Adobe Marketing Cloud Android SDK 4.x for Marketing Cloud Solutions

Transcription

1 Adobe Marketing Cloud Android SDK 4.x for Marketing Cloud Solutions

2 Contents Android SDK 4.x for Marketing Cloud Solutions...5 Release Notes for Android SDK 4.x for Marketing Cloud Solutions...6 Getting Started...8 Before You Start...8 Core Implementation and Lifecycle...9 Processing Rules and Context Data...11 Configuration...13 ADBMobile JSON Config...13 Override the ADBMobile JSON Config Path...20 Hit Batching...20 Configuration Methods...21 Analytics...26 Track App States...26 Track App Actions...27 Track App Crashes...29 Timed Actions...31 Visitor Lifetime Value...32 Products Variable...33 Products Variable with Merchandising evars and Product-Specific Events...34 Event Serialization...35 Video Analytics...35 Postbacks...39 Postbacks Example...40 Analytics Methods...41 Last updated 9/15/2015 Android SDK 4.x for Marketing Cloud Solutions

3 Contents Acquisition...45 Mobile App Acquisition...45 Acquisition Methods...46 Messaging...47 In-app Messaging...47 Push Messaging...49 Location...51 Geo-Location and Points of Interest...51 Beacon tracking...53 Target...55 Target Configuration...55 Target Methods...55 Marketing Cloud...58 Marketing Cloud Visitor ID Configuration...58 Marketing Cloud Visitor ID Service Methods...58 Audience Manager...60 Audience Manager Configuration...60 Audience Manager Methods...60 Lifecycle Metrics...62 Wearables...67 Android Wearable Implementation...67 Android SDK Reference...70 App IDs...70 Visitor Tracking Between an App and Mobile Web...70 Last updated 9/15/2015 Android SDK 4.x for Marketing Cloud Solutions

4 Android Widgets...71 Opt-Out and Privacy Settings...72 Using Bloodhound to Test Mobile Applications...73 PhoneGap Plug-in...74 PhoneGap Plug-in Methods x Migration Guide...80 Documentation Updates...84 Historical Release Notes...86 Contact and Legal Information...88 Last updated 9/15/2015 Android SDK 4.x for Marketing Cloud Solutions

5 Android SDK 4.x for Marketing Cloud Solutions 5 Android SDK 4.x for Marketing Cloud Solutions Android SDK 4.x for Marketing Cloud Solutions lets you measure native Android applications, deliver targeted content within your app, and leverage and collect audience data through audience management. Last Update: September 17, 2015 Version 4.6 of the SDK is now available! See Release Notes for Android SDK 4.x for Marketing Cloud Solutions. This SDK supports Android 2.2 or later. Note: In version 4.2 and later, all hits are now sent using HTTP POST. This has no impact on the data that is collected or reported, but you'll need to use a packet analyzer that supports inspecting POST data to view hits, such as the Bloodhound 3 beta. If you are upgrading from a previous version, you'll want to take a look at the 4.x Migration Guide. Adobe Mobile Services Adobe Mobile services provides a new UI that brings together mobile marketing capabilities for mobile applications from across the Adobe Marketing Cloud. Initially, the Mobile service provides seamless integration of app analytics and targeting capabilities from the Adobe Analytics and Adobe Target solutions. Learn more at Adobe Mobile Services documentation.

6 Release Notes for Android SDK 4.x for Marketing Cloud Solutions 6 Release Notes for Android SDK 4.x for Marketing Cloud Solutions Release notes and known issues for Android SDK 4.x for Marketing Cloud Solutions. This section contains the following information: Current Release Notes Marketing Cloud Release Notes, Documentation Updates, and Historical Release Notes Current Release Notes The Android SDK version 4.6 (September 17, 2015) includes the following changes: Feature Push Messaging to Analytics Segments Adobe Mobile Services and the Adobe Mobile SDK allow you to send push messages to Analytics segments. The SDK also allows you to easily report users that have opened your app as a result of opening the push message. See Push Messaging. Acquisition Methods Allows developers to start an app acquisition campaign as if the user had clicked a link. This is helpful for creating manual acquisition links and handling the app store redirect yourself. See Acquisition. Postbacks Postback Signals let you send data collected by the SDK to a separate third-party server. Leveraging the same triggers and traits you use to display an in-app message, you can configure the SDK to send customized data to a third-party destination. See Postbacks. Identifiers Added the following new identifiers: The setpushidentifier method in Configuration Methods. The submitadvertisingidentifiertask method in Configuration Methods. Marketing Cloud Release Notes, Documentation Updates, and Historical Release Notes In addition to the notes for each release, the following resources provide additional information: Resource Marketing Cloud Release Notes Documentation Updates View the latest release notes for the Adobe Marketing Cloud solutions. View detailed information about updates to this guide that might not be included in these release notes.

7 Release Notes for Android SDK 4.x for Marketing Cloud Solutions 7 Resource Historical Release Notes View information about new features and enhancements in previous releases of Android SDK 4.x for Marketing Cloud Solutions.

8 Getting Started 8 Getting Started Information to help you get starting with the Android SDK for Marketing Cloud Solutions. Before You Start Complete these steps to configure a report suite to collect app data. If you are an Analytics administrator: Complete the steps in Set up your App in Adobe Mobile Services to configure a report suite to collect mobile app data. After you complete these steps, create an Analytics account for each app developer and give them access to view the report suite(s) you created. If you are an app developer: Send a link to this page to your Analytics administrator and ask him or her to complete these steps. After the report suite is configured, your administrator will provide you with a login you can use to complete steps in Download the SDK and Testing Tools. This section contains the following information: Set up your App in Adobe Mobile Services Download the SDK and Testing Tools Set up your App in Adobe Mobile Services Note: You must be an Analytics Administrator to complete these steps. Adobe Mobile services is the primary reporting interface for mobile app analytics and targeting. After you complete these steps you can download a configuration file that is pre-configured with your data collection server, report suite, and many other settings. First, sign in at Two ways exist for you to sign in: Marketing Cloud: Sign in to the Marketing Cloud with your Adobe ID. This method assumes that your company has been provisioned in the Marketing Cloud, and you have linked your Analytics account. (If you are unsure, use your existing Adobe Analytics account.) Adobe Analytics: Click Sign in with Analytics provide your Analytics company, username, and password. Complete the following steps to set up a new report suite to collect app data and to define an app in Adobe Mobile services. 1. Click the Create New App button. (If you don't see this button, click Manage Apps > Add instead.) 2. From the Report Suite drop-down, select New Report Suite. 3. Provide the name of your App and select a unique report suite ID, for example, mycomobileappdev. Note that you'll need to set up separate report suites and apps for the development and production versions, so you can repeat these steps when you are ready to set up the production version. 4. Leave Mobile App Template selected. This template enables timestamps to collect offline data and activates the mobile solution variables to capture lifecyle metrics. 5. Select your Timezone and Currency, and then click Save. Download the SDK and Testing Tools After an Analytics Administrator has completed the previous steps, complete the following to download the mobile SDKs. 1. Browse to and log-in the with the account your administrator created for you. 2. Select your App from the drop-down list in the left navigation. 3. Click the Gear icon to open the App configuration.

9 Getting Started 9 4. Scroll to bottom of the page and download the SDK, Bloodhound, and the Sample App for your platform. A config file for your App is included in the SDK download automatically, so you don't need to download that separately unless you have already downloaded the SDK and you just want to get updated settings. Core Implementation and Lifecycle Information to help you implement the Android library and collect lifecyle metrics (launches, upgrades, sessions, engaged users, and so on). This section contains the following information: Core Implementation and Lifecycle Add the SDK and Config File to your Project (IntelliJ IDEA) Add the SDK and Config File to your Project (Eclipse) Add App Permissions Implement Lifecycle Metrics Get the SDK Requires Android 2.2 or later. Complete the steps in Before You Start to set up a development report suite and download a pre-populated version of the configuration file. After unzipping the [Your_App_Name_]AdobeMobileLibrary-4.*-Android.zip download file, you'll have the following software components: adobemobilelibrary.jar: Library designed for use with Android devices and simulators. ADBMobileConfig.json: SDK configuration file customized for your app. Note: If you download the SDK outside of the Adobe Mobile services UI, the ADBMobileConfig.json must be manually configured. If you are new to Analytics and the mobile SDK, we highly recommend using the steps in Before You Start to set up a development report suite and download a pre-populated version of the configuration file. Configuration is not difficult, but it can be a source of frustration when you are getting started. Add the SDK and Config File to your Project (IntelliJ IDEA) For IntelliJ users: 1. Add the ADBMobileConfig.json file to the assets folder of your project. 2. Right click your project in the Project navigation panel. 3. Select Open Module Settings. 4. Select Libraries under Project Settings. 5. Click + icon to add a new library. 6. Select Java and navigate to the adobemobilelibrary.jar file. 7. Select the modules where you plan to use the mobile library. 8. Click Apply, and then OK to close the Module Settings window. Add the SDK and Config File to your Project (Eclipse) For Eclipse users: 1. Add the ADBMobileConfig.json file to the assets folder of your project.

10 Getting Started In the Eclipse IDE, right-click on the project name. 3. Select Build Path > Add External Archives. 4. Select adobemobilelibrary.jar. 5. Click Open. 6. Right-click the project again, then select Build Path > Configure Build Path. 7. Click the Order and Export tab. 8. Ensure that adobemobilelibrary.jar is selected. Add App Permissions The AppMeasurement Library requires the following permissions to send data and record offline tracking calls: INTERNET ACCESS_NETWORK_STATE To add these permissions, add the following lines to your AndroidManifest.xml file (in the application project directory): <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.access_network_state" /> Implement Lifecycle Metrics After you enable lifecycle, each time your app is launched, a single hit is sent to measure launches, upgrades, sessions, engaged users, and many other Lifecycle Metrics. In your main activity: 1. Import the library: import com.adobe.mobile.*; 2. Within the oncreate method, allow the SDK access to your application context using public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.main); // Allow the SDK access to the application context Config.setContext(this.getApplicationContext()); 3. Within the onresume function, begin collecting lifecycle public void onresume() { Config.collectLifecycleData(this); // -or- Config.collectLifecycleData(this, contextdata); 4. Within the onpause function, pause collecting lifecycle public void onpause() { Config.pauseCollectingLifecycleData(); In Each activity within your application: 1. Import the library: import com.adobe.mobile.*;

11 Getting Started Within the onresume function, begin collecting lifecycle public void onresume() { Config.collectLifecycleData(this); // -or- Config.collectLifecycleData(this, contextdata); 3. Within the onpause function, pause collecting lifecycle public void onpause() { Config.pauseCollectingLifecycleData(); It is essential that you add these calls to every activity to ensure accurate crash reporting. Including Additional Data with Lifecycle Calls To include additional data with lifecycle metric calls, pass an additional parameter to collectlifecycledata that contains context public void onresume() { HashMap<String, Object> contextdata = new HashMap<String, Object>(); contextdata.put("myapp.category", "Game"); Config.collectLifecycleData(this, contextdata); Additional context data values that are sent with collectlifecycledata must be mapped to custom variables in Adobe Mobile services: Other Lifecycle Metrics are collected automatically. What to do next: Track App States Track App Actions Processing Rules and Context Data Processing rules are used to copy the data you send in context data variables to evars, props, and other variables for reporting. Processing Rules Summit 2013 Processing Rules Help

12 Getting Started 12 Become authorized to use Processing Rules We recommend grouping your context data variables using "namespaces", as it helps you keep logical ordering. For example, if you want to collect info about a product, you might define the following variables: "product.type":"hat" "product.team":"mariners" "product.color":"blue" Context data variables are sorted alphabetically in the processing rules interface, so namespaces let you quickly see variables that are in the same namespace. We recommend that you avoid naming context data keys using the evar or prop number: "evar1":"jimbo" This might make it slightly easier when you perform the one time mapping in processing rules, but you lose readability during debugging and future code updates can be more difficult. Instead, we strongly recommend using descriptive names for keys and values: "username":"jimbo" Context variables that define counter events should be set to 1: "logon":"1" Context data variables that define incrementor events can have the event as the key and the amount to increment as the value: "levels completed":"6" Note: Adobe reserves the namespace "a.". Aside from that small restriction, context data variables just need to be unique in your login company to avoid collisions.

13 Configuration 13 Configuration Information to help you configure the Android SDK, including JSON configuration, hit batching, and SDK methods. ADBMobile JSON Config Information to help you use the ADBMobile JSON Config file. ADBMobileConfig.json Config File Reference The same config file can be used for your app across multiple platforms. ios: The ADBMobileConfig.json can be placed anywhere that it is accessible in your bundle. Android: The ADBMobileConfig.json must be placed in the assets folder. Variable acquisition backdatesessioninfo batchlimit Minimum SDK Version Enables mobile app acquisition. server - Acquisition server that is checked at the initial launch for an acquisition referrer. appid - Generated ID that uniquely identifies this app on the acquisition server. If this section is missing, you need to enable Mobile App acquisition and then re-download the SDK configuration file. See also: referrertimeout Enables/disables the ability for the Adobe SDK to backdate session info hits. Session info hits currently consist of crashes and session length. The default is false. When enabled, the Adobe SDK will backdate the session info hit to 1 second after the last hit of the previous session. This means that crashes and session data will correlate with the correct date in which they happened. This does, however, have a side effect in which it might create a visit for the backdated hit. One hit will be backdated on every new launch of the application. Be aware that backdated session hit information is sent in a session info server call. Additional server calls may apply. When disabled, the Adobe SDK will attach the session info to the current lifecycle. Threshold for number of hits to be sent in consecutive calls. For example, if batchlimit is set to 10, each hit prior to the 10th hit will be stored in the queue. Once the 10th hit comes in, all 10 hits will be sent consecutively Default: 0 (Batching not enabled) Requires offlineenabled = true

14 Configuration 14 Variable charset clientcode lifecycletimeout messages offlineenabled Minimum SDK Version Defines the character set you are using for the data sent to Analytics. The charset is used to convert incoming data into UTF-8 for storage and reporting. See Using the charset Property. (Required by Target) Your assigned client code. Default: 300 seconds Specifies the length of time, in seconds, that must elapse between app launches before the launch is considered a new session. This timeout also applies when your application is sent to the background and reactivated. The time that your app spends in the background is not included in the session length. Generated automatically by Adobe Mobile services, defines the settings for in-app messaging. For details, see Messages description. When enabled, hits are queued while the device is offline and sent later when the device is online. Your report suite must be timestamp-enabled to use offline tracking. Default: false Important: If timestamps are enabled on your report suite, your offlineenabled configuration property must be true. if your report suite is not timestamp enabled, your offlineenabled configuration property must be false. If this is not configured correctly, data will be lost. If you are not sure if a report suite is timestamp enabled, contact Customer Care or download the configuration file from Adobe Mobile services. org poi If you are currently reporting AppMeasurement data to a report suite that also collects data from JavaScript, you might need to set up a separate report suite for mobile data, or include a custom timestamp on all JavaScript hits using the s.timestamp variable. Specifies the Marketing Cloud org ID for the visitor ID service. Each POI array holds the POI name, latitude, longitude, and radius (in meters) for the area of the point. The POI name can be any string. When a tracklocation call is sent, if the current coordinates are within a defined POI, a context data variable is populated and sent with the tracklocation call. "poi" : [ ] ["san francisco", , ,7000], ["santa cruz", , ,600] Note: Starting in version 4.2, POIs are defined in the Adobe Mobile interface and then synchronized dynamically to the app configuration file. This synchronization requires the analytics.poi setting: analytics.poi : /yourfile.json,

15 Configuration 15 Variable Minimum SDK Version If this is not configured, the ADBMobile.json file must be updated to include this line. See "Before you Start" to download an updated configuration file. postback 4.6 The definition for the "callback" message template is shown below: "payload": { "templateurl": "", // required - will be token-expanded prior to being sent "templatebody": "", // optional - if this length > 0 POST will be used as transport method. This is a base64 encoded blob, which will be decoded and token-expanded prior to being sent. "contenttype": "", // optional - if this is length > 0 and POST type is selected this will be set as the Content-Type header. if this is not supplied for a POST request, the default will be "application/x-www-form-urlencoded" "timeout": 0 // optional - number of seconds to wait before timing out. Default is 2. The payload object in the code is an example payload for a message definition that would go in ADBMobileConfig.json. For more information, see the applicable topic: Android: Postbacks ios: Postbacks privacydefault referrertimeout remotes Default: optedin optedin - hits are sent immediately. optedout - hits are discarded. optunknown - If your report suite is timestamp-enabled, hits are saved until the privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). If your report suite is not timestamp-enabled, hits are discarded until the privacy status changes to opt in. This sets the initial value only. If this value is ever set or changed in code, then the new value is used going forward until it is changed, or the app is uninstalled and then reinstalled. (Required by acquisition) Number of seconds the SDK waits for acquisition referrer data on the initial launch before timeout. If you are using acquisition, we recommend a 5 second timeout. If set to 0 or if not included, the SDK does not wait for acquisition data and acquisition metrics are not tracked. Configured automatically, defines the Adobe hosted endpoints for dynamic configuration files. The last update time of each configuration file is checked against the current version at each launch, and any updates are downloaded and saved. analytics.poi - endpoint for hosted POI configuration.

16 Configuration 16 Variable rsids server ssl Minimum SDK Version messages - endpoint for hosted in-app message configuration. (Required by Analytics) One or more report suites to receive Analytics data. Multiple report suite IDs should be comma-separated with no space between. "rsids" : "rsid" "rsids" : "rsid1,rsid2" (Required by Analytics and/or Audience Management). Analytics or Audience Management server, based on the parent node. This variable should be populated with the server domain, without an " or protocol prefix. The protocol prefix is handled automatically by the library based on the ssl variable. If ssl is true, a secure connection is made to this server. If ssl is false, a non-secure connection is made to this server. Default: false Enables (true) or disables (false) sending measurement data via SSL (HTTPS). The definition for the "callback" message template is shown below: "payload": { "templateurl": "", // required - will be token-expanded prior to being sent "templatebody": "", // optional - if this length > 0 POST will be used as transport method. This is a base64 encoded blob, which will be decoded and token-expanded prior to being sent. "contenttype": "", // optional - if this is length > 0 and POST type is selected this will be set as the Content-Type header. if this is not supplied for a POST request, the default will be "application/x-www-form-urlencoded" "timeout": 0 // optional - number of seconds to wait before timing out. Default is 2. The payload object in the code is an example payload for a message definition that would go in ADBMobileConfig.json. For more information, see the applicable topic: Android: Third-Party Callback ios: Third-Party Callback timeout 4.0 Determines how long Target waits for a response. The following is an example of an ADBMobileConfig.json file: { "version": " T19:18:28.169Z", "marketingcloud" : { "org": "016D5C175213CCA80A490D05@AdobeOrg"

17 Configuration 17, "target": { "clientcode": "", "timeout": 5, "audiencemanager": { "server": "", "acquisition": { "server": "c00.adobe.com", "appid": "10a77a60192fbb628376e1b1daeeb65debf934e2c807e067ceb2963a41b165ee", "analytics": { "rsids": "coolapp", "server": "my.coolapp.com", "ssl": false, "offlineenabled": true, "charset": "UTF-8", "lifecycletimeout": 300, "privacydefault": "optedin", "batchlimit": 0, "referrertimeout": 5, "poi": [ ["san francisco", , ,7000], ["santa cruz", , ,600] ], "messages": [ { "messageid": "cb a a-a889-9dbeb451f8ae", "template": "fullscreen", "payload": { "html": "<!DOCTYPE html><html><head><meta charset=\"utf-8\" /><title></title><style></style></head><body><iframe src=\" frameborder=\"0\"></iframe></body></html>", "showoffline": false, "showrule": "always", "enddate": , "startdate": 0, "audiences": [], "triggers": [ { "key": "pev2", "matches": "eq", "values": [ "AMACTION:custom" ] ] ], "remotes": { "analytics.poi": " "messages": " Messages description The messages node is generated automatically by Adobe Mobile services and typically does not need to be manually changed. The following description is provided for troubleshooting purposes: "messageid"

18 Configuration 18 Generated ID, required "template" "alert", "fullscreen", or "local" required "showoffline" true or false default is false "showrule" "always", "once", or "untilclick" required "enddate" number of seconds since Jan 1, 1970 default is "startdate" number of seconds since Jan 1, 1970 default is 0 "payload" "html" fullscreen template only, required html defining the message "image" fullscreen only, optional url to the image to be used for a fullscreen image "altimage" fullscreen only, optional name of the bundled image to use if the url specified in image is unreachable "title" fullscreen and alert, required title text for a fullscreen or alert message "content" alert and local notification, required

19 Configuration 19 sub-text for an alert message, or notification text for a local notification message "confirm" alert, optional text used in the confirm button "cancel" alert, required text used in the cancel button "url" alert, optional url action to load if the confirm button is clicked "wait" local notification, required amount of time to wait (in seconds) to post the local notification after matching its criteria "audiences" array of objects that defines how the message should be shown "key" variable name to look for in the hit, required "matches" type of matcher used when doing the comparison eq = equals ne = does not equal co = contains nc = does not contain sw = starts with ew = ends with ex = exists nx = does not exist lt = less than le = less than or equals gt = greater than ge = greater than or equals "values" an array of values used to match against the value of the variable named in

20 Configuration 20 key with the matcher type in matches "triggers" same as audiences, but this is the action instead of the audience "key" "matches" "values" Override the ADBMobile JSON Config Path Load a different ADBMobile JSON Config file when the application starts. The Config.overrideConfigStream(configInput) method enables you to specify the path to a different ADBMobile.json configuration file when the application starts. This method must be called before any other Marketing Cloud SDK call (before Config.collectLifecycleData() ), likely in the oncreate method of your first loaded activity. Calling this method with a different path causes a one-time override of the configuration file until the application is closed. try { InputStream configinput = getassets().open("examplejsonfile.json"); Config.overrideConfigStream(configInput); catch (IOException ex) { // do something with the exception if needed Hit Batching Hit batching allows applications with offline tracking enabled to hold hits from being sent until the number of hits in the queue pass a configurable limit. Requires SDK version 4.1 or later To enable hit batching, you need to update your ADBMobileConfig.json and specify a value for batchlimit: "analytics": { "batchlimit": 5,... When set to a number higher than 0, the SDK queues the number of hits equal to batchlimit. After this threshold is passed, all hits in the queue are sent. The following methods are used in conjunction with hit batching: Analytics.getQueueSize() - Returns a long with the number of hits currently in the hit batching queue. Analytics.sendQueuedHits() - Forces the library to send all hits in the queue no matter how many are currently queued. Analytics.clearQueue() - Clears all hits from the queue without sending them. : Offline tracking must be enabled to use hit batching.

21 Configuration 21 Configuration Methods List of methods provided by the Android library. This section contains the following information: Initial Configuration SDK Settings (Config Class) Initial Configuration The following method must be called once in the oncreate() method of your main activity. Method public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.main); Config.setContext(this.getApplicationContext()); SDK Settings (Config Class) Method getversion Returns the current version of the Adobe Mobile library. public static String getversion(); String libraryversion = Config.getVersion(); getprivacystatus Returns the enum representation of the privacy status for current user. MOBILE_PRIVACY_STATUS_OPT_IN - hits are sent immediately. MOBILE_PRIVACY_STATUS_OPT_OUT - hits are discarded. MOBILE_PRIVACY_STATUS_UNKNOWN - If your report suite is timestamp-enabled, hits are saved until the privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). If your report suite is not timestamp-enabled, hits are discarded until the privacy status changes to opt in. Default: The default value is set in ADBMobileConfig.json public static MobilePrivacyStatus getprivacystatus(); MobilePrivacyStatus privacystatus = Config.getPrivacyStatus(); setprivacystatus Sets the privacy status for the current user to status. Set to one of the following values:

22 Configuration 22 Method MOBILE_PRIVACY_STATUS_OPT_IN - hits are sent immediately. MOBILE_PRIVACY_STATUS_OPT_OUT - hits are discarded. MOBILE_PRIVACY_STATUS_UNKNOWN - If your report suite is timestamp-enabled, hits are saved until the privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). If your report suite is not timestamp-enabled, hits are discarded until the privacy status changes to opt in. public static void setprivacystatus(mobileprivacystatus status); Config.setPrivacyStatus(MobilePrivacyStatus.MOBILE_PRIVACY_STATUS_OPT_IN); getlifetimevalue Returns the lifetime value of the current user. Default: 0 public static BigDecimal getlifetimevalue(); BigDecimal currentlifetimevalue = Config.getLifetimeValue(); getuseridentifier Returns the custom user identifier if a custom identifier has been set. Returns null if a custom identifier is not set. Default: null Note: If your app upgrades from the Marketing Cloud 3.x to 4.x SDK, the previous visitor ID (either custom or automatically generated) is retrieved and stored as the custom user identifier. This preserves visitor data between upgrades of the SDK. For new installations on the 4.x SDK, user identifier is null until set. public static String getuseridentifier(); String userid = Config.getUserIdentifier(); setuseridentifier Sets the user identifier to identifier. public static void setuseridentifer(string identifier); Config.setUserIdentifier("billybob"); getdebuglogging Returns the current debug logging preference. Default: false

23 Configuration 23 Method public static Boolean getdebuglogging(); Boolean debugging = Config.getDebugLogging(); setdebuglogging Sets the debug logging preference to debuglogging. public static void setdebuglogging(boolean debuglogging); Config.setDebugLogging(true); collectlifecycledata Indicates to the SDK that lifecycle data should be collected for use across all solutions in the SDK. See Lifecycle Metrics. public static void collectlifecycledata(final Activity activity, final Map<String, Object> contextdata); Without extra context protected void onresume() { super.onresume(); Config.collectLifecycleData(this); With extra context public void onresume() { HashMap<String, Object> contextdata = new HashMap<String, Object>(); contextdata.put("myapp.category", "Game"); Config.collectLifecycleData(this, contextdata); collectlifecycledata (Activity activity) (4.2 or later) Indicates to the SDK that lifecycle data should be collected for use across all solutions in the SDK. See Lifecycle Metrics. public static void collectlifecycledata(final Activity protected void onresume() { super.onresume(); // assumes being called in an Activity class Config.collectLifecycleData(this);

24 Configuration 24 Method pausecollectinglifecycledata Indicates to the SDK that your app is paused, so that lifecycle metrics are calculated correctly. For example, on pause collects a timestamp to determine previous session length. This also sets a flag so that lifecycle correctly knows that the app did not crash. See Lifecycle Metrics. public static void protected void onpause() { super.onpause(); Config.pauseCollectingLifecycleData(); setsmalliconresourceid(int resourceid) (4.2 or later) Set the small icon that will be used for notifications created by the SDK. This icon will show up in the status bar. This will also be the secondary image shown when the user sees the full notification in the notification center. public static void setsmalliconresourceid(final int resourceid); Config.setSmallIconResourceId(R.drawable.appIcon); setlargeiconresourceid(int resourceid) (4.2 or later) Set the large icon that will be used for notifications created by the SDK. This icon will be the primary image shown when the user sees the full notification in the notification center. public static void setlargeiconresourceid(final int resourceid); Config.setLargeIconResourceId(R.drawable.appIcon); overrideconfigstream(inputstream configinput) (4.2 or later) Lets you load a different ADBMobile JSON Config file when the application starts. The different configuration is used until the application is closed. public static void overrideconfigstream(final InputStream configinput); try { InputStream configinput = getassets().open("examplejsonfile.json"); Config.overrideConfigStream(configInput); catch (IOException ex) { // do something with the exception if needed setpushidentifier Sets the device token for push notifications.

25 Configuration 25 Method public static void setpushidentifier(final String registrationid);... // note: the code to retreive the push token must run in the background InstanceID instanceid = InstanceID.getInstance(getApplicationContext()); String token = instanceid.gettoken(" ", GoogleCloudMessaging.INSTANCE_ID_SCOPE, null); Config.setPushIdentifier(token);... submitadvertisingidentifiertask Provide a Callable to the SDK that returns the string of the Advertising Identifier returned from Google Play Services. The SDK runs this task on a background thread and sets an internal variable for Advertising Identifier based on the value returned from the Callable. Note, if you want to use Advertising Identifier in Acquisition or Lifecycle, you must call it before calling Config.collectLifecycleData. public static void submitadvertisingidentifiertask(final Callable<String> public void onresume() { super.onresume(); final Callable<String> task = new Callable<String>() public String call() throws Exception { AdvertisingIdClient.Info idinfo; String adid = null; Context appcontext = CLASSNAME.this.getApplicationContext(); try { idinfo = AdvertisingIdClient.getAdvertisingIdInfo(appContext); if (idinfo!= null) { adid = idinfo.getid(); catch (Exception ex) { Log.e("Error", ex.getlocalizedmessage()); ; return adid; Config.submitAdvertisingIdentifierTask(task); Config.collectLifecycleData(this);

26 Analytics 26 Analytics Information to help you use the Android SDK with Adobe Analytics. Track App States States are the different screens or views in your application. Each time a new state is displayed in your application (for example, when a user navigates from the home page to the news feed), you should send a trackstate call. In Android, trackstate is typically called each time a new Activity is loaded. How to Track Prerequisites: Add the library to your project and implement lifecycle. 1. Import the library: import com.adobe.mobile.*; 2. Within the oncreate function, call trackstate to send a hit for this state public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.main); // Adobe - track when this state loads Analytics.trackState("State Name", null); The "State Name" is reported in the View State variable in Adobe Mobile services, and a view is recorded for each trackstate call. In other Analytics interfaces, View State is reported as Page Name and state views is reported as page views. Sending Additional Data In addition to the "State Name", you can send additional context data with each track action public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.main); // Adobe - track when this state loads HashMap<String, Object> examplecontextdata = new HashMap<String, Object>(); examplecontextdata.put("myapp.login.loginstatus", "logged in"); Analytics.trackState("Home Screen", examplecontextdata); Context data values must be mapped to custom variables in Adobe Mobile services:

27 Analytics 27 App State Reporting States are typically viewed using a pathing report so you can see how users navigate your app, and which states are viewed most. Adobe Mobile Services Adobe Analytics Ad hoc analytics View States Report. This report is based on the paths users took through your application. For example, Login > Home > Settings, or Home > Feed. States can be viewed anywhere Pages can be viewed, such as the Pages Report, Page Views report, and Path Reports. States can be viewed anywhere Pages can be viewed using the Page dimension, Page Views metric, Path Reports. Track App Actions Actions are the events that occur in your app that you want to measure. Each action has one or more corresponding metrics that are incremented each time the event occurs. For example, you might send a trackaction call for each new subscription, each time an article is viewed, or each time a level is completed. Actions are not tracked automatically, you must call trackaction when an event you want to track occurs, and then map the action to a custom event. How to Track Prerequisites: Add the library to your project and implement lifecycle. 1. Import the library: import com.adobe.mobile.*; 2. When the action that you want to track occurs in your app, call trackaction to send a hit for this action: Analytics.trackAction("myapp.ActionName", null); 3. In Adobe Mobile services, select your app and click Manage App Settings. 4. Click Manage Variables and Metrics and then click the Custom Metrics tab. 5. Map the context data name defined in your code ("myapp.actionname " in the example) to a custom event.

28 Analytics 28 You can also set a prop to hold all action values by mapping a custom prop with a name like "Custom Actions" and setting the value to 'a.action'. Sending Additional Data In addition to the action name, you can send additional context data with each track action call: HashMap<String, Object> examplecontextdata = new HashMap<String, Object>(); examplecontextdata.put("myapp.social.socialsource", "Twitter"); Analytics.trackAction("myapp.SocialShare", examplecontextdata); Context data values must be mapped to custom variables in Adobe Mobile services:

29 Analytics 29 Action Reporting Interface Adobe Mobile Services Report Action Paths Report. View the order in which actions occur in your app. You can also click Customize on any report to view actions ranked, trended, or in a breakdown report. Apply a filter to view actions for a specific segment. Marketing reports & analytics Ad hoc analytics Custom Event Report. After an action is mapped to a custom event, you can view mobile events similar to all other Analytics events. Custom Event Report. After an action is mapped to a custom event, you can view mobile events similar to all other Analytics events. Track App Crashes App crashes are tracked as part of lifecycle metrics. To track crashes, add the library to your project and implement lifecycle. When lifecycle metrics are implemented, a call is made to Config.collectLifecycleData in the OnResume method of each activity. In the onpause method, a call is made to Config.pauseCollectingLifeCycleData. Inside of the pausecollectinglifecycledata, a flag is set to indicate a graceful exit. When the app is relaunched or resumed, collectlifecycledata checks this flag for a graceful exit. If the app did not exit successfully (as determined by the flag status), an a.crashevent context data is sent with the next call and a crash event is reported. To ensure accurate crash reporting, you must call the pausecollectinglifecycledata inside of the onpause method of each activity. To understand why this is essential, it is helpful to understand the Android activity lifecycle:

30 Analytics 30 If a call is not made to pausecollectinglifecycledata before your app is paused, when the user returns to your app or when your app is re-launched, the SDK reports a crash event since the flag is not set to indicate a graceful exit. If Config.collectLifecycleData is called twice in a row during the same session (without a call to pausecollectinglifecycledata in between), then a crash is reported on every call after the first. For example, if you forget to add a call to pausecollectinglifecycledata to onpause for an activity, then a crash might be reported if the app is backgrounded during that activity. (See for more information on Android activity lifecycle. The Android lifecycle image that appears on this page was created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License)

31 Analytics 31 Timed Actions Timed actions let you measure in-app time and total time between the start and end of an action. The SDK calculates the amount of time in session and the total time (cross-session) it takes for the action to be completed. This can be used to define segments to compare on time to purchase, pass level, checkout flow, and so on. The following metrics are reported for timed actions: Total # of seconds in app between start and end - cross sessions Total # of seconds between start and end (clock time) An optional callback allows you to take additional action when the timed action completes: Run code and add any logic - optional custom logic based on duration results. Add context data prior to passing in durations. Cancel hit and durations not yet sent. How to Track Prerequisites: Add the library to your project and implement lifecycle. 1. Import the library: import com.adobe.mobile.*; 2. Call tracktimedactionstart and provide a timed action name and optional context data. HashMap cdata = new HashMap<String, Object>(); cdata.put("experiencename", experience); Analytics.trackTimedActionStart("TimeUntilPurchase", cdata); 3. (Optional) At any point, you can call tracktimedactionupdate with the timed action name to add additional context data. HashMap cdata = new HashMap<String, Object>(); cdata.put("myapp.imageliked", imagename); Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata); 4. When the event completes, call tracktimedactionend and pass the timed action name and TimedActionBlock (callback) which will look up all data and calculate durations. Timed event metrics are saved in mobile solution variables for automatic reporting. Analytics.trackTimedActionEnd("TimeUntilPurchase", cdata); Sending Additional Data In addition to the timed action name, you can send additional context data with the action start and action update calls: HashMap cdata = new HashMap<String, Object>(); cdata.put("myapp.imageliked", imagename); Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata); Context data values must be mapped to custom variables in Adobe Mobile services:

32 Analytics 32 Examples // Timed Action Start Example HashMap cdata = new HashMap<String, Object>(); cdata.put("experiencename", experience); Analytics.trackTimedActionStart("TimeUntilPurchase", cdata); // Timed Action Update Example cdata = new HashMap<String, Object>(); cdata.put("imageliked", imagename); Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata); // Timed Action End Example Analytics.trackTimedActionEnd("TimeUntilPurchase", null); // Timed Action End Example with Callback Analytics.trackTimedActionEnd("TimeUntilPurchase", new Analytics.TimedActionBlock<Boolean>() public Boolean call(long inappduration, long totalduration, Map<String, Object> contextdata) { contextdata.put("purchaseitem", "Item453"); return true; // return true to send the hit, false to cancel ); Visitor Lifetime Value Lifetime value lets you measure and target on a lifetime value for each user. Each time you send in a value with tracklifetimevalueincrease, the value is added to the existing value. Lifetime value is stored on device and can be retrieved at any time by calling lifetimevalue. This can be used to store lifetime purchases, ad views, video completes, social shares, photo uploads, and so on. How to Track Prerequisites: Add the library to your project and implement lifecycle. 1. Import the library: import com.adobe.mobile.*; 2. Call tracklifetimevalueincrease with the amount to increase the value: Analytics.trackLifetimeValueIncrease(BigDecimal.valueOf(5.0), null);

33 Analytics 33 Sending Additional Data In addition to the lifetime value, you can send additional context data with each track action call: HashMap cdata = new HashMap<String, Object>(); cdata.put("myapp.imageliked", imagename); Analytics.trackLifetimeValueIncrease(BigDecimal.valueOf(5.0), cdata); Context data values must be mapped to custom variables in Adobe Mobile services: Products Variable The products variable cannot be set using processing rules. In the mobile SDK, you must use a special syntax within the context data parameter to set products directly on the server call. To set the products variable, set a context data key to "&&products", and set the value using the syntax defined for the products variable: cdata.put("&&products", "Category;Product;Quantity;Price[,Category;Product;Quantity;Price]"); For example: //create a context data dictionary HashMap cdata = new HashMap<String, Object>(); // add products, a purchase id, a purchase context data key, and any other data you want to collect. // Note the special syntax for products cdata.put("&&products", ";Running Shoes;1;69.95,;Running Socks;10;29.99"); cdata.put("myapp.purchase", "1"); cdata.put("myapp.purchaseid", " "); // send the tracking call - use either a trackaction or TrackState call. // trackaction example: Analytics.trackAction("purchase", cdata); // trackstate example: Analytics.trackState("Order Confirmation", cdata); Note that products is set directly on the image request, and the other variables are set as context data:

34 Analytics 34 All context data variables must be mapped using processing rules: You do not need to map the products variable using processing rules since it is set directly on the image request by the SDK. Products Variable with Merchandising evars and Product-Specific Events An example of the products variable with Merchandising evars and product-specific events. //create a context data dictionary HashMap cdata = new HashMap<String, Object>(); // add products, a purchase id, a purchase context data key, and any other data you want to collect. // Note the special syntax for products cdata.put("&&events", "event1"); cdata.put("&&products", ";Running Shoes;1;69.95;event1=5.5;eVar1=Merchandising,;Running Socks;10;29.99"); cdata.put("myapp.purchase", "1"); cdata.put("myapp.purchaseid", " "); // send the tracking call - use either a trackaction or TrackState call. // trackaction example: Analytics.trackAction("purchase", cdata);