Release Notes for Android SDK 4.x for Marketing Cloud Solutions
122
Adobe ® Marketing Cloud Android SDK 4.x for Marketing Cloud Solutions
Transcript of Release Notes for Android SDK 4.x for Marketing Cloud Solutions
Adobe® Marketing Cloud
Android SDK 4.x for Marketing Cloud Solutions
Contents
Release Notes....................................................................................................................5
Android SDK 4.x for Marketing Cloud Solutions............................................................7
Getting Started.................................................................................................................8Before You Start..................................................................................................................................................................8
Core Implementation and Lifecycle.........................................................................................................................10
Processing Rules and Context Data..........................................................................................................................12
Migrating to the Android 4.x Library........................................................................................................................13
Configuration..................................................................................................................18ADBMobile JSON Config...............................................................................................................................................18
Override the ADBMobile JSON Config Path....................................................................................................................................26
Hit Batching.......................................................................................................................................................................26
Configuration Methods.................................................................................................................................................27
Lifecycle Metrics.............................................................................................................33
Analytics..........................................................................................................................38Track App States..............................................................................................................................................................38
Track App Actions...........................................................................................................................................................39
Track App Crashes...........................................................................................................................................................41
Timed Actions...................................................................................................................................................................44
Visitor Lifetime Value.....................................................................................................................................................45
Products Variable............................................................................................................................................................46
Products Variable with Merchandising eVars and Product-Specific Events........................................................................47
Event Serialization...........................................................................................................................................................48
Video Analytics.................................................................................................................................................................48
Postbacks...........................................................................................................................................................................53
Android SDK 4.x for Marketing Cloud SolutionsLast updated 1/18/2018
Postbacks Example...................................................................................................................................................................................53
PII Postbacks...............................................................................................................................................................................................54
Analytics Methods...........................................................................................................................................................55
Acquisition......................................................................................................................58Mobile App Acquisition................................................................................................................................................58
Acquisition Methods......................................................................................................................................................59
Tracking Deep Links.......................................................................................................................................................60
Tracking Third-Party Deferred Deep Links.......................................................................................................................................61
Testing Marketing Link Acquisition..........................................................................................................................62
Testing Version 3 Acquisition.....................................................................................................................................65
Testing Legacy Acquisition..........................................................................................................................................68
Messaging.......................................................................................................................69In-App Messaging...........................................................................................................................................................69
Troubleshooting In-App Messaging..................................................................................................................................................71
Push Messaging...............................................................................................................................................................73
Implement Push Messaging with Deep Linking............................................................................................................................74
Receive Rich Push Notifications...........................................................................................................................................................76
Troubleshooting Push Messaging......................................................................................................................................................78
Location...........................................................................................................................79Geo-Location and Points of Interest.........................................................................................................................79
Beacon tracking...............................................................................................................................................................81
Target..............................................................................................................................83Target Configuration......................................................................................................................................................83
Target Methods................................................................................................................................................................83
Prefetch offer content in Android.............................................................................................................................88
Marketing Cloud.............................................................................................................93Marketing Cloud Visitor ID Configuration..............................................................................................................93
Marketing Cloud Visitor ID Service Methods.........................................................................................................93
Android SDK 4.x for Marketing Cloud SolutionsLast updated 1/18/2018
Contents
Marketing Cloud Device Co-op..................................................................................................................................96
Audience Manager.........................................................................................................97Audience Manager Configuration.............................................................................................................................97
Audience Manager Methods.......................................................................................................................................97
Wearables........................................................................................................................99Android Wearables: Getting Started........................................................................................................................99
Android Wearables: Additional Notes...................................................................................................................101
Android SDK Reference................................................................................................103App IDs.............................................................................................................................................................................103
Visitor Tracking Between an App and Mobile Web..........................................................................................103
Android Widgets...........................................................................................................................................................104
Opt-Out and Privacy Settings......................................................................................106
Using Bloodhound to Test Mobile Applications........................................................108
PhoneGap Plug-in........................................................................................................109PhoneGap Plug-in Methods......................................................................................................................................110
Contact and Legal Information...................................................................................122
Android SDK 4.x for Marketing Cloud SolutionsLast updated 1/18/2018
Release NotesRelease notes and known issues for Android SDK 4.x for Marketing Cloud Solutions.
Mobile Services
Release date: October 12, 2017
DescriptionFeature
Released October 26, 2017Virtual Report Suite
Added support for Analytics Virtual Report Suites.
See Virtual Report Suites for more information.
Added push messaging support for recurring scheduling.Push Messaging
For more information about scheduling recurring pushmessages, see Schedule: Push Message.
You can now log in to Mobile Services UI by using ExperienceCloud authentication.
Experience Cloud login
For more information about the updated signing in process,see Signing In.
Mobile Services SDK
Version 4.14.0
Release date: October 12, 2017
DescriptionAndroid/iOS SDKs
Use the mobile preview link to perform easy end-to-end QAfor mobile app activities and enroll yourself into different
Target enhancement for previewing experiences.
experiences right on your device without any special testdevices.
For more information, see Target Mobile Preview.
The Adobe Target prefetch feature uses the Android MobileSDKs to fetch offer content as few times as possible by cachingthe server responses.
Target enhancement for allowing prefetching of experiencedata.
For more information, see Prefetch offer content in Androidand Prefetch offer content in iOS.
5Release Notes
DescriptionXamarin SDK plugin
The Xamarin plugin for iOS and Android has been updated toversion 4.13.8.
Version update
For more information about the release notes for all solutions, see Adobe Experience Cloud Release Notes.
6Release Notes
Android SDK 4.x for Marketing Cloud SolutionsAndroid SDK 4.x for Marketing Cloud Solutions allows you to measure native Android applications, deliver targeted contentin your app, and leverage and collect audience data through audience management.
Last Update: December 14, 2017
Some information to remember:
• 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 need to use a packet analyzer that supports inspectingPOST data to view hits, such as the Bloodhound 3.x for Mac.
Important: As of April 30, 2017, Adobe Bloodhound has been sunset. Starting on May 1, 2017, no additional enhancementsand no additional Engineering or Adobe Expert Care support will be provided.
• If you are upgrading from a previous version, see the 4.x Migration Guide.
Adobe Mobile User Documentation
Adobe Mobile services provides a UI that brings together mobile marketing capabilities for mobile applications from across theAdobe Marketing Cloud. To learn more about the UI and read the user documentation, see Adobe Mobile Services.
Release Notes
For the latest information about Marketing Cloud releases, see Marketing Cloud Release Notes.
7Android SDK 4.x for Marketing Cloud Solutions
Getting StartedThe following information helps you get started with the Android SDK for Marketing Cloud Solutions:
Before You Start
Before configuring a report suite and collecting Android app data, complete the following prerequisite tasks:
This section contains the following information:
• Role-Specific Tasks• Log in to the Adobe Mobile Services UI• Create a Report Suite• Download the SDK
Role-Specific Tasks
Analytics administrators and app developers must complete the following tasks:
Analytics administrators
To configure a report suite and collect mobile app data:
1. Complete one of the sections in Log in to the Adobe Mobile Services UI.
2. Create an Analytics account for each app developer.
App developers now have access to view the report suite(s) that you created.
Important: To create a new report suite and download the SDKs, you must be an Analytics Administrator.
App developers
1. Ensure that your Analytics administrator has completed the steps in the Analytics Administrators section in Role-SpecificTasks.
2. Verify that your Analytics administrator has completed one of the sections in Log in to the Adobe Mobile Services UI.3. After the report suite has been configured, complete steps in Download the SDK.
For more information about roles and permissions, see Roles and Permissions.
Log in to the Adobe Mobile Services UI
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 othersettings.
You can log in to the Adobe Mobile Services UI in one of the following ways:
• Marketing Cloud
Sign in to the Marketing Cloud with your Adobe ID. This method assumes that your company has been provisioned in theMarketing Cloud, and you have linked your Analytics account.
8Getting Started
Tip: If you are unsure whether your company has been provisioned in the Marketing Cloud, use your existing AdobeAnalytics account.
• Adobe Analytics
Click Sign in with Analytics and enter your Analytics company name, your username, and your password.
Create a Report Suite
To create a report suite to collect app data and define an app:
1. Click Create New App.
If you do not see this button, click Manage Apps > Add.
2. In the Report Suite drop-down, select New Report Suite.3. Enter the name of your app and select a report suite type.
An example of a report suite ID is mycomobileappdev. You need to set up separate report suites and apps for the developmentand production versions, so you can repeat these steps when you are ready to set up the production version.
4. In Report Suite ID, verify that your report suite name is displayed.5. In Copy Settings From, verify that Mobile App Template is selected.
This template enables timestamps to collect offline data and activates the mobile solution variables to capture lifecycle metrics.
6. Select your time zone, your currency, and click Save.
Download the SDK
To download the mobile SDK:
1. Log in to the Mobile Services UI and open your app in one of the following ways:
• In the All Apps drop-down list, select your app.• On the right pane, find your app, and open it.
2. Click Manage App Settings.
3. Scroll to the App SDK Downloads section.
4. Download the SDK and the sample app for your platform.
Attention: A config file for your app is automatically included in the SDK download, so you do not need to download thatfile separately. However, if you already downloaded the SDK, and you want to get updated settings, download the configfile again.
If you are using Android Studio, you can also add the following to your app's build.gradle file:
compile 'com.adobe.mobile:adobeMobileLibrary:4.13.7'
Remember the following information:
• Replace the version number in the code sample with the appropriate version of the Android SDKs.• Download the config file and include it in your project.
9Getting Started
Core Implementation and Lifecycle
This information helps you implement the Android library and collect lifecycle metrics, such as launches, upgrades, sessions,engaged users, and so on.
This topic contains the following information:
• Download the SDK• Add the SDK and Config File to your IntelliJ IDEA or Eclipse Project• Add App Permissions• Implement Lifecycle Metrics
Download the SDK
Important: To download the SDK, you must use Android 2.2 or later.
1. Complete the steps in the following sections to set up a development report suite and download a pre-populated version ofthe configuration file:
• Create a Report Suite• Download the SDK
2. Download, unzip the [Your_App_Name_]AdobeMobileLibrary-4.*-Android.zip file, and verify that the followingsoftware components exist:
• adobeMobileLibrary.jar
This is the library that will be used with Android devices and simulators.
• ADBMobileConfig.json
This is the SDK configuration file that is customized for your app.
Important: If you download the SDK outside the Adobe Mobile services UI, the ADBMobileConfig.json file must bemanually configured. If you are new to Analytics and the Mobile SDK, and you want to set up a development report suiteand download a pre-populated version of the configuration file, see Before You Start.
Add the SDK and Config File to your IntelliJ IDEA or Eclipse Project
IntelliJ IDEA Project
To add the SDK and config file to your project:
1. Add the ADBMobileConfig.json file to the assets folder in your project.2. Right click your project in the project navigation panel.3. Select Open Module Settings.4. Under Project Settings, select Libraries.5. Click the + 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 OK to close the Module Settings window.
10Getting Started
Eclipse Project
To add the SDK and config file to your project:
1. Add the ADBMobileConfig.json file to the assets folder in your project.2. In Eclipse IDE, right-click the project name.3. Select Build Path > Add External Archives.4. Select adobeMobileLibrary.jar.5. Click Open.6. Right-click the project again and select Build Path > Configure Build Path.7. On the Order and Export tab, 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, which is located in the applicationproject 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, one hit is sent to measure launches, upgrades, sessions, engaged users,and many other metrics. For more information, see Lifecycle Metrics.
Complete the following steps in each activity of your application:
1. Import the library:import com.adobe.mobile.*;
2. In the onResume function, start the lifecycle data collection:@Overridepublic void onResume() { Config.collectLifecycleData(this); // -or- Config.collectLifecycleData(this, contextData);}
3. In the onPause function, pause the lifecycle data collection:@Overridepublic void onPause() { Config.pauseCollectingLifecycleData();}
Important: You must add these calls to every activity to ensure accurate crash reporting. For more information, see TrackApp Crashes.
Include Additional Data with Lifecycle Calls
To include additional data with lifecycle metric calls, pass an additional parameter to collectLifecycleData that containscontext data:@Overridepublic void onResume() { HashMap<String, Object> contextData = new HashMap<String, Object>();
11Getting Started
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 AdobeMobile services:
Other lifecycle metrics are collected automatically. For more information, see Lifecycle Metrics.
What to do next
Complete the following tasks:
• Track App States• Track App Actions
Processing Rules and Context Data
Processing rules are used to copy the data that you send in context data variables to evars, props, and other variables for reporting.
For more information, see the following content:
• Processing Rules Training @ Summit 2013• Processing Rules
When working with processing rules, remember the following information:
• Group your context data variables by using namespaces, because it helps you maintain a logical ordering. For example, tocollect information 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, which allows you to quickly see which variablesare in the same namespace.
Avoid naming context data keys by using the evar or prop number:"eVar1":"jimbo"
12Getting Started
This might make it slightly easier when you complete the one-time mapping in processing rules, but you lose readability duringdebugging and future code updates, which can be more difficult. Instead, we strongly recommend that you use descriptivenames 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"
Tip: Adobe reserves the namespace "a.". To avoid collisions, the only other requirement is that context data variables areunique in your login company.
Migrating to the Android 4.x Library
This information helps you migrate from the 3.x or 2.x version of the Android library to version 4.x.
In the version 4.x library, the public methods are consolidated into one header. Also, all functionality is now accessible throughclass level methods, so you do not have to keep track of pointers, instances, or singletons.
The following sections walk you through the migration process:
• Events, Props, and eVars• Remove Unused Properties• Update Track Calls and Tracking Variables• Custom Visitor ID• Offline Tracking• Products Variable• Test the Migration
Events, Props, and eVars
In version 4, you can no longer assign variables such as events, eVars, props, heirs, and lists in your app. Instead, the SDK usescontext data and processing rules to map your app data to Analytics variables for reporting.
Processing rules provide the following advantages:
• You can change your data mapping without submitting an update to the App Store.• You can use meaningful names for data instead of setting variables that are specific to a report suite.• There is little impact to sending in extra data.
These values will not appear in reports until they are mapped using processing rules.
Tip: Values that you assigned directly to variables should be added to the data HashMap.
13Getting Started
Remove Unused Properties
The new ADBMobileConfig.json file contains application-specific, global settings, and replaces most of the configurationvariables that were used in previous versions. Here is an example of an ADBMobileConfig.json file:{ "version" : "1.0", "analytics" : { "rsids" : "coolApp", "server" : "my.CoolApp.com", "charset" : "UTF-8", "ssl" : false, "offlineEnabled" : true, "lifecycleTimeout" : 5, "privacyDefault" : "optedin", "poi" : [ ["san francisco",37.757144,-122.44812,7000], ["santa cruz",36.972935,-122.01725,600] ] }, "target" : { "clientCode" : "myTargetClientCode", "timeout" : 5 }, "audienceManager" : { "server" : "myServer.demdex.com" }}
Moving the Configuration File and Migrating to Version 4
The following tables list the configuration variables that you need to move to the configuration file.
Moving the configuration file
1. Move the value that is set for the variable in the first column to the variable in the second column.2. Remove the old configuration variable from your code.
Migrating from version 3.x
Move the value from the first column to the variable in the second column.
Variable in the ADBMobileConfig.json fileConfigurationVariable/Method
"offlineEnabled"setOfflineTrackingEnabled
"batchLimit"setOfflineHitLimit
"rsids"reportSuiteIDs
"server"trackingServer
"charset"charSet
"currency"currencyCode
"ssl"ssl
14Getting Started
Variable in the ADBMobileConfig.json fileConfigurationVariable/Method
Remove, no longer used.linkTrackVars
Remove, no longer used.linkTrackEvents
Migrating from version 2.x
Move the value from the first column to the variable in the second column.
Variable in the ADBMobileConfig.json fileConfiguration Variable
"offlineEnabled"trackOffline
"batchLimit"offlineLimit
"rsids"account
"server", remove the "http://" prefix. The protocol prefix is added automatically based on the"ssl" setting.
trackingServer
Remove. For secure connections, define "server" and then enable "ssl".trackingServerSecure
"charset"charSet
"currency"currencyCode
"ssl"ssl
Remove, no longer used.linkTrackVars
Remove, no longer used.linkTrackEvents
Remove, no longer configurable.timestamp
Remove, no longer used.dc
Remove, no longer configurable.userAgent
Remove, no longer used.dynamicVariablePrefix
Remove, no longer used.visitorNamespace
Remove, no longer used.usePlugins
15Getting Started
Variable in the ADBMobileConfig.json fileConfiguration Variable
Remove, replaced by Lifecycle Metrics.useBestPractices
all calls to churnmeasurement(getChurnInstance)
Update Track Calls and Tracking Variables
Instead of using the web-focused track and trackLink calls, the version 4 SDK uses the following methods:
• trackState, which are the views that are available in your app, such as home dashboard, app settings, cart, and soon.
These states are similar to pages on a website, and trackState calls increment page views.
• trackAction actions, such as logons, banner taps, feed subscriptions, and so on that occur in your app and thatyou want to measure.
The contextData parameter for both of these methods is a HashMap<String, Object>, which contains the name-valuepairs that are sent as context data.
Events, Props, eVars
In version 4, you can no longer assign variables such as events, eVars, props, heirs, and lists directly in your app. The SDK nowuses context data and processing rules to map your app data to Analytics variables for reporting.
Processing rules provide the following advantages:
• You can change your data mapping without submitting an update to the app store.• You can use meaningful names for data instead of setting variables that are specific to a report suite.• There is little impact to sending in extra data.
These values will not appear in reports until they are mapped using processing rules. For more information, see ProcessingRules and Context Data.
Values that you were assigning directly to variables should be added to the data HashMap. This means that calls to setProp,setEvar, and assignments to persistent context data should be removed and the values be added to the data parameter.
AppSection/Server, GeoZip, Transaction ID, Campaign, and other standard variables
Data that you were setting on the measurement object, including the variables listed above, should be added to the data HashMap.The only data that is sent with a trackState or trackAction call is the payload in the data parameter.
Replace Tracking Calls
Replace the following methods with a call to trackState or trackAction:
Migrating from version 3.x
• trackAppState (trackState)• trackEvents (trackAction)• track (trackAction)• trackLinkURL (trackAction)
Migrating from version 2.x
• track (trackState)
16Getting Started
• trackLink (trackAction)
Custom Visitor ID
Replace the visitorID variable with a call to setUserIdentifier.
Offline Tracking
Offline tracking is enabled in ADBMobileConfig.json, and all other offline configuration is done automatically.
Remove calls to the following methods:
Version 3.x
• setOnline• setOffline
Version 2.x
• forceOffline• forceOnline
Products Variable
For more information about the products variable, see Products Variable.
Test the Migration
After you complete the migration, for more information about inspecting the data that is being sent by the Mobile SDK, seeUsing Bloodhound to Test Mobile Applications .
Important: As of April 30, 2017, Adobe Bloodhound has been sunset. Starting on May 1, 2017, no additional enhancementsand no additional Engineering or Adobe Expert Care support will be provided.
17Getting Started
ConfigurationThe following information helps you configure the Android SDK, including JSON configuration, hit batching, and SDK methods:
ADBMobile JSON Config
This information helps you use the ADBMobile.json config file.
This section contains the following information:
• ADBMobileConfig.json Config File Reference• Sample ADBMobileConfig.json File• Messages description
ADBMobileConfig.json Config File Reference
The same config file can be used for your app across multiple platforms:
• On iOS, the ADBMobileConfig.json file can be placed anywhere that it is accessible in your bundle.• On Android, the ADBMobileConfig.json file must be placed in the assets folder.
DescriptionMinimum SDKVersion
Variable
Enables mobile app acquisition.4.1
acquisition
• server, which is the acquisition server that is checked at the initial launchfor an acquisition referrer.
• appid, which is the generated ID that uniquely identifies this app on theacquisition server.
If this section is missing, enable Mobile App acquisition and download theSDK configuration file again. For more information, see the referrerTimeoutrow in this table.
The default value is false.4.8.0
analyticsForwardingEnabled
The property in the audienceManager object. If Audience Manager isconfigured, and analyticsForwardingEnabled is set to true, all Analyticstraffic is also forwarded to Audience Manager.
Enables/disables the ability for the Adobe SDK to backdate session info hits.4.6
backdateSessionInfo
Session info hits currently consist of crashes and session length. When thesehits are disabled, the Adobe SDK attaches the session info to the currentlifecycle. The default value is false.
When the hits are enabled, the Adobe SDK backdates the session info hit to1 second after the final hit in the previous session. This means that crash andsession data will correlate with the correct date on which they occurred. Oneside effect is that the SDK might create a visit for the backdated hit. One hitwill be backdated on every new launch of the application.
18Configuration
DescriptionMinimum SDKVersion
Variable
When you set backdateSessionInfo to false, the SDK returns to itspre-4.1 behavior of lumping the session info for the previous session with thefirst hit of the subsequent session, which avoids the creation of an inflatedvisit. This option causes an immediate drop in visit counts because inflatedvisits are no longer created.
Important: Backdated session hit information is sent in a session infoserver call, and additional server calls might apply.
Threshold for number of hits to be sent in consecutive calls.4.1
batchLimit
For example, if batchLimit is set to 10, each hit before the 10th hit will bestored in the queue. When the 10th hit comes in, all 10 hits will be sentconsecutively.
Remember the following information:
• Default value is 0, which means that batching not enabled.• Requires offlineEnabled = true.
Defines the character set that you are using for the data that is sent to Analytics.4.0
charset
The charset is used to convert incoming data into UTF-8 for storage andreporting. For more information, see Using the charSet Property.
4.0clientCode
Important: This variable is required by Target.
Your assigned client code.
Default value is 300 seconds.4.0
lifecycleTimeout
Specifies the length of time, in seconds, that must elapse between the time theapp launches but before the launch is considered to be a new session. Thistimeout also applies when your application is sent to the background andreactivated.
The time that your app spends in the background is not included in the sessionlength.
Generated automatically by Adobe Mobile services, defines the settings forin-app messaging. For more information, see the Messages Description sectionbelow.
4.2messages
When enabled, hits are queued while the device is offline and sent later whenthe device is online. Your report suite must be timestamp-enabled to use offlinetracking.
4.0offlineEnabled
19Configuration
DescriptionMinimum SDKVersion
Variable
The default value is false.
Important: If timestamps are enabled on your report suite, yourofflineEnabled configuration property must be true. if your reportsuite is not timestamp enabled, your offlineEnabled configurationproperty must be false. If this is not configured correctly, data will be lost.If you are not sure whether a report suite is timestamp enabled, contactCustomer Care or download the configuration file from Adobe Mobileservices.
If you are currently reporting AppMeasurement data to a report suite thatalso collects data from JavaScript, you might need to set up a separate reportsuite for mobile data or include a custom timestamp on all JavaScript hits thatuse the s.timestamp variable.
Specifies the Marketing Cloud org ID for the visitor ID service.4.3
org
Each point of interest (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.
4.0poi
When a trackLocation call is sent, if the current coordinates are within adefined POI, a context data variable is populated and sent with thetrackLocation call."poi" : [ ["san francisco",37.757144,-122.44812,7000], ["santa cruz",36.972935,-122.01725,600] ]
Tip: Starting in version 4.2, POIs are defined in the Adobe Mobileinterface and synchronized dynamically to the app configuration file.This synchronization requires the analytics.poi setting:“analytics.poi”: “https://assets.adobedtm.com/…/yourfile.json”,
If this setting is not configured, the ADBMobile.json file must beupdated to include this line. To download an updated configuration file,see Before You Start.
Here is the definition for the "callback" message template:"payload": { "templateurl": "", // required - will be token-expanded
4.6postback
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
20Configuration
DescriptionMinimum SDKVersion
Variable
"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 a sample payload for a message definitionthat goes in ADBMobileConfig.json.
For more information, one of the following:
• Postbacks (Android)
• Postbacks (iOS)
The default value is optedin.4.0
privacyDefault
• For optedin, the hits are sent immediately.• For optedout, the hits are discarded.• For optunknown, if your report suite is timestamp-enabled, hits are saved
until the privacy status changes to opt-in (hits are sent) or opt-out (hits arediscarded).
If your report suite is not timestamp-enabled, hits are discarded until theprivacy status changes to opt in.
This only sets the initial value. If this value is set or changed in code, the newvalue is used until it is changed again, or when the app is uninstalled andreinstalled.
Number of seconds the SDK waits for acquisition referrer data on the initiallaunch before timing out. If you are using acquisition, we recommend a5-second timeout.
4.1referrerTimeout
Important: This variable is required by Acquisition.
If the variable is set to 0 or is not included, the SDK does not wait foracquisition data, and acquisition metrics are not tracked.
Configured automatically and defines the Adobe-hosted endpoints for dynamicconfiguration files. The last update time of each configuration file is checked
4.2remotes
against the current version at each launch, and the updates are downloadedand saved.
• analytics.poi is the endpoint for hosted POI configuration.• messages is the endpoint for hosted in-app message configuration.
4.0rsids
Important: This variable is required by Analytics.
21Configuration
DescriptionMinimum SDKVersion
Variable
One or more report suites to receive Analytics data. Multiple report suite IDsshould be comma-separated with no space between."rsids" : "rsid"
"rsids" : "rsid1,rsid2"
4.0serverImportant: This variable is required by Analytics and/or AudienceManagement.
The Analytics or Audience Management server, based on the parent node.
This variable should be populated with the server domain, without anhttp:// or https:// protocol prefix. This prefix is handled automaticallyby the library and is based on the ssl variable.
If ssl is true, a secure connection is made to this server. If ssl is false, anon-secure connection is made to this server.
The default value is false.4.0ssl
Enables (true) or disables (false) the ability to send measurement data byusing 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 sample payload for a message definitionthat goes in ADBMobileConfig.json.
For more information, see the relevant topic:
• Postbacks (Android)
• Postbacks (iOS)
Determines how long Target waits for a response.4.0timeout
22Configuration
Sample ADBMobileConfig.json File
Here is a sample ADBMobileConfig.json file:{ "version": "2014-08-05T19:18:28.169Z", "marketingCloud" : { "org": "016D5C175213CCA80A490D05@AdobeOrg" }, "target": { "clientCode": "", "timeout": 5 }, "audienceManager": { "server": "", "analyticsForwardingEnabled": false }, "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",37.757144,-122.44812,7000], ["santa cruz",36.972935,-122.01725,600] ] }, "messages": [ { "messageId": "cb426565-a563-497a-a889-9dbeb451f8ae", "template": "fullscreen", "payload": { "html": "<!DOCTYPE html><html><head><meta charset=\"utf-8\" /><title></title><style></style></head><body><iframe src=\"http://www.adobe.com/\" frameborder=\"0\"></iframe></body></html>" }, "showOffline": false, "showRule": "always", "endDate": 2524730400, "startDate": 0, "audiences": [], "triggers": [ { "key": "pev2", "matches": "eq", "values": [ "AMACTION:custom" ] } ] } ], "remotes": { "analytics.poi": "https://assets.adobedtm.com/staging/42a6fc9b77cd9f29082cf19b787bae75b7d1f9ca/scripts/satellite-53e0faadc2f9ed92bc00003b.json",
"messages": "https://assets.adobedtm.com/staging/42a6fc9b77cd9f29082cf19b787bae75b7d1f9ca/scripts/satellite-53e0f9e2c2f9ed92bc000032.json"
}}
23Configuration
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"
• 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 2524730400
• "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"
24Configuration
• alert and local notification, required
• 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"
25Configuration
• an array of values used to match against the value of the variable named in
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
You can load a different ADBMobile JSON config file when the application starts.
The Config.overrideConfigStream(configInput) method allows you to specify the path to a different ADBMobile.jsonconfiguration file when the application starts. This method must be called before any other Marketing Cloud SDK call (beforeConfig.collectLifecycleData() ), typically 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 to hold hits from being sent until the number of hits in the queue have exceeded the configuredlimit.
: To use hit batching, you must enable offline tracking.
Requires SDK version 4.1 or later
To enable hit batching, update your ADBMobileConfig.json and specify a value for batchLimit:"analytics": { "batchLimit": 5, ...}
When the value is set to a number greater than 0, the SDK queues the number of hits equal to the batchLimit value. After thisthreshold is passed, all hits in the queue are sent.
The following methods are used 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 hits are currently queued.• Analytics.clearQueue clears all hits from the queue without sending them.
26Configuration
Configuration Methods
Here is the list of methods that are 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:
DescriptionMethod
For example:@Overridepublic void onCreate(Bundle savedInstanceState) {
setContext
super.onCreate(savedInstanceState); setContentView(R.layout.main); Config.setContext(this.getApplicationContext());}
SDK Settings (Config Class)
DescriptionMethod
Registers an object that implements the AdobeDataCallback interface. The overwritten "call"method will be invoked with a Config.MobileDataEvent value and the associated data in
registerAdobeDataCallback
a Map<String, Object> for the triggering event. For more details about which events willtrigger this callback, see MobileDataEvent Enum.
Tip: This method requires version 4.9.0 or later.
Syntax:public static void registerAdobeDataCallback(final AdobeDataCallback callback);
Example:Config.registerAdobeDataCallback(new Config.AdobeDataCallback() { @Override public void call(Config.MobileDataEvent event, Map<String, Object> contextData) { // handle each event type accordingly if (event == Config.MobileDataEvent.MOBILE_EVENT_ACQUISITION_INSTALL) { // do something with acquisition data found in contextData parameter HashMap<String, Object> acquisitionData = new HashMap<String, Object>(contextData); ... } }});
27Configuration
DescriptionMethod
Returns the current version of the Adobe Mobile library.getVersion
Syntax:public static String getVersion();
Example:String libraryVersion = Config.getVersion();
Returns the enum representation of the privacy status for current user.getPrivacyStatus
Here are the privacy status values:
• MOBILE_PRIVACY_STATUS_OPT_IN, where the hits are sent immediately.• MOBILE_PRIVACY_STATUS_OPT_OUT, where the its are discarded.• MOBILE_PRIVACY_STATUS_UNKNOWN, where if your report suite is timestamp enabled, hits
are saved until the privacy status changes to opt-in (hits are sent) or opt-out (hits arediscarded).
If your report suite is not timestamp enabled, hits are discarded until the privacy status changesto opt in.
The default value is set in the ADBMobileConfig.json file.
Syntax:public static MobilePrivacyStatus getPrivacyStatus();
Example:MobilePrivacyStatus privacyStatus = Config.getPrivacyStatus();
Sets the privacy status for the current user to status.setPrivacyStatus
You can set the privacy status to one of the following values:
• MOBILE_PRIVACY_STATUS_OPT_IN, where the hits are sent immediately.
These hits are sent immediately.
• MOBILE_PRIVACY_STATUS_OPT_OUT, where the its are discarded.
These hits are discarded.
• MOBILE_PRIVACY_STATUS_UNKNOWN, where if your report suite is timestamp enabled, hitsare saved until the privacy status changes to opt-in (hits are sent) or opt-out (hits arediscarded).
If your report suite is not timestamp enabled, hits are discarded until the privacy status changesto opt in.
Syntax:public static void setPrivacyStatus(MobilePrivacyStatus status);
Example:Config.setPrivacyStatus(MobilePrivacyStatus.MOBILE_PRIVACY_STATUS_OPT_IN);
28Configuration
DescriptionMethod
Returns the lifetime value of the current user.getLifetimeValue
The default value is 0.
Syntax:public static BigDecimal getLifetimeValue();
Example:BigDecimal currentLifetimeValue = Config.getLifetimeValue();
If a custom identifier has been set, the custom user identifier is returned. If a custom identifierhas not been set, it returns null.
getUserIdentifier
The default value is null.
Tip: If your app upgrades from the Marketing Cloud 3.x to the 4.x SDK, the previouscustom or automatically generated visitor ID is retrieved and stored as the custom useridentifier. This preserves visitor data between SDK upgrades. For new installations on the4.x SDK, until it is set, the user identifier is null.
Syntax:public static String getUserIdentifier();
Example:String userId = Config.getUserIdentifier();
Sets the user identifier to identifier.setUserIdentifier
Syntax:public static void setUserIdentifer(String identifier);
Example:Config.setUserIdentifier("billybob");
Returns the current debug logging preference.getDebugLogging
The default value is false.
Syntax:public static Boolean getDebugLogging();
Example:Boolean debugging = Config.getDebugLogging();
Sets the debug logging preference to debugLogging.setDebugLogging
Syntax:public static void setDebugLogging(Boolean debugLogging);
Example:Config.setDebugLogging(true);
29Configuration
DescriptionMethod
Indicates to the SDK that lifecycle data should be collected for use across all solutions in theSDK. For more information, see Lifecycle Metrics.
collectLifecycleData
Syntax:public static void collectLifecycleData(final Activity activity, final Map<String, Object> contextData);
Example:
Without extra context data:@Overrideprotected void onResume() { super.onResume(); Config.collectLifecycleData(this);}
With extra context data:@Overridepublic void onResume() { HashMap<String, Object> contextData = new HashMap<String, Object>();
contextData.put("myapp.category", "Game"); Config.collectLifecycleData(this, contextData);}
(Version 4.2 or later) Indicates to the SDK that lifecycle data should be collected for use acrossall solutions in the SDK. For more information, see Lifecycle Metrics.
collectLifecycleData (Activityactivity)
Syntax:public static void collectLifecycleData(final Activity activity);
Example:@Overrideprotected void onResume() { super.onResume(); // assumes being called in an Activity class Config.collectLifecycleData(this);}
Indicates to the SDK that your app is paused, so that lifecycle metrics are calculated correctly.For example, onPause collects a timestamp to determine the previous session length. This also
pauseCollectingLifecycleData
sets a flag so that lifecycle knows that the app did not crash. For more information, see LifecycleMetrics.
Syntax:public static void pauseCollectingLifecycleData();
Example:@Overrideprotected void onPause() { super.onPause(); Config.pauseCollectingLifecycleData();}
30Configuration
DescriptionMethod
(Version 4.2 or later) Sets the small icon that will be used for notifications that were createdby the SDK. This icon will appear in the status bar and will be the secondary image that isdisplayed when the user sees the complete notification in the notification center.
setSmallIconResourceId(intresourceId)
Syntax:public static void setSmallIconResourceId(final int resourceId);
Example:Config.setSmallIconResourceId(R.drawable.appIcon);
(Version 4.2 or later) Sets the large icon that will be used for notifications that were createdby the SDK. This icon will be the primary image that is displayed when the user sees the completenotification in the notification center.
setLargeIconResourceId(intresourceId)
Syntax:public static void setLargeIconResourceId(final int resourceId);
Example:Config.setLargeIconResourceId(R.drawable.appIcon);
(Version 4.2 or later) Allows you to load a different ADBMobile JSON config file when theapplication starts. The different configuration is used until the application is closed.
overrideConfigStream(InputStreamconfigInput)
Syntax:public static void overrideConfigStream(final InputStream configInput);
Example: try { InputStream configInput = getAssets().open("ExampleJSONFile.json"); Config.overrideConfigStream(configInput); } catch (IOException ex) { // do something with the exception if needed}
Sets the device token for push notifications.setPushIdentifier
Syntax:public static void setPushIdentifier(final String registrationId);
Example:...// note: the code to retreive the push token must run in the backgroundInstanceID instanceID = InstanceID.getInstance(getApplicationContext());String token = instanceID.getToken("835015092242", GoogleCloudMessaging.INSTANCE_ID_SCOPE, null);Config.setPushIdentifier(token);...
Provides a Callable to the SDK that returns the string of the Advertising Identifier that isreturned from Google Play Services.
submitAdvertisingIdentifierTask
31Configuration
DescriptionMethod
The SDK runs this task on a background thread and sets an internal variable for the AdvertisingIdentifier that is based on the value returned from the Callable.
Important: If you want to use the Advertising Identifier in Acquisition or Lifecycle, callit before calling Config.collectLifecycleData.
Syntax:public static void submitAdvertisingIdentifierTask(final Callable<String> task);
Example:@Overridepublic void onResume() { super.onResume();
final Callable<String> task = new Callable<String>() { @Override 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);}
AdobeDataCallback Interface
public interface AdobeDataCallback { void call(MobileDataEvent event, Map<String, Object> contextData); }
MobileDataEvent Enum
public enum MobileDataEvent { MobileDataEvent.MOBILE_EVENT_LIFECYCLE, // triggers on a lifecycle hit MobileDataEvent.MOBILE_EVENT_ACQUISITION_INSTALL, // triggers on a app install that has acquisition data MobileDataEvent.MOBILE_EVENT_ACQUISITION_LAUNCH // triggers on launch when the device previously installed via acquisition }
32Configuration
Lifecycle MetricsHere are the metrics and dimensions that can be measured automatically by the mobile library, after lifecycle is implemented,and a link to troubleshoot Lifecycle data.
For more information, go to the Knowledge Base at Troubleshoot Lifecycle data.
This topic contains the following information:
• Lifecycle Metrics and Dimensions• Additional Mobile Metrics and Dimensions
Lifecycle Metrics and Dimensions
When configured, lifecycle metrics are sent in context data parameters to Analytics, in parameters to Target with each mboxcall, and as a signal to audience management. Analytics and Target use the same format, while audience management uses adifferent prefix for each metric.
For Analytics, the context data that is sent with each lifecycle tracking call is automatically captured in and reported on by usingthe metric or dimension listed in the first column, with the exceptions noted in the Description column.
Metrics
DescriptionAudience Manager SignalAnalytics ContextData/Target Parameter
Metric
Triggered at the first run after installation orre-installation.
c_a_InstallEventa.InstallEventFirst Launches
Triggered at the first run after an upgrade or whenthe version number changes.
c_a_UpgradeEventa.UpgradeEventUpgrades
Triggered when the application is used on aparticular day.
c_a_DailyEngUserEventa.DailyEngUserEventDaily EngagedUsers
Important: This metric is not automaticallystored in an Analytics metric. You mustcreate a processing rule that sets a customevent to capture this metric.
Triggered when the application is used during aparticular month.
c_a_MonthlyEngUserEventa.MonthlyEngUserEventMonthlyEngagedUsers
Important: This metric is not automaticallystored in an Analytics metric. You mustcreate a processing rule that sets a customevent to capture this metric.
Triggered at every run, including crashes andinstalls. Also triggered on a resume from the
c_a_LaunchEventa.LaunchEventLaunches
33Lifecycle Metrics
DescriptionAudience Manager SignalAnalytics ContextData/Target Parameter
Metric
background when the lifecycle session timeouthas been exceeded.
Triggered when the application is notbackgrounded before being closed. The event issent when the application is started after the crash.
c_a_CrashEventa.CrashEventCrashes
Adobe Mobile crash reporting does not implementa global uncaught exception handler.
Reports the number of seconds that a previousapplication session lasted, based on how long theapplication was open and in the foreground.
c_a_PrevSessionLengtha.PrevSessionLengthPreviousSessionLength
Dimensions
DescriptionAudience ManagementAnalytics ContextData/Target
Dimension
Date of first launch after installation.c_a_InstallDatea.InstallDateInstall Date
The date format is MM/DD/YYYY.
Stores the application name and version in thefollowing format:
c_a_AppIDa.AppIDApp ID
[AppName] [BundleVersion]
An example of this format is myapp 1.1.
Number of times the application was launched orbrought out of the background.
c_a_Launchesa.LaunchesLaunch Number
Number of days since the first run.c_a_DaysSinceFirstUsea.DaysSinceFirstUseDays since first use
Number of days since the last use.c_a_DaysSinceLastUsea.DaysSinceLastUseDays since last use
Measures the hour that the app was launched.c_a_HourOfDaya.HourOfDayHour of Day
This metric uses the 24-hour numerical format andis used for time parting to determine peak usagetimes.
Number of the day in a week when the app waslaunched.
c_a_DayOfWeeka.DayOfWeekDay of Week
34Lifecycle Metrics
DescriptionAudience ManagementAnalytics ContextData/Target
Dimension
OS version.c_a_OSVersiona.OSVersionOperating SystemVersion
Number of days since the application versionnumber has changed.
c_a_DaysSinceLastUpgradea.DaysSinceLastUpgradeDays since lastupgrade
Important: This metric is not automaticallystored in an Analytics variable. You mustcreate a processing rule to copy this value toan Analytics variable for reporting.
Number of launches since the application versionnumber has changed.
c_a_LaunchesSinceUpgradea.LaunchesSinceUpgradeLaunches since lastupgrade
Important: This metric is not automaticallystored in an Analytics variable. You mustcreate a processing rule to copy this value toan Analytics variable for reporting.
Stores the device name.c_a_DeviceNamea.DeviceNameDevice Name
Stores the name of the mobile service provider asprovided by the device.
c_a_CarrierNamea.CarrierNameCarrier Name
Important: This metric is not automaticallystored in an Analytics variable. You mustcreate a processing rule to copy this value toan Analytics variable for reporting.
Width x Height in actual pixels.c_a_Resolutiona.ResolutionResolution
Additional Mobile Metrics and Dimensions
The following metrics and dimensions are captured in mobile solution variables by the method listed in the Description column.
Metrics
DescriptionAudienceManagement Trait
Analytics ContextData/Target Parameter
Event
Populated by trackTimedAction methods.c_a_action_time_totala.action.time.totalAction Time Total
Populated by trackTimedAction methods.c_a_action_time_inappa.action.time.inappAction Time In App
35Lifecycle Metrics
DescriptionAudienceManagement Trait
Analytics ContextData/Target Parameter
Event
Populated by trackLifetimeValue methods.c_a_ltv_amounta.ltv.amountLifetime Value
(event)
Dimensions
DescriptionAudience ManagementTrait
Analytics ContextData/Target Parameter
Dimension
Populated by trackLocation methods.c_a_loc_lat_a
c_a_loc_lon_a
a.loc.lat.a
a.loc.lon.a
Location (down to10 km)
Populated by trackLocation methods.c_a_loc_lat_b
c_a_loc_lon_b
a.loc.lat.b
a.loc.lon.b
Location (down to100 m)
Populated by trackLocation methods.c_a_loc_lat_c
c_a_loc_lon_c
a.loc.lat.c
a.loc.lon.c
Location (down to 1m)
Populated by trackLocation methods whendevice is within a defined POI.
c_a_loc_poia.loc.poiPoint of InterestName
Populated by trackLocation methods whendevice is within a defined POI.
c_a_loc_dista.loc.distDistance to Point ofInterest Center
Populated by trackLifetimeValue methods.c_a_ltv_amounta.ltv.amountLifetime Value
(conversionvariable)
Populated by Mobile App Acquisition andautomatically generated by Adobe mobile services.
c_a_referrer_campaign_trackingcodea.referrer.campaign.trackingcodeTracking Code
Name of the campaign, also stored in the campaignvariable. Populated by Mobile App Acquisition.
c_a_referrer_campaign_namea.referrer.campaign.nameCampaign
The name or ID of the content that displayed thelink. Populated by Mobile App Acquisition.
c_a_referrer_campaign_contenta.referrer.campaign.contentCampaign Content
Marketing medium, such as a banner or email.Populated by Mobile App Acquisition.
c_a_referrer_campaign_mediuma.referrer.campaign.mediumCampaign Medium
Original referrer, such as a newsletter or a socialmedia network. Populated by Mobile AppAcquisition.
c_a_referrer_campaign_sourcea.referrer.campaign.sourceCampaign Source
36Lifecycle Metrics
DescriptionAudience ManagementTrait
Analytics ContextData/Target Parameter
Dimension
Paid keywords or other terms that you want totrack with this acquisition. Populated by MobileApp Acquisition.
c_a_referrer_campaign_terma.referrer.campaign.termCampaign Term
37Lifecycle Metrics
AnalyticsThis information helps 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,a trackState call is sent. In Android, trackState is typically called each time a new activity is loaded.
Tracking States
1. Add the library to your project and implement lifecycle.
2. Import the library:import com.adobe.mobile.*;
3. In the onCreate function, call trackState to send a hit for this state view:@Overridepublic 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 eachtrackState call. In other Analytics interfaces, View State is reported as Page Name, and state views is reported as pageviews.
Send Additional Data
In addition to the "State Name", you can send additional context data with each track action call:@Overridepublic 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:
38Analytics
App State Reporting
States are typically viewed by using a pathing report, which allows you to see how users navigate your app and which states aremost frequently viewed.
The View States report.Adobe MobileServices
This report is based on the paths that the users took through your application. A sample path is Home >Settings > Feed.
States can be viewed anywhere that Pages can be viewed, such as the Pages report, the Page Views report,and the Path report.
AdobeAnalytics
States can be viewed anywhere Pages can be viewed by using the Page dimension, Page Views metric, Pathreports.
Ad hocanalytics
Track App Actions
Actions are the events that occur in your Android 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 mightsend a trackAction call for each new subscription, each time an article is viewed, or each time a level is completed. Actionsare not tracked automatically, so you must call trackAction when an event that you want to track occurs, and map the actionto a custom event.
Tracking Actions
1. Add the library to your project and implement lifecycle.
2. Import the library:import com.adobe.mobile.*;
3. 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);
4. In the Adobe Mobile Services UI, select your app and click Manage App Settings.
5. Click Manage Variables and Metrics and click the Custom Metrics tab.
39Analytics
6. Map the context data name that is defined in your code, for example, myapp.ActionName, to a custom event.
You can also set a prop to hold all action values by mapping a custom prop with a name like Custom Actions and setting thevalue 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:
40Analytics
Action Reporting
ReportInterface
Action Paths report.Adobe Mobile Services
View the order in which actions occur in your app. You can also click Customize on any report toview actions ranked, trended, or in a breakdown report or apply a filter to view actions for a specificsegment.
Custom Event report.Marketing reports &analytics
After an action is mapped to a custom event, you can view mobile events similar to all other Analyticsevents.
Custom Event report.Ad hoc analytics
After an action is mapped to a custom event, you can view mobile events similar to all other Analyticsevents.
Track App Crashes
This information helps you understand how crashes are tracked and the best practices to handle false crashes.
Prerequisite: App crashes are tracked as part of lifecycle metrics. Before you can track crashes, add the library to your projectand implement lifecycle.
When lifecycle metrics are implemented, a call is made to Config.collectLifecycleData in the OnResume method of eachactivity. In the onPause method, a call is made to Config.pauseCollectingLifeCycleData.
In the pauseCollectingLifeCycleData, a flag is set to indicate a graceful exit. When the app is launched again or resumed,collectLifecycleData checks this flag. If the app did not exit successfully as determined by the flag status, an a.CrashEventcontext data is sent with the next call and a crash event is reported.
To ensure accurate crash reporting, you must call pauseCollectingLifeCycleData in the onPause method of each activity.To understand why this is essential, here is an illustration of the Android activity lifecycle:
41Analytics
For more information about the Android activity lifecycle, see Activities.
This Android lifecycle illustration was created and shared by the Android Open Source Project and used according to terms in theCreative Commons 2.5 Attribution License.
What can cause a false crash to be reported?
1. If you are debugging by using an IDE, such as Android Studio, and launching the app again from the IDE while the app isin the foreground causes a crash.
Tip: You can avoid this crash by backgrounding the app before launching again from the IDE.
42Analytics
2. If the last foreground Activity of your app is backgrounded and does not call Config.pauseCollectingLifecycleData();in onPause, and your app is manually closed or killed by the OS, the next launch results in a crash.
How should Fragments be handled?
Fragments have application lifecycle events that are similar to Activities. However, a Fragment cannot be active without beingattached to an Activity.
Important: You need to rely on the lifecycle events against which the containing activities can run your code. This will behandled by the parent view of the Fragment.
(Optional) Implement Activity lifecycle callbacks
Starting with API Level 14, Android allows global lifecycle callbacks for activities. For more information, see the AndroidDevelopers Guide.
You can use these callbacks to ensure that all of your Activities correctly call collectLifecycleData() andpauseCollectingLifecycleData(). You need to add this code only in your main Activity and any other Activity in whichyour app may be launched:import com.adobe.mobile.Config;
public class MainActivity extends Activity {... @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main);
getApplication().registerActivityLifecycleCallbacks(new Application.ActivityLifecycleCallbacks() { @Override public void onActivityResumed(Activity activity) { Config.setContext(activity.getApplicationContext()); Config.collectLifecycleData(activity); }
@Override public void onActivityPaused(Activity activity) { Config.pauseCollectingLifecycleData(); }
// the following methods aren't needed for our lifecycle purposes, but are required to be implemented // by the ActivityLifecycleCallbacks object @Override public void onActivityCreated(Activity activity, Bundle savedInstanceState) {} @Override public void onActivityStarted(Activity activity) {} @Override public void onActivityStopped(Activity activity) {} @Override public void onActivitySaveInstanceState(Activity activity, Bundle outState) {} @Override public void onActivityDestroyed(Activity activity) {} }); }...}
43Analytics
To send additional context data with your lifecycle call by using Config.collectLifecycleData(Activity activity,Map<String, Object> contextData), you must override the onResume method for that Activity and ensure that you callsuper.onResume() after manually calling collectLifecycleData.@Overrideprotected void onResume() { HashMap<String, Object> cdata = new HashMap<>(); cdata.put("someKey", "someValue"); Config.collectLifecycleData(this, cdata);
super.onResume();}
Timed Actions
Timed actions allow you to measure the in-app time and total time between the start and the end of an action. The SDK calculatesthe amount of time in each session and the total time across sessions that it will take for the action to be completed. You canuse timed actions to define segments and compare time to purchase, pass level, checkout flow, and so on.
The following metrics are reported for timed actions:
• Total # of seconds in the 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 before passing in durations.• Cancel hit and durations not yet sent.
Track Timed Actions
1. Add the library to your project and implement lifecycle.
2. Import the library:import com.adobe.mobile.*;
3. 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);
4. (Optional) At any point, you can call trackTimedActionUpdate with the timed action name to add additional contextdata.HashMap cdata = new HashMap<String, Object>();cdata.put("myapp.ImageLiked", imageName);Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata);
5. When the event completes, call trackTimedActionEnd and pass the timed action name and TimedActionBlock (callback),which will look up all data and calculate durations.Analytics.trackTimedActionEnd("TimeUntilPurchase", cdata);
Timed event metrics are saved in mobile solution variables for automatic reporting.
44Analytics
Sending Additional Data
In addition to the timed action name, you can also 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:
Examples// Timed Action Start ExampleHashMap cdata = new HashMap<String, Object>();cdata.put("ExperienceName", experience);Analytics.trackTimedActionStart("TimeUntilPurchase", cdata);
// Timed Action Update Examplecdata = new HashMap<String, Object>();cdata.put("ImageLiked", imageName);Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata);
// Timed Action End ExampleAnalytics.trackTimedActionEnd("TimeUntilPurchase", null);
// Timed Action End Example with CallbackAnalytics.trackTimedActionEnd("TimeUntilPurchase", new Analytics.TimedActionBlock<Boolean>() { @Override 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
The lifetime value allows you to measure and target on a lifetime value for each Android user. The value can be used to storelifetime purchases, ad views, video completes, social shares, photo uploads, and so on.
Each time you send in a value with trackLifetimeValueIncrease, the value is added to the existing value. Lifetime valueis stored on device and can be retrieved at any time by calling lifetimeValue.
Track the Visitor Lifetime Value
1. Add the library to your project and implement lifecycle.
45Analytics
2. Import the library:import com.adobe.mobile.*;
3. Call trackLifetimeValueIncrease with the amount to increase the value:Analytics.trackLifetimeValueIncrease(BigDecimal.valueOf(5.0), null);
Send Additional Data
In addition to the lifetime value, you can also 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 by using processing rules. In the Mobile SDK, you must use a special syntax in the contextdata parameter to set products on the server call.
To set the products variable, set a context data key to "&&products", and set the value by using the syntax that is defined forthe products variable:cdata.put("&&products", "Category;Product;Quantity;Price[,Category;Product;Quantity;Price]");
For example://create a context data dictionaryHashMap 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 productscdata.put("&&products", ";Running Shoes;1;69.95,;Running Socks;10;29.99");cdata.put("myapp.purchase", "1");cdata.put("myapp.purchaseid", "1234567890");
// send the tracking call - use either a trackAction or TrackState call.// trackAction example:Analytics.trackAction("purchase", cdata);// trackState example:Analytics.trackState("Order Confirmation", cdata);
The products variable is set on the image request, and the other variables are set as context data:
46Analytics
All context data variables must be mapped by using processing rules:
You do not need to map the products variable by using processing rules because this variable is set directly on the image requestby the SDK.
Products Variable with Merchandising eVars and Product-Specific Events
Here is an example of the products variable with Merchandising eVars and product-specific events.//create a context data dictionaryHashMap 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 productscdata.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", "1234567890");
// send the tracking call - use either a trackAction or TrackState call.// trackAction example:Analytics.trackAction("purchase", cdata);// trackState example:Analytics.trackState("Order Confirmation", cdata);
47Analytics
Tip: If you trigger a product-specific event by using the &&products variable, you must also set that event in the &&eventsvariable. If you do not set that event, it is filtered out during processing.
Event Serialization
Event serialization is not supported by processing rules. In the Mobile SDK, you must use a special syntax in the context dataparameter to set serialized events directly on the server call.cdata.put("&&events", "event1:12341234");
For example://create a context data dictionaryHashMap cdata = new HashMap<String, Object>();
// add eventscdata.put("&&events", "event1:12341234");
// send the tracking call - use either a trackAction or TrackState call.// trackAction example:Analytics.trackAction("action", cdata);// trackState example:Analytics.trackState("State Name", cdata);
Video Analytics
Here is some information about measuring video on Android by the video measurement solution.
Tip: During video playback, frequent "heartbeat" calls are sent to this service to measure time played. These heartbeat callsare sent every 10 seconds, which results in granular video engagement metrics and more accurate video fallout reports. Formore information about Adobe's video measurement solution, see Measuring Video in Adobe Analytics using Video Heartbeat.
The general process to measure video is similar across all platforms. This content provides an overview of the developer taskswith code samples.
This topic contains the following information:
• Map Player Events to Analytics Variables• Configure Media Settings• Track Player Events• Classes• Media Measurement Class and Method Reference
Map Player Events to Analytics Variables
The following table lists the media data that is sent to Analytics. Processing rules are used to map the context data in the ContextData Variable column to an Analytics variable in the Variable Type column.
DescriptionVariable TypeContext Data Variable
(Required) When a visitor views the video in some way, thiscontext data variable collects the name of the video, as specified
a.media.name • eVar
• Default expiration: Visit
48Analytics
DescriptionVariable TypeContext Data Variable
in the implementation. You can add classifications for thisvariable.
• Custom Insight (s.prop, used forvideo pathing)
(Optional) The Custom Insight variable provides video pathinginformation.
(Optional) Provides video pathing information.a.media.name • Custom Insight (s.prop)
Important: Pathing must be enabled for this variable byExpCare.
Event type: Custom Insight (s.prop)
(Required) Collects video segment data, including the segmentname and the order in which the segment occurs in the video.
a.media.segment • eVar
• Default expiration: Page viewThis variable is populated by enabling thesegmentByMilestones variable when automatically trackingplayer events or by setting a custom segment name whenmanually tracking player events.
For example, when a visitor views the first segment in a video,SiteCatalyst might collect the following in the Segments eVar:
1:M:0-25
The default video data collection method collects data at thefollowing points:
• video start (play)• segment begin• video end (stop)
Analytics counts the first segment view at the start of thesegment, when the visitor starts watching. Subsequent segmentviews as the segment begins.
Collects data about the type of content that is viewed by a visitor.Hits sent by video measurement are assigned a content type ofvideo.
a.contentType • eVar
• Default expiration: Page view
From a video measurement perspective, Content Type allowsyou identify video visitors and calculate video conversion rates.
Counts the time, in seconds, that is spent watching a video sincethe last data collection process (image request).
a.media.timePlayed • Event
• Type: Counter
49Analytics
DescriptionVariable TypeContext Data Variable
Indicates that a visitor has viewed some portion of a video.However, it does not provide any information about how much,or which part, of a video that the visitor viewed.
a.media.view • Event
• Type: Counter
Indicates that a visitor has viewed some portion of a videosegment. However, it does not provide any information abouthow much, or which part, of a video that the visitor viewed.
a.media.segmentView • Event
• Type: Counter
Indicates that a user has viewed a complete video. By default,the complete event is measured 1 second before the end of thevideo.
a .media.complete • Event
• Type: Counter
During implementation, you can specify how many secondsfrom the end of the video you would like to consider a view asbeing complete. For live video and other streams that do nothave a defined end, you can specify a custom point to measurecompletes (for example, after a specific time viewed).
Configure Media Settings
Configure a MediaSettings object with the settings you want to use to track video:MediaSettings mySettings = Media.settingsWith("name", 10, "playerName", "playerId");
Track Player Events
To measure video playback, the mediaPlay, mediaStop, and mediaClose methods need to be called at the appropriate times.For example, when the player is paused, call mediaStop. mediaPlay is called when playback starts or is resumed.
Classes
Class: MediaSettingspublic String name;public String playerName;public String playerID;public double length;public String channel;public String milestones;public String offsetMilestones;public boolean segmentByMilestones;public boolean segmentByOffsetMilestones;public int trackSeconds = 0;public int completeCloseOffsetThreshold = 1;
// MediaAnalytics Ad settingspublic String parentName;public String parentPod;public String CPM;public double parentPodPosition;public boolean isMediaAd;
50Analytics
Class: MediaStatepublic Date openTime = new Date();public String name;public String segment;public String playerName;public String mediaEvent;public int offsetMilestone;public int segmentNum;public int milestone;public double length;public double offset;public double percent;public double timePlayed;public double segmentLength;public boolean complete = false;public boolean clicked = false;public boolean ad;public boolean eventFirstTime;
Media Measurement Class and Method Reference
DescriptionMethod
Returns a MediaSettings object with specified parameters.settingsWith
Syntax:public static MediaSettings adSettingsWith(String name, double length, String playerName, String parentName, String parentPod, double parentPodPosition, String CPM);
Example:MediaSettings mySettings = Media.settingsWith("name", 10, "playerName", "playerId");
Returns a MediaSettings object for use with tracking an ad video.adSettingsWith
Syntax:public static MediaSettings adSettingsWith(String name, double length, String playerName, String parentName, String parentPod, double parentPodPosition, String CPM);
Example:
Opens a MediaSettings object for tracking.open
Syntax:public static void open(MediaSettings settings, MediaCallback callback);
Example:Media.open(mySettings, new Media.MediaCallback() { @Override public void call(Object item) { // monitor callback if you want to be notified every second the media is playing }});
Closes the media item named name.close
51Analytics
DescriptionMethod
Syntax:public static void close(String name);
Example:Media.close("name");
Plays the media item named name at the given offset in seconds.play
Syntax:public static void play(String name, double offset);
Example:
Manually mark the media item as complete at the offset provided in seconds.complete
Syntax:public static void complete(String name, double offset);
Example:Media.complete("name", 0);
Notifies the media module that the video has been stopped or paused at the given offset.stop
Syntax:public static void stop(String name, double offset);
Example:Media.stop("name", 0);
Notifies the media module that the media item has been clicked.click
Syntax:public static void click(String name, double offset);
Example:Media.click("name", 0);
Sends a track action call (no page view) for the current media state.track
Syntax:public static void track(String name, Map<String, Object> data);
Example:Media.track("name", null);
52Analytics
Postbacks
Postbacks allow you to send data that is collected by the SDK to a third-party server. By leveraging the same triggers and traitsthat you use to display an in-app message, you can configure the SDK to send customized data to a third-party destination.
Important: This functionality requires SDK version 4.6.0 or later.
Postback messages are queued and follow all existing online/offline rules that govern analytics data collection. When a messagematches (like shown-messages do), postback messages do not cancel the rest of the messages. This allows for multiple postbacksto occur on the same analytics hit. For the definition, see the postbacks row in ADBMobile JSON Config.
Template Expansions
Template expansions are available in the templateurl and templatebody properties. Template items take the form of {key},where key is a context data key or traditional data key. The values that are available for template expansion are limited to thestandard Lifecycle variables list, in addition to any custom data that is attached to the hit that triggers the message. No historical-or segment-based data is available at this time.
There are also specific, reserved templates that the SDK will automatically replace with internal data that is known to the SDK.
This list includes:
Token DescriptionToken Name
Returns SDK version.{%sdkver%}
Resolves to a random number between 1 and 100000000.{%cachebust%}
Returns Advertiser ID for Android. Note, this only works if you have usedsubmitAdvertisingIdentifierTask.
{%adid%}
Returns the Push Identifier token. Note, this only works if you have used setPushIdentifier.{%pushid%}
Returns current timestamp in epoch time.{%timestampu%}
Returns current timestamp in JavaScript (ISO 8601) format.{%timestampz%}
Postbacks Example
You can use this information to help you understand postbacks are and how they work.
: This example is provided for informational purposes only. The ADBMobileConfig.json file should be configured in theAdobe Mobile UI and should not be manually modified. A manually edited configuration file can be dangerous when you haveremote messages configuration enabled.
This topic contains the following information:
• ADBMobileConfig.json Definition• Code Sample
53Analytics
ADBMobileConfig.json Definition"messages": [ { "messageId": "79ae37c9-89b9-465e-af7f-d3351771f1dc", "template": "callback", "payload": { "templateurl": "http://my.server.com/?user={user.name}&zip={user.zip}&c16={%sdkver%}&c27=cln,{a.PrevSessionLength}",
"templatebody": "c2RrdmVyPXslc2RrdmVyJX0mY2I9eyVjYWNoZWJ1c3QlfSZjbGllbnRJZD17bi5jbGllbnQuaWR9JnRzPXsldGltZXN0YW1wVSV9JnRzej17JXRpbWVzdGFtcFolfQ==",
"contenttype": "application/x-www-form-urlencoded", "timeout": 4 }, "showOffline": true, "showRule": "always", "endDate": 2524730400, "startDate": 0, "audiences": [], "triggers": [ { "key": "pageName", "matches": "eq", "values": [ "MainMenu" ] } ] }]
Code SampleHashMap<String, Object> contextData = new HashMap<String, Object>();contextData.put("user.name", "bob");contextData.put("user.zip", "90210");Analytics.trackState("MainMenu", contextData);
Because its state is “MainMenu”, this tracking call triggers the above postback message. The URL will replace all templatevariables with values from the hit. Assuming that the user’s previous session was 132 seconds long, and that user is on AndroidSDK version 4.6.0, the resulting URL would look like this:
http://my.server.com/?user=bob&zip=90210&c16=4.6.0-AN&c27=cln,132
PII Postbacks
You can use the Adobe SDK to collect personally identifiable information (PII) and send it to a third-party endpoint.
When you want to use the Adobe SDK to collect PII, you should send a track PII call. Although using this call enables collectionof PII data, the SDK does not automatically send the data to an Adobe endpoint. A PII type postback needs to be configuredwith the appropriate endpoint.
Tip: An endpoint that supports HTTPS is required to use the PII postback type.
Tracking PII Postbacks
1. Add the library to your project and implement lifecycle.
2. Import the library:#import "ADBMobile.h"
54Analytics
3. When you are ready to capture PII, call trackPII to send a hit for this action, event, or view:[ADBMobile collectPII data:nil];
Analytics Methods
Here is a list of Adobe Analytics methods that are provided by the Android library.
The SDK currently supports multiple Adobe Marketing Cloud Solutions, including Analytics, Target, Audience Manager, andthe Marketing Cloud Visitor ID Service. Methods are prefixed according to the solution, for example, Marketing Cloud visitorID methods are prefixed with analytics.
Each of the following methods is used to send data to your Adobe Analytics report suite:
DescriptionMethod
Tracks an app state with optional context data.trackState
States are the views that are available in your app, such as home dashboard, app settings, cart,and so on. These states are similar to pages on a website, and trackState calls increment page views.
If state is empty, app name app version (build) is displayed in reports. If you see this valuein reports, ensure that you set state in each trackState call.
Tip: This is the only tracking call that increments page views.
Syntax:public static void trackState(String state, Map<String, Object> contextData);
Example:Analytics.trackState("loginScreen", null);
Tracks an action in your app.trackAction
Actions that you want to measure, such as logons, banner taps, feed subscriptions, andother metrics, that occur in your app.
Syntax:public static void trackAction(String state, Map<String, Object> contextData);
Example:Analytics.trackAction("heroBannerTouched", null);
Returns the automatically generated visitor identifier for Analytics.getTrackingIdentifier
This is an app-specific unique visitor ID that is generated at the initial launch and is stored and usedfrom that point forward. The ID is preserved between app upgrades, and when the app is uninstalled,the ID is removed.
Syntax:public static String getTrackingIdentifier();
55Analytics
DescriptionMethod
Example:String trackingId = Analytics.getTrackingIdentifier();
Sends the current latitude, longitude, and location in a defined point of interesttrackLocation
Syntax:public static void trackLocation(Location location, Map<String, Object> contextData);
Example:Analytics.trackLocation(userLocation, null);
Adds amount to the user's lifetime value.trackLifetimeValueIncrease
Syntax: public static void trackLifetimeValueIncrease(BigDecimal amount, Map<String, Object> contextData);
Example:Analytics.trackLifetimeValueIncrease(new BigDecimal(30), null);
Start a timed action with name action.trackTimedActionStart
If you call this method for an action that has already started, the previous timed action is overwritten.
Tip: This call does not send a hit.
Syntax:public static void trackTimedActionStart(String action, Map<String, Object> contextData);
Example:Analytics.trackTimedActionStart("cartToCheckout", null);
Pass in contextData to update the context data that is associated with the action.trackTimedActionUpdate
The data that is passed in is appended to the existing data for the action, and if the same key is alreadydefined for action, overwrites the data.
Tip: This call does not send a hit.
Syntax:public static void trackTimedActionUpdate(String action, Map<String, Object> contextData);
Example:HashMap cdata = new HashMap<String, Object>();cdata.put("quantity", 3);Analytics.trackTimedActionUpdate("cartToCheckout", cdata);
56Analytics
DescriptionMethod
End a timed action.trackTimedActionEnd
If you provide block, you can access the final time values and can manipulate data before sendingthe final hit.
Tip: If you provide block, you must return true to send a hit. Passing null for block sendsthe final hit.
Syntax:public static void trackTimedActionEnd(String action, TimedActionBlock<Boolean> logic);
Example:Analytics.trackTimedActionEnd("cartToCheckout", new Analytics.TimedActionBlock<Boolean>() { @Override public Boolean call(long inAppDuration, long totalDuration, Map<String, Object> contextData) { contextData.put("price", 49.95); return true; }});
Requires SDK 4.1sendQueuedHits
Regardless of how many hits are queued, this method forces the library to send all hits in the offlinequeue.
Syntax:void sendQueuedHits()
Examples:Analytics.sendQueuedHits();
Returns the number of stored tracking calls in the offline queue.getQueueSize
Syntax:long getQueueSize()
Examples:long queueSize = Analytics.getQueueSize();
Clears all of the hits from the offline queue.clearQueue
Syntax:void clearQueue()
Examples:Analytics.clearQueue();
: Use caution when manually clearing the queue. This process cannot be reversed.
57Analytics
AcquisitionThis information helps you use acquisition tracking links in your Android apps.
Mobile App Acquisition
Acquisition links with unique tracking codes can be generated in Adobe Mobile services. When a user downloads and runs anapp from the app store after clicking on the generated link, the SDK automatically collects and sends the acquisition data toAdobe Mobile services.
Important: To use Acquisition, you must have SDK version 4.1 or later.
Acquisition links must be created in Adobe Mobile services. For more information, see App Acquisition Analytics.
In SDK versions 4.13.1 and later:
If you cannot use the acquisition links that are created in Adobe Mobile Services, the acquisition data can still be collected andsent by the SDK by using Google Play Acquisition.
To collect acquisition data from a standard Google Play Acquisition campaign:
• Use the standard Google Play Store acquisition method.
Custom acquisition data can be used with the standard Google Play Acquisition key value pairs.
• When the user downloads and runs an app as the result of a Google Play store acquisition, the data from the referrer will becollected and sent to Adobe Mobile Services.
• The data will be stored and available in the AdobeDataCallback instance that was registered earlier with the SDK.
For more information, see Configuration Methods.
• The MobileDataEvent.MOBILE_EVENT_ACQUISITION_INSTALL or theMobileDataEvent.MOBILE_EVENT_ACQUISITION_LAUNCH event type will be used.
For more information, see MobileDataEvent Enum.
• Custom keys that were part of the acquisition data from Google Play will be name-spaced with "a.acquisition.custom."
If you are using the Acquisition links that were created on Adobe Mobile Services, add custom data to the acquisition link bycompleting the following tasks:
1. Prefix an acquisition variable with "adb".
When the SDK receives the acquisition data from Adobe Mobile Services (on first launch), that data will be stored and alsoavailable in the AdobeDataCallback instance registered earlier with the SDK, as mentioned in Configuration Methods.
2. The MobileDataEvent.MOBILE_EVENT_ACQUISITION_INSTALL or theMobileDataEvent.MOBILE_EVENT_ACQUISITION_LAUNCH event type will be used.
3. The custom data keys will be prefixed with "a.acquisition.custom."
Tip: If you are sending data to multiple report suites, use the acquisition data from the app that is associated with the firstreport suite in your list of report suite IDs.
The updates in this section enable the SDK to send acquisition data from an acquisition link.
58Acquisition
Tracking Mobile Acquisition
1. Add the library to your project and implement lifecycle.
2. Import the library:import com.adobe.mobile.*;
3. Implement the BroadcastReceiver for the referrer:package com.your.package.name; // replace with your app package name
import android.content.BroadcastReceiver;import android.content.Context;import android.content.Intent;
public class GPBroadcastReceiver extends BroadcastReceiver { @Override public void onReceive(Context c, Intent i) { com.adobe.mobile.Analytics.processReferrer(c, i); }}
4. Update AndroidManifest.xml to enable the BroadcastReceiver that was created in the previous step:<receiver android:name="com.your.package.name.GPBroadcastReceiver" android:exported="true">
<intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER" /> </intent-filter></receiver>
5. Verify that ADBMobileConfig.json contains the required acquisition settings:"acquisition": { "server": "c00.adobe.com", "appid": "0652024f-adcd-49f9-9bd7-2552a4565d2f"},"analytics": { "referrerTimeout": 5, ...
Important: If you are sending data to multiple report suites, use the acquisition settings (acquisition server and appid)from the app that is associated with the first report suite in your list of report suite IDs.
The acquisition settings are generated by Adobe Mobile services and should not be changed. For more information abouthow to download a customized ADBMobileConfig.json file with the acquisition settings pre-configured, see BeforeYou Start.
After these settings are enabled, after the initial launch of the app, acquisition data is sent automatically with the initial lifecyclecall.
: referrerTimeout must be set to a value higher than 0 to enable app acquisition.
Acquisition Methods
The following Acquisition methods are provided by the Android library:
59Acquisition
DescriptionMethod
Allows developers to start an app acquisition campaign as if the user clicked a link. This ishelpful for creating manual acquisition links and handling the app store redirect yourself.
campaignStartForApp
Syntaxpublic static void campaignStartForApp(final String appId, final Map<String, Object> data);
ExampleAcquisition.campaignStartForApp("0652024f-adcd-49f9-9bd7-2552a4564d2f", new HashMap<String, Object>() {{ put("custom.key", "value");}});
Tracking Deep Links
You can use this information to track deep and deferred deep links in your mobile apps by using the Adobe Mobile AndroidSDK.
This topic contains the following information:
• Getting Started• Deep Link Public Information
Getting Started
Tracking Deep Links
1. Add the SDK to your project and implement Lifecycle metrics.
For more information, see Core Implementation and Lifecycle.
2. Register the application to handle URLs.
3. Pass Activity with deep link intent to Adobe SDK by using collectLifecycleData.
Here is a sample track deep link:public class ParseDeepLinkActivity extends Activity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);
Config.collectLifecycleData(this); ... }}
The Adobe Mobile SDK can parse key and value pairs of data that is appended to any deep or universal link as long as the linkcontains a key with the a.deeplink.id label and a corresponding non-null and user-generated value. All key and value pairsof data that are appended to the link will be parsed, attached to a lifecycle hit, and sent to Adobe Analytics as long as the linkcontains the a.deeplink.id key and value.
Additionally, you might append one or more of the following reserved keys (with user-generated values) to the deep or universallink:
• a.launch.campaign.trackingcode
60Acquisition
• a.launch.campaign.source• a.launch.campaign.medium• a.launch.campaign.term• a.launch.campaign.content
These keys are pre-mapped variables for reporting in Adobe Analytics. For more information on mapping and processing rules,see Processing Rules and Context Data.
Tracking Deferred Deep Links (for use with Marketing Links)
With a deferred deep link, the Adobe SDK will open a new Intent with the deep link as the intent data. This process is handledas an external deep link using the code above.
Deep Link Public Information
Constants/* * Used for message deep link tracking * Key for deep link URL. */public static final String ADB_MESSAGE_DEEPLINK_KEY = "adb_deeplink";
Tracking Third-Party Deferred Deep Links
Use the Android SDK to implement the tracking of third-party deferred deep links.
This topic contains the following information:
• Classic Adobe Mobile SDK Deep Linking• Facebook Deep Linking• Setting up the SDKs• Enable Deep Linking in an Android Application
Classic Adobe Mobile SDK Deep Linking
The Adobe Mobile SDK currently supports deep linking where the app developer is expected to use the collectLifecycleDataSDK API from the deep linked activity. The SDK appends the deep link data from the deep link URL parameters. For moreinformation about how deep linking works in the Adobe Mobile SDK, see Tracking Deep Links.
Facebook Deep Linking
An ad creator can create an ad on Facebook as a deep link. When users click the ad, it goes directly to the information in whichthey are interested in the app. The deep link, is not a fingerprinter URL. However, during ad configuration, there is an optionto provide a third-party deep link URL. An app developer who is using the Adobe Mobile SDKs and services is expected to enterthe Adobe Mobile Service-configured fingerprinter URL in this field. If everything is set up correctly, the Facebook SDK passesthis URL to the application when the app is installed or launched.
Setting up the SDKs
To prepare to add Facebook deep linking support with the Adobe Mobile SDK, the app developer completes the following tasks:
• Getting Started Android SDK• Deep Linking Set up
61Acquisition
If the application is set up correctly, the trackAdobeDeepLink() API should enable collecting the deep link information fromthe Facebook acquisition campaign and send it to Adobe Mobile Service. If the install hit has not been sent to Adobe MobileService at the first launch, this information will be added to the Lifecycle hit. Otherwise, it will be sent as an Adobe deep linkhit.
Tip: Ensure that the deep link URL has a key called a.deeplink.id. If the URL is missing the deep link ID parameter,the URL parameters will not be appended to the context data.
If the link can be attributed to an acquisition, the Adobe Mobile SDK will store the acquisition data from the Facebook deeplink that was used to call trackAdobeDeepLink(). This data will be available to the Adobe Mobile SDK in future launches.If a callback has been registered, the Adobe callback will also be used to send the data back to the client.
Enable Deep Linking in an Android Application
1. Register the application to handle deep links.
For more information, see Allowing Other Apps to Start your Activity.
2. Link the Facebook SDKs.
To add the Facebook gradle dependency in the app, complete the steps in Getting Started Android SDK.
3. To initialize the Facebook SDK, complete the instructions in the Android Studio Setup section.
4. Call trackAdobeDeepLink() from the main activity.@Overrideprotected void onResume() { super.onResume(); AppEventsLogger.activateApp(this); /* * Adobe Tracking - Config * * call collectLifecycleData() to begin collecting lifecycle data * must be in the onResume() of every activity in your app */ Config.collectLifecycleData(this);
AppLinkData.fetchDeferredAppLinkData(this, new AppLinkData.CompletionHandler() { @Override public void onDeferredAppLinkDataFetched(AppLinkData appLinkData) { // Process app link data if (appLinkData != null) { Config.trackAdobeDeepLink(appLinkData.getTargetUri()); } } } );}
Testing Marketing Link Acquisition
The following instructions help you roundtrip an acquisition campaign with a marketing link on an Android device.
If your mobile app is not yet in Google Play, you can select any mobile app as a destination when creating the marketing link.This only affects the app to which the acquisition server redirects you, after you click the acquisition link, and not the ability to
62Acquisition
test the acquisition link. Query string parameters are passed to the Google Play store, which are passed to the app at install aspart of a campaign broadcast. Roundtrip mobile app acquisition testing requires the simulation of this type of broadcast.
The app must be freshly installed, or have data cleared in Settings, each time a test is run. This ensures that the initial lifecyclemetrics that are associated with the campaign query string parameters are sent when the app is first launched.
1. Complete the prerequisite tasks in Mobile App Acquisition and ensure that you have correctly implemented the broadcastreceiver for INSTALL_REFERRER.
2. In the Adobe Mobile Services UI, click Acquisition > Marketing Links Builder and generate an acquisition marketing linkURL that sets Google Play as the destination for Android devices.
For more information, see Marketing Links Builder.
For example:https://c00.adobe.com/v3/da120731d6c09658b82d8fac78da1d5fc2d09c48e21b3a55f9e2d7344e08425d/start?a_dl=573e5bb3248a501360c2890b
3. Open the generated link on the Android device.
You should be redirected to a page with a URL similar to the following example:https://play.google.com/store/apps/details?id=com.adobe.android&referrer=utm_campaign%3Dadb_acq_v3%26utm_source%3Dadb_acq_v3%26utm_content%3D91b52ce097b1464b9b47cb2995c493cc6ab2c3a3
4. Copy the unique ID after utm_content%3D.
In the previous example, the ID is 91b52ce097b1464b9b47cb2995c493cc6ab2c3a3.
If you cannot get the unique ID on the device, run the following CURL command on your desktop to get the unique ID fromthe response string.curl -A "Mozilla/5.0 (Linux; Android 5.0.2; SAMSUNG SM-T815Y Build/LRX22G) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.133 Safari/537.36" <Your Marketing Link>
For example:curl -A "Mozilla/5.0 (Linux; Android 5.0.2; SAMSUNG SM-T815Y Build/LRX22G) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.133 Safari/537.36" https://c00.adobe.com/v3/da120731d6c09658b82d8fac78da1d5fc2d09c48e21b3a55f9e2d7344e08425d/start?a_dl=573e5bb3248a501360c2890b
5. Construct the acquisition end link by using the unique ID from step 3, by using the following format:http://c00.adobe.com/v3/<appid>/end?a_ugid=<unique id>
For example:http://c00.adobe.com/v3/<appid>/end?a_ugid=91b52ce097b1464b9b47cb2995c493cc6ab2c3a3
6. Open the link in a browser.
You should be see the contextData in the JSON response:{"fingerprint":"44b2f88a062df7e727c047f006deb9971304617b","endCallbacks":["***"],"timestamp":1464301282,"appguid":"da120731d6c09658b82d8fac78da1d5fc2d09c48e21b3a55f9e2d7344e08425d","contextData":{"a.launch.campaign.trackingcode":"trymttvm","a.referrer.campaign.name":"Android Demo","a.referrer.campaign.trackingcode":"trymttvm"},"adobeData":{"unique_id":"9a2be52764a8db125c29a8c10f3b1b3d5d8ed915","deeplinkid":"57476c26072932ec6d3a470b"}}.
7. Repeat step 3 to get a new unique ID.8. Verify that the following settings in your config file are correct:
ValueSetting
The server should be c00.adobe.comacquisition
appid should equal the <appid> in your acquisition link
63Acquisition
ValueSetting
For testing purposes, set the referrer timeout to allow for adequate time (60 seconds or more)to manually send the broadcast. You can restore the original timeout setting after testing.
analytics
9. Connect the device to a computer, uninstall, and install the app again.10. Launch ADB Shell and launch the application on the device.
adb shell
11. Send a broadcast by using the following adb command:am broadcast -a com.android.vending.INSTALL_REFERRER -n com.adobe.android/com.adobe.android.YourBroadcastReceiver --es "referrer" "utm_source=adb_acq_v3&utm_campaign=adb_acq_v3&utm_content=<unique id get on step 5>"
12. Replace com.adobe.android with your application's package name, update the receiver reference with the reference ofthe location of the campaign tracking receiver in your app, and replace the values that are associated with utm_content.
If the broadcast is successful, you should expect a response like the following example:Broadcasting: Intent{ act=com.android.vending.INSTALL_REFERRER cmp=com.adobe.adms.tests/.ReferralReceiver (has extras) }Broadcast completed: result=0
13. (Optional) You can enable debug logging of the SDK to obtain additional information.
If everything works correctly, you should see following logs:"Analytics - Received referrer information(<referrer content>)""Analytics - Trying to fetch referrer data from (acquisition end url)";"Analytics - Received Referrer Data(<A JSON Response>)"
If you do not see these logs, verify that you have completed performed steps 6 to 10.
The following table contains additional information about the possible errors:
DescriptionError
The response is malformed.Analytics - Unable to decode
response(<String>).
The JSON string is malformed.Analytics - Unable to parse response(<A
JSON Response>.
There in no contextData parameter in the response.Analytics - Unable to parse acquisition
service response (no contextData
parameter in response).
a.referrer.campaign.name is not included incontextData.
Analytics - Acquisition referrer data was
not complete (no a.referrer.campaign.name
in context data), ignoring.
Failed to get the response in the time defined byreferrerTimeout. Increase the value and try again.
Analytics - Acquisition referrer timed
out.
64Acquisition
DescriptionError
You should also ensure that you've opened the acquisitionlink before installing the app.
Remember the following information:
• Hits that are sent from the app can be monitored by using HTTP monitoring tools to verify the acquisition attribution.
• For more information about how to broadcast INSTALL_REFERRER, see Testing Google Play Campaign Measurement in theGoogle Developers guide .
• You can use the provided acquisitionTest.jar Java tool to help you get the unique ID and broadcast install referrer,which in turn, helps you obtain the information in steps 3 to 10.
Install the Java Tool
To install the Java tool:
1. Download acquistionTester.zip.2. Extract the .jar file.
You can run the .jar file on the command line.
For example:java -jar acquisitionTester.jar -a com.adobe.test -r com.adobe.test.ReferrerReceiver -l "https://c00.adobe.com/v3/appid/start?a_i_id=123456&a_g_id=com.adobe.test&a_dd=i&ctxa.referrer.campaign.name=name&ctxa.referrer.campaign.trackingcode=1234
• The marketing links are cached on the server side with a ten-minutes expiration time.
When you make changes to marking links, wait about 10 minutes before the changes take effect before you use the links again.
Testing Version 3 Acquisition
This information helps you roundtrip a version 3 acquisition campaign link on an Android device.
Important: Acquisition in version 3 refers to the acquisition links that you create with the Acquisition Builder in the AdobeMobile Services UI. To use this feature, you must upgrade to Android SDK 4.x for Marketing Cloud Solutions 4.6.0 or later.
If the mobile app is not yet in Google Play, when creating the campaign link, you can select any mobile app as a destination.This only affects the app to which the acquisition server redirects you after you click the acquisition link, but does not affect theability to test the link. Query string parameters are passed to the Google Play store, which are passed to the app at install as partof a campaign broadcast. Roundtrip mobile app acquisition testing requires the simulation of this type of broadcast.
The app must be freshly installed, or have data cleared in Settings, each time a test is run. This ensures that the initial lifecyclemetrics that are associated with the campaign query string parameters are sent when the app is first launched.
1. Complete the prerequisite tasks in Mobile App Acquisition and ensure that you have correctly implemented the broadcastreceiver for INSTALL_REFERRER.
2. In the Adobe Mobile Services UI, click Acquisition > Marketing Links Builder and generate an acquisition marketing linkURL that sets Google Play as the destination for Android devices.
For more information, see Marketing Links Builder.
65Acquisition
For example:http://c00.adobe.com/v3/<appid>/start?a_i_id=iostestapp&a_g_id=com.adobe.android&a_dd=g&ctxa.referrer.campaign.name=name&ctxa.referrer.campaign.trackingcode=trackingcode
Tip: If you refer to both Android and iOS apps in the acquisition link, use Google Play as the default store.
3. Open the generated link in a desktop browser.
You should be redirected to a page with a URL similar to the following example:https://play.google.com/store/apps/details?id=com.adobe.android&referrer=utm_campaign%3Dadb_acq_v3%26utm_source%3Dadb_acq_v3%26utm_content%3D91b52ce097b1464b9b47cb2995c493cc6ab2c3a3
4. Copy the unique ID after utm_content%3D.
In the previous example, the ID is 91b52ce097b1464b9b47cb2995c493cc6ab2c3a3.
5. Construct the acquisition end link by using the unique ID from step 3 by using the following format:http://c00.adobe.com/v3/<appid>/end?a_ugid=<unique id>
For example:http://c00.adobe.com/v3/<appid>/end?a_ugid=91b52ce097b1464b9b47cb2995c493cc6ab2c3a3
6. Open the link in a desktop browser.
You should be see the contextData in the JSON response:{"fingerprint":"228d7e6058b1d731dc7a8b8bd0c15e1d78242f31","timestamp":1457989293,"appguid":"","contextData":{"a.referrer.campaign.name":"name","a.referrer.campaign.trackingcode":"trackingcode"}}.
If you do not see contextData, or some of the string is missing, ensure that the acquisition URL follows the format inCreate Acquisition Link Manually.
7. Repeat step 3 to obtain a new unique ID.8. Verify that the following settings in your config file are correct:
ValueSetting
The server should be c00.adobe.comacquisition
appid should equal the <appid> in your acquisition link
For testing purposes, set the referrer timeout to allow for adequate time (60 seconds or more)to manually send the broadcast. You can restore the original timeout setting after testing.
analytics
9. Connect the device to a computer, uninstall, and install the app again.10. Launch ADB Shell and launch the application on the device.11. Send a broadcast by using the following adb command:
am broadcast -a com.android.vending.INSTALL_REFERRER -n com.adobe.android/com.adobe.android.YourBroadcastReceiver --es "referrer" "utm_source=adb_acq_v3&utm_campaign=adb_acq_v3&utm_content=<unique id get on step 5>"
12. Complete the following steps:a) Replace com.adobe.android with your application's package name.b) Update the receiver reference with that of the location of the campaign tracking receiver in your appc) Replace values that are associated with utm_content.
If the broadcast is successful, you can expect a response similar to the following example:Broadcasting: Intent{ act=com.android.vending.INSTALL_REFERRER cmp=com.adobe.adms.tests/.ReferralReceiver (has
66Acquisition
extras) }Broadcast completed: result=0
13. (Optional) You can enable debug logging of the SDK to obtain additional information.
If everything works correctly, you should see following logs:"Analytics - Received referrer information(<referrer content>)""Analytics - Trying to fetch referrer data from (acquisition end url)";"Analytics - Received Referrer Data(<A JSON Response>)"
If you do not see the above logs, verify that you completed steps 6 to 12.
The following table contains additional information about the possible errors:
DescriptionError
The response is malformed.Analytics - Unable to decode
response(<String>).
The JSON string is malformed.Analytics - Unable to parse response(<A
JSON Response>).
There in no contextData parameter in the response.Analytics - Unable to parse acquisition
service response (no contextData
parameter in response).
a.referrer.campaign.name is not included incontextData.
Analytics - Acquisition referrer data was
not complete (no a.referrer.campaign.name
in context data), ignoring.
Failed to get the response in the time defined byreferrerTimeout. Increase the value and try again.
Analytics - Acquisition referrer timed
out.
You should also ensure that you have opened the acquisitionlink before installing the app.
Remember the following information:
• Hits sent from the app can be monitored by using HTTP monitoring tools to verify the acquisition attribution.
• For more information about how to broadcast INSTALL_REFERRER, see Testing Google Play Campaign Measurement in theGoogle Developers guide.
• A bug fix was released for acquisition on Android 4.8.2.
Before testing, upgrade the SDK to the latest version.
• You can use the provided acquisitionTest.jar Java tool to help you get the unique ID and broadcast install referrer,which in turn, helps you obtain the information in steps 3 to 12.
Install the Java Tool
To install the Java tool:
1. Download acquistionTester.zip.2. Extract the .jar file.
67Acquisition
You can run the file on the command line.
For example:java -jar acquisitionTester.jar -a com.adobe.test -r com.adobe.test.ReferrerReceiver -l "https://c00.adobe.com/v3/appid/start?a_i_id=123456&a_g_id=com.adobe.test&a_dd=i&ctxa.referrer.campaign.name=name&ctxa.referrer.campaign.trackingcode=1234
Testing Legacy Acquisition
The following information helps you roundtrip a legacy acquisition campaign link on an Android device.
If the mobile app is not yet in Google Play, you can select any mobile app as a destination when creating the campaign link. Thisonly affects the app to which the acquisition server redirects you, after you click the acquisition link, and not the ability to testthe acquisition link. Query string parameters are passed to the Google Play store, which are passed to the app at install as partof a campaign broadcast. Roundtrip mobile app acquisition testing requires the simulation of this type of broadcast.
The app must be freshly installed, or have data cleared in Settings, each time a test is run. This ensures that the initial lifecyclemetrics that are associated with the campaign query string parameters are sent when the app is first launched.
1. In the Mobile Services UI, generate a legacy acquisition campaign URL.For more information, see Use Legacy Acquisition Links.
2. Connect the device to a computer, launch ADB Shell, and launch the application on the device.3. Send a broadcast using the following format:
am broadcast -a com.android.vending.INSTALL_REFERRER -n com.example.adobetesttapp/com.google.analytics.tracking.android.CampaignTrackingReceiver --es "referrer" "utm_source=testSource&utm_medium=testMedium&utm_term=testTerm&utm_content=testContent&utm_campaign=testCampaign&trackingcode=trackingvalue"
4. Complete the following steps:a) Replace com.example.adobetesttapp.com with your application's reverse DNS entry.b) Update the receiver reference with the campaign tracking receiver location reference in your app.c) Replace values that are associated with utm_source, utm_medium, utm_term, utm_content, utm_campaign,
and so on, with appropriate values.
If the broadcast is successful, a response similar to the one below is displayed:Broadcasting: Intent { act=com.android.vending.INSTALL_REFERRER cmp=com.example.analyticsecommtest/com.google.analytics.tracking.android.AnalyticsReceiver has extras) } Broadcast completed: result=0
You will also see an image request sent to Adobe's data collection servers. If the SDK waits for the complete duration of thereferrer timeout, which you set in step 1, with an image request that does not include campaign parameters, the broadcast failed.
68Acquisition
MessagingThis information helps you use messaging in your Android apps.
In-App Messaging
You can deliver in-app messages that are triggered from any analytics data or event. After the implementation, messages aredynamically delivered to the app and do not require a code update.
Important: To use in-app messaging, you must have SDK version 4.2 or later.
You can create messages and the rules in Adobe Mobile services that define when messages are displayed. For more information,see Create an in-app message. To display in-app messages, updates must be made to the SDK. You can complete these steps evenif you have not yet defined any messages. After you define messages, they will be delivered dynamically to your app and displayedwithout an app store update.
This topic contains the following information:
• Enabling In-App Messaging• Local Fallback Image• Configuring Notification Icons
Enabling In-App Messaging
1. Add the library to your project and implement lifecycle.
2. Update AndroidManifest.xml to declare the full screen activity and enable the Message Notification Handler:<activity android:name="com.adobe.mobile.MessageFullScreenActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" /><receiver android:name="com.adobe.mobile.MessageNotificationHandler" />
If you selected a modal layout, select one of the following themes for the message:
• Theme.Translucent.NoTitleBar.Fullscreen
• Theme.Translucent.NoTitleBar
• Theme.Translucent
For example:<activityandroid:name="com.adobe.mobile.MessageFullScreenActivity"android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"android:windowSoftInputMode="adjustUnspecified|stateHidden" /><receiver android:name="com.adobe.mobile.MessageNotificationHandler" />
3. Import the library:import com.adobe.mobile.*;
4. In each collectLifecycleData call, pass this to provide a reference to your current activity:@Overridepublic void onResume() { Config.collectLifecycleData(this);}
5. Verify that ADBMobileConfig.json contains the required settings for in-app messaging.
69Messaging
Important: messages or remotes is required.
For in-app messages to be dynamically updated on launch, the remotes object must be present and properly configured:“messages”: [ { “messageId”: “de45c43c-37bf-441f-8cbd-cc3ba3469ebe”, “template”: “fullscreen”, “showOffline”: false, “showRule”: “always”, “endDate”: 2524730400, “startDate”: 0, “audiences”: [], “triggers”: [], “payload”: { // contents change depending on template “html”: “<html>html code goes here</html>” }, }, …]“remotes” : { “analytics.poi”: “https://assets.adobedtm.com/…/yourfile.json”, “messages”: “https://assets.adobedtm.com/…/yourfile.json”}
If this object is not configured, download an updated ADBMobileConfig.json from Adobe Mobile services. For moreinformation, see Before You Start.
Local Fallback Image
When creating a full-screen message, you can optionally specify a fallback image. If your message cannot retrieve its intendedimage from the web, the SDK attempts to load the image with the same name from your application’s assets folder. This allowsyou to show your message in its original form, even if the user is offline, or the predetermined image is unreachable.
Important: The fallback image asset name is specified when you configure the message in Adobe Mobile services, and youneed to ensure that the specified resource is available.
Configuring Notification Icons
The following methods allow you to configure the small and large icons that appear in the notification area, and the large iconthat is displayed when notifications appear in the notification drawer.
DescriptionMethod
Set the small icon that will be used for notifications that are created by the SDK. This icon appearsin the status bar and is the secondary image that is displayed shown when the user sees the completenotification in the notification center.
Config.setSmallIconResourceId(int
resourceId)
Syntax:public static void setSmallIconResourceId(final int resourceId);
Example:Config.setSmallIconResourceId(R.drawable.appIcon);
70Messaging
DescriptionMethod
Set the large icon that will be used for notifications that are created by the SDK. This icon will bethe primary image that is displayed when the user sees the complete notification in the notificationcenter.
Config.setLargeIconResourceId(int
resourceId)
Syntax:public static void setLargeIconResourceId(final int resourceId);
Example:Config.setLargeIconResourceId(R.drawable.appIcon);
Troubleshooting In-App Messaging
This information helps you troubleshoot in-app messaging.
If you have completed all the requirements for In-App Messaging, but messages do not display, check the following items:
SuggestionSituation or Issue
Verify that the SDK is version 4.2 or higher and is correctly configured. For moreinformation, see View Hits for a screen shot showing the SDK version.
Are you putting the newconfiguration and new SDK in theapp? Ensure that you have a Messages section in your configuration (downloaded JSON file),
or have a Messages remote endpoint, so that it can be retrieved from dynamic tagmanagement.
Important: As of April 30, 2017, Adobe Bloodhound has been sunset. Starting onMay 1, 2017, no additional enhancements and no additional Engineering or AdobeExpert Care support will be provided.
Did you update your manifest file to define the full screen activity?My full screen message in Androidis not showing up. I am using thecorrect SDK, configuration, and mytriggers are being met.
Ensure that the local notification broadcast receiver is declared in your manifest.My local notification message inAndroid is not working. For more information, see step 2 in Enabling In-App Messaging.
To verify whether your message is live, on the Manage In-App Message page, in theStatus column, check the list of messages.
Is the message live?
Verify the assumptions in data for traits/trigger in Bloodhound.Double check the traits/triggersections. Validate the hits in Bloodhound. For more information, see View Hits in Bloodhound
documentation for a screen shot that displays the SDK version.
71Messaging
SuggestionSituation or Issue
Important: As of April 30, 2017, Adobe Bloodhound has been sunset. Starting onMay 1, 2017, no additional enhancements and no additional Engineering or AdobeExpert Care support will be provided.
Verify that these settings are set the way you want. On the Audience tab, review yourTrigger options, which allow you to specify how often the message is shown.
Look at show once, show always,show offline settings on the Audiencetab.
Launch only fires on a new session. For more information about when a session begins,see the lifecycleTimeout row in JSON Config.
If using launch event as trigger...
Complete one of the following tasks:I updated my message remotely, butmy app is still showing the oldmessage.
• Dynamic tag management can take a few minutes to update its endpoint with your newdefinition.
Wait for some time and try again.
• The config will only update on a new launch.
If the app was restarted during the life cycle session timeout, your new config might nothave been downloaded.
For more information, see Lifecycle Metrics.
The In-App Message full-screen template supports displaying an image from a remoteserver (Image URL) or from the app bundle (Bundled Image). The image should be in astandard image format, such as JPG, GIF or PNG.
My image does not fit exactly intothe space provided by the template.
Because device screens have many different dimensions, the image will most likely notfit exactly into the space provided by the template. The template focuses on showing thecenter of the image and, if the image does not fit, crops (portrait) or fades (landscape)the sides.
Here is the exact placement and sizing rules for each orientation:
• Portrait
• A height of 195px for phones
• A height of 529px for tablets
• Centered if the image width is smaller than the device width.
• Cropped if the image width is greater than the device width.
• Landscape
• The image scaled to 100% of the height of the device.• The width is 75% of the device, with a fade out on the right.
72Messaging
SuggestionSituation or Issue
If you have issues with the full-screen template, you can download and use the CustomHTML template. This template provides more flexibility for images and allows full controlof the template.
Push Messaging
Adobe Mobile and the Adobe Mobile SDK allow you to send push messages to your users. The SDK also allows you to easilyreport users who have opened your app after clicking through a push message.
Important: To use push messaging, you must have SDK version 4.6 or later.
Important: Do not manually set the Marketing Cloud Visitor ID inside your app. This causes the creation of a new uniqueuser that will not receive push messages because of its opt-in status. For example, a user has opted-in to receive push messageslogs in to your app. After logging in, if you manually set the ID inside your app, a new unique user is created who has notopted to receive push messages. This new user will not receive your push messages.
This section contains the following information:
• Prerequisites• Enable Push Messaging
Prerequisites
• Add the library to your project and implement lifecycle metrics.
• SDK must be enabled for Visitor ID Service.
Enable Push Messaging
Tip: If your app is already set up to use messaging by using Google Cloud Messaging (GCM), some of the following stepsmight already be completed.
1. Verify that ADBMobileConfig.json contains the required settings for push messaging.
The "marketingCloud" object must have its "org" property configured for push messaging."marketingCloud": { "org": <org-id-string> }
2. Obtain the registration ID/token by using the GCM or Firebase Cloud Messaging (FCM) APIs.
• GCM
• For more information about setting up GCM, see Set up a GCM Client App on Android.• To implement a sample app, see Google Samples.
InstanceID instanceID = InstanceID.getInstance(this);String token = instanceID.getToken(getString(R.string.gcm_defaultSenderId), GoogleCloudMessaging.INSTANCE_ID_SCOPE, null);
73Messaging
• FCM
• For more information about setting up FCM, see Set Up a Firebase Cloud Messaging Client App on Android.
String token = FirebaseInstanceId.getInstance().getToken();
3. The registration ID/token must be passed to the SDK by using the Config.setPushIdentifier(final StringregistrationId) method.Config.setPushIdentifier(token); // token was obtained in step 2
4. Enable reporting by passing your activity in the collectLifecycleData method.
Here are the requirements to enable push click-through reporting:
• In your implementation of GCMListenerService, the Bundle object that contains the message data, which is passed intothe onMessageReceived method, must be added to the Intent that is used to open the target activity on a click-through.
This can be done using the method putExtras (Click here for more info).
• In the target activity of the clickthrough, the activity must be passed into the SDK with the collectLifecycleData call.
Remember the following information:
• Use Config.collectLifecycleData(this) or Config.collectLifecycleData(this, contextData).• Do not use Config.collectLifecycleData().
Implement Push Messaging with Deep Linking
After you configure the deep linking URL in the Adobe Mobile Services UI, this URL will be in the push payload with theadb_deeplink key.
You can get the URL by calling data.getString("adb_deeplink") in the customized GcmListenerService class orremoteMessage.getData().get("adb_deeplink") in the FirebaseMessagingService.
Tip: You can define different intents depending on whether the payload has a deep linking URL.
1. Complete one of the following tasks:
• If the deep linking URL is in the push payload, create a ACTION_VIEW intent with the URL.
When the user clicks the push message, a deep link is triggered.
• If the deep linking URL is not in the push payload, create an intent that will open one of your activities.
Here is an example that uses a GCM implementation to pass data to the Mobile SDK after the message is received: @Overridepublic void onMessageReceived(String from, Bundle data) { String message = data.getString("message"); String deeplink = data.getString("adb_deeplink"); sendNotification(message, deeplink);}
private void sendNotification(String messageBody, String deeplink) { Intent intent; if (deeplink!=null) { intent = new Intent(Intent.ACTION_VIEW, Uri.parse(deeplink)); } else { intent = new Intent(this, MainActivity.class); }
74Messaging
intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP); PendingIntent pendingIntent = PendingIntent.getActivity(this, 0 /* Request code */, intent,
PendingIntent.FLAG_ONE_SHOT);
Uri defaultSoundUri= RingtoneManager.getDefaultUri(RingtoneManager.TYPE_NOTIFICATION); NotificationCompat.Builder notificationBuilder = new NotificationCompat.Builder(this) .setSmallIcon(R.drawable.ic_stat_ic_notification) .setContentTitle("Deep Link Push") .setContentText(messageBody) .setAutoCancel(true) .setSound(defaultSoundUri) .setContentIntent(pendingIntent);
NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
notificationManager.notify(0 /* ID of notification */, notificationBuilder.build()); }
This is a sample implementation for the class extending from FirebaseMessagingService:public void onMessageReceived(RemoteMessage message) {
Map<String, String> data = message.getData(); String messageStr = data.get("message"); String deepLink = data.get("adb_deeplink");
sendNotification(deepLink, messageStr, data); }
private void sendNotification(String deeplink, String message, Map<String, String> data) { Intent intent;
if (deeplink!=null) { intent = new Intent(Intent.ACTION_VIEW, Uri.parse(deeplink)); } else { intent = new Intent(this, MainActivity.class); }
intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
//put the data map into the intent to track clickthroughs Bundle pushData = new Bundle(); Set<String> keySet = data.keySet(); for (String key : keySet) { pushData.putString(key, data.get(key)); }
intent.putExtras(pushData);
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_ONE_SHOT);
Uri defaultSoundUri= RingtoneManager.getDefaultUri(RingtoneManager.TYPE_NOTIFICATION);
NotificationCompat.Builder notificationBuilder = new NotificationCompat.Builder(this) .setSmallIcon(R.drawable.icon) .setContentTitle("FCM Deep Link Push") .setContentText(message) .setAutoCancel(true) .setSound(defaultSoundUri) .setContentIntent(pendingIntent);
NotificationManager notificationManager =
(NotificationManager)getApplicationContext().getSystemService(Context.NOTIFICATION_SERVICE);
75Messaging
notificationManager.notify(0, notificationBuilder.build()); }
Receive Rich Push Notifications
You can attach image files to your Android notifications. Adding visual components can significantly increase your user'sengagement with push notifications.
Handle the Incoming Rich Push Message (GCM)
If the app is in the foreground, the push message will be handled by the app that extends the GcmListenerService class andis declared in the manifest file in the following way:<service android:name="com.mycompany.MyGcmListenerService" android:exported="false" > <intent-filter> <action android:name="com.google.android.c2dm.intent.RECEIVE" /> </intent-filter></service>
Important: The class that contains the onMessageReceived() implementation to handle the data that is received.
If the push message contains a Media URL, the URL will be available in the Bundle parameter that is passed to theonMessageReceived() function. The key to be used is attachment-url as shown in the following code sample:public class MyGcmListenerService extends GcmListenerService { @Override public void onMessageReceived(String from, Bundle data) { Intent intent = new Intent(this, MainMenuActivity.class);intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
//put the data bundle in the intent to track clickthroughsintent.putExtras(data);
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_ONE_SHOT);
Uri defaultSoundUri= RingtoneManager.getDefaultUri(RingtoneManager.TYPE_NOTIFICATION);
NotificationCompat.Builder notificationBuilder = new NotificationCompat.Builder(this) .setSmallIcon(R.drawable.icon) .setContentTitle("ADBMobileSamples") .setContentText(message) .setAutoCancel(true) .setSound(defaultSoundUri) .setContentIntent(pendingIntent);
//Handle image url if present in the push messageString attachmentUrl = data.getString("attachment-url");
if (attachmentUrl != null) { Bitmap image = getBitmapFromURL(attachmentUrl); if (image != null) { notificationBuilder.setStyle(new NotificationCompat.BigPictureStyle().bigPicture(image));
}}//Display the NotificationNotificationManager notificationManager = (NotificationManager)getApplicationContext().getSystemService(Context.NOTIFICATION_SERVICE);notificationManager.notify(0, notificationBuilder.build());
}
76Messaging
}
Important: When you set NotificationCompat.BigPictureStyle, large images might not be displayed. To ensurethat large images are always displayed, set the native Notification.BigPictureStyle.
Sample Rich Push Notification
Here is an example of a rich push notification with an image:
For more information about rich push notifications with Android, see Engage with Rich Notifications.
77Messaging
Troubleshooting Push Messaging
This information helps you troubleshoot push messaging.
DescriptionSituation or issue
The following types of delays might be associated with push messages for MobileServices:
Why are there sometimes delayssending push messages?
• Waiting for Analytics Hits
Every report suite has a setting to determine when to process incoming Analytics hits.The default is 1 hour on the hour. The actual processing of Analytics hits might takeup to 30 minutes but is typically 15-20 minutes.
For example, a report suite processes hits every hour. If you factor in the processingtime of a maximum of 30 minutes, it could take up to 90 minutes for an incoming hitto be available for a push message. If a user launched the app at 9:01 AM, the hit wouldshow up in the Mobile Services UI as a new unique user between 10:15 to 10:30 AM.
• Waiting for Push Service
The push service (APNS or GCM) might not immediately send out the message.Although uncommon, we have seen a delay of 5-10 minutes. On the Messages page,you can verify that the push message has been sent to the push service by clicking theView link for the message. In the report, the number of successful sends to the pushservice is listed in the Published column.
Tip: The push services do not guarantee a message will be sent. For moreinformation about the reliability of services, see the appropriate documentation:
• APNS: Quality of Service
• GCM: Lifetime of a Message
For some Android devices, you might need to useNotificationCompat.BigTextStyle when displaying messages.
Why are my push messages being cutoff or are not expanding?
78Messaging
LocationThis information helps you use the Location feature in your Android apps.
Geo-Location and Points of Interest
Geo-location helps you measure location data by using latitude and longitude and predefined points of interest in your Androidapps.
Each trackLocation call sends the following information:
• Latitude, longitude, and location in a point of interest (POI) that is defined in the Adobe Mobile Services UI.
This information is passed to mobile solution variables for automatic reporting.
• Distance from center and accuracy passed as context data.
These variables are not captured automatically. You must map these context data variables by using the instructions in SendingAdditional Data.
This section contains the following information:
• Dynamic POI updates• Tracking Geo-Location and POIs• Sending Additional Data• Location Context Data• Additional Information
Dynamic POI updates
Starting in version 4.2, POIs are defined in the Adobe Mobile UI and dynamically synchronized to the app configuration file.This synchronization requires an analytics.poi setting in the ADBMobile JSON Config:“analytics.poi”: “https://assets.adobedtm.com/…/yourfile.json”,
If this is not configured, you must download an updated version of the ADBMobile.json file and add it to your app. For moreinformation, see Download the SDK.
Tracking Geo-Location and POIs
1. Add the library to your project and implement lifecycle.2. Import the library:
import com.adobe.mobile.*;
3. Call trackLocation to track the current location:Location currentLocation = new Location("my location here");Analytics.trackLocation(currentLocation, null);
Tip: You can call trackLocation at any time.
You can use Android Location Strategies to determine the location that is passed to the trackLocation call.
Additionally, if the location is determined to be in a defined POI radius, an a.loc.poi context data variable is sent in with thetrackLocation hit and is reported as a POI on the Location Breakdown reports. An a.loc.dist context variable is alsosent with the distance in meters from the defined coordinates.
79Location
Sending Additional Data
In addition to the location data, you can send additional context data with each track location call:HashMap<String, Object> locationContextData = new HashMap<String, Object>();locationContextData.put("myapp.location.LocationSource", "GPS");
Location currentLocation = new Location("my location here");Analytics.trackLocation(currentLocation, locationContextData);
Context data values must be mapped to custom variables in the Adobe Mobile Services UI:
Location Context Data
The latitude and longitude are sent by using three different context data parameters, with each parameter representing a differentlevel of precision, for a total of six context data parameters.
For example, the coordinates lat = 40.93231, long = -111.93152 represent a location with 1 m precision. This location is splitaccording to the level of precision across the following variables:
a.loc.lat.a = 040.9
a.loc.lat.b = 32
a.loc.lat.c = 31
a.loc.lon.a = -111.9
a.loc.lon.b = 31
a.loc.lon.c = 52
Some precision levels might appear as 00 depending on the accuracy of the current location. For example, if the location iscurrently accurate to 100m, a.loc.lat.c and a.loc.lon.c will be populated with 00.
Additional Information
Remember the following information:
• A trackLocation request sends in the equivalent of a trackAction call.• POIs are not passed as part of typical trackAction and trackState calls, so you must use a trackLocation call to track
POIs.• trackLocation should be called as often as necessary to track location and POIs.
We recommend calling trackLocation when the app starts and then as needed, depending on the app's requirements.
80Location
• POIs are populated only after they are defined in the app's configuration file.
The POIs are not applied to historical trackLocation calls that were previously sent.
• trackLocation calls support sending additional context data similar to trackAction calls.• When two POIs have overlapping diameters, the first POI that contains the current location is used.
If your POIs overlap, you should list POIs in order of most to least granular to ensure that the most granular POI is reported.
Beacon tracking
Beacon tracking allows you to measure and target micro locations by using iBeacon and Bluetooth Low Energy.
The following beacon data is sent to Analytics and Target when trackBeacon is called:
• a.beacon.uuid - ProximityUUID of the beacon• a.beacon.major - Major number of the beacon (such as store number)• a.beacon.minor - Minor number of the beacon (such as a unique number within a store)• a.beacon.prox - Values of 0-3 represent how close the user is to the beacon.
Here is what these values mean:
• 0 = unknown• 1 = immediate• 2 = near• 3 = far
This beacon data is captured in mobile solution variables.
Tracking Beacons
1. Add the library to your project and implement lifecycle.2. Import the library:
import com.adobe.mobile.*;
3. Gather beacon location.
Multiple third-party libraries are available to scan Bluetooth LE beacons, depending on the manufacturer of the beacon.
4. After the beacon information has been obtained, use the following call to track the location:// assumed that the following variables will have been retrieved by the 3rd party beacon libraryString beaconUUID;String major;String minor;Analytics.BEACON_PROXIMITY proximity; // BEACON_PROXIMITY is an enum available in the SDK. Number 0-3 representing how close the// user is to the beacon. 0 unknown, 1 immediate, 2 near, 3 far. Analytics.trackBeacon(beaconUUID, major, minor, proximity, null);
5. When the user leaves the beacon's proximity, clear the current beacon:Analytics.clearBeacon();
81Location
Sending Additional Data
In addition to the beacon data, you can send additional context data with each trackBeacon call:HashMap cdata = new HashMap<String, Object>();cdata.put("myapp.ImageLiked", imageName);Analytics.trackBeacon(beaconUUID, major, minor, proximity, cdata);
Context data values must be mapped to custom variables in the Adobe Mobile services UI:
82Location
TargetThis information helps you deliver targeted content in Android applications.
Target Configuration
You can deliver targeted content in Android applications.
Set the Application Context
(Required) The setContext() method must be called once in the onCreate() method of your main activity.
For example:@Overridepublic void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); Config.setContext(this.getApplicationContext());}
If you already added this method call when you implemented Analytics or Audience Management, you do not need to add itagain.
Target Methods
Here is the list of Adobe Target methods that are provided by the Android library.
The SDK currently supports multiple Adobe Marketing Cloud Solutions, including Analytics, Target, Audience Manager, andthe Marketing Cloud Visitor ID Service. Methods are prefixed according to the solution. For example, Marketing Cloud visitorID methods are prefixed with target.
Tip: Lifecycle Metrics are sent as parameters to each mbox load.
Class Reference : TargetLocationRequest
Properties:public String name;public String defaultContent;public HashMap<String, Object> parameters;
String Constants
Tip: The following constants are for ease of use when you set keys for custom parameters.
public static final String TARGET_PARAMETER_ORDER_ID = "orderId";public static final String TARGET_PARAMETER_ORDER_TOTAL = "orderTotal";public static final String TARGET_PARAMETER_PRODUCT_PURCHASE_ID = "productPurchasedId";public static final String TARGET_PARAMETER_CATEGORY_ID = "categoryId";public static final String TARGET_PARAMETER_MBOX_3RDPARTY_ID = "mbox3rdPartyId";public static final String TARGET_PARAMETER_MBOX_PAGE_VALUE = "mboxPageValue";public static final String TARGET_PARAMETER_MBOX_PC = "mboxPC"; // pcId in cookiepublic static final String TARGET_PARAMETER_MBOX_SESSION_ID = "mboxSession"; // sessionId in cookiepublic static final String TARGET_PARAMETER_MBOX_HOST = "mboxHost";
83Target
Important:
• If you are using SDKs before version 4.14.0, see http://developers.adobetarget.com/api/#input-parameters for parameterslimitations.
• If you are using SDKs version 4.14.0 or after, see http://developers.adobetarget.com/api/#batch-input-parameters forparameters limitations.
DescriptionMethod
Sends request to your configured Target server and returns the string value of the offer that isgenerated in a block callback.
loadRequest
Syntax:
public static void loadRequest(TargetLocationRequest request, TargetCallback<String> callback);
Example:
Target.loadRequest(heroBannerRequest, new Target.TargetCallback<String>() { @Override public void call(String item) { // do something with item }});
Syntax:
public static void loadRequest(final String name, final String defaultContent, final Map<String, Object> profileParameters, final Map<String, Object> orderParameters, final Map<String, Object> mboxParameters, final TargetCallback<String> callback)
Example:
Map<String, Object> profileParameters = new HashMap<String, Object>();profileParameters.put(“profile-parameter-key”, “profile-parameter-value”);
Map<String, Object> orderParameters = new HashMap<String, Object>();orderParameters.put(“order-parameter-key”, “order-parameter-value”);
Map<String, Object> mboxParameters = new HashMap<String, Object>();mboxParameters.put(“mbox-parameter-key”, “mbox-parameter-value”);Target.loadRequest(“mboxName”, “defaultContent”, profileParameters, orderParameters, mboxParameters, new TargetCallback<String>() { @Override public void call (String item) { Log.d(“Target Content”, item); }});
Sends request to your configured Target server and returns the string value of the offer that isgenerated in a block callback.
loadRequest
Syntax:
public static void loadRequest(final String name, final String defaultContent, final Map<String, Object> profileParameters, final
84Target
DescriptionMethod
Map<String, Object> orderParameters, final Map<String, Object> mboxParameters, final TargetCallback<String> callback)
Example:
Map<String, Object> profileParameters = new HashMap<String, Object>();profileParameters.put(“profile-parameter-key”, “profile-parameter-value”);
Map<String, Object> orderParameters = new HashMap<String, Object>();orderParameters.put(“order-parameter-key”, “order-parameter-value”);
Map<String, Object> mboxParameters = new HashMap<String, Object>();mboxParameters.put(“mbox-parameter-key”, “mbox-parameter-value”);Target.loadRequest(“mboxName”, “defaultContent”, profileParameters, orderParameters, mboxParameters, new TargetCallback<String>() { @Override public void call (String item) { Log.d(“Target Content”, item); }});
Sends a request to your configured Target server and returns the string value of the offer that isgenerated in a TargetCallback.
loadRequest
Syntax:
public static void loadRequest(final String name, final String defaultContent, final Map<String, Object> profileParameters, final Map<String, Object> orderParameters, final Map<String, Object> mboxParameters, final Map<String, Object> requestLocationParameters, final TargetCallback<String> callback);
Returns: N/A
Parameters:
Description:Name:
Type: Stringname
Name of the Target mbox/location that you want to retrieve.
Type: StringdefaultContent
Value returned in the callback if the Target server is unreachable, orthe user does not qualify for the campaign.
Type: Map<String, Object>profileParameters
Values in this dictionary will go in the "profileParameters" objectin the request to Target.
Type: Map<String, Object>orderParameters
Values in this dictionary will go in the "order" object in the request toTarget.
85Target
DescriptionMethod
Description:Name:
Type: Map<String, Object>mboxParameters
Values in this dictionary will go in the "mboxParameters" object inthe request to Target.
Type: Map<String, Object>requestLocationParameters
Values in this dictionary will go in the "requestLocation" object inthe request to Target.
Type: TargetCallback<String>callback
This method will be called with the content of the offer from the Targetserver. If the Target server is unreachable or the user does not qualifyfor the campaign, defaultContent will be returned.
Example:Map<String, Object> profileParameters = new HashMap<String, Object>();profileParameters.put(“profile-parameter-key”, “profile-parameter-value”);
Map<String, Object> orderParameters = new HashMap<String, Object>();orderParameters.put(“order-parameter-key”, “order-parameter-value”);
Map<String, Object> mboxParameters = new HashMap<String, Object>();mboxParameters.put(“mbox-parameter-key”, “mbox-parameter-value”);
Map<String, Object> requestLocationParameters = new HashMap<String, Object>();requestLocationParameters.put(“request-location-parameter-key”, “request-location-parameter-value”);
Target.loadRequest(“mboxName”, “defaultContent”, profileParameters, orderParameters, mboxParameters, requestLocationParameters,new TargetCallback<String>() { @Override public void call (String item) { Log.d(“Target Content”, item); }});
For more information about the underlying Target API, see Delivery in the Target Developer's help.
Creates a TargetLocationRequest object with the given parameters.createOrderConfirmRequest Syntax:
public static TargetLocationRequest createOrderConfirmRequest(String name, String orderId, String orderTotal, String productPurchasedId, Map<String, Object> parameters);
Example:TargetLocationRequest orderConfirm = Target.createOrderConfirmRequest("orderConfirm", "order", "47.88", "3722", null);
86Target
DescriptionMethod
Creates a TargetLocationRequest object with the given parameters.createRequest
Syntax:public static TargetLocationRequest createRequest(String name, String defaultContent, Map<String, Object> parameters);
Example:TargetLocationRequest heroBannerRequest = Target.createRequest("heroBanner", "default.png", null);
Clears any target cookies from your app.clearCookies
Syntax:public static void clearCookies();
Example:Target.clearCookies();
Returns the pcID.getPcID
Syntax:public static String getPcID();
Example:Target.getPcID();
Returns the session ID.getSessionID
Syntax:public static String getSessionID();
Example:Target.getSessionID();
Sets the third-party ID.setThirdPartyID
Syntax:public static String setThirdPartyID(final String thirdPartyId);
Example:Target.setThirdPartyID(“third-party-id”);
Returns the third-party ID.getThirdPartyID
Syntax:public static String getThirdPartyID();
Example:String thirdPartyId = Target.getThirdPartyID();
87Target
Prefetch offer content in Android
The Adobe Target prefetch feature uses the Android Mobile SDKs to fetch offer content as few times as possible by caching theserver responses.
This process reduces the load time, prevents multiple network calls, and allows Adobe Target to be notified which mbox wasvisited by the mobile app user. All content will be retrieved and cached during the prefetch call, and this content will be retrievedfrom the cache for all future calls that contain cached content for the specified mbox name.
Prefetch content does not persist across launches. The prefetch content is cached as long as the application lives or until theclearPrefetchCache() method is called.
Important: Target prefetch APIs have been available since SDK version 4.14.0. For more information about parameterlimitations, see http://developers.adobetarget.com/api/#batch-input-parameters.
Pre-fetch Methods
Here are the methods that you can use for prefetch in Android:
DescriptionParameter
Sends a prefetch request with an array of locations to the configured Target server and returnsthe request status in the provided callback.
prefetchContent
Syntax
public static void prefetchContent(final List<TargetPrefetchObject> targetPrefetchArray,final Map<String, Object> profileParameters,final TargetCallback<Boolean> callback)
Parameters
DescriptionName
Array of TargetPrefetchObjects thatcontains the name and mboxParameters foreach Target location to prefetch.
targetPrefetchArray
Contains the keys and values of profileparameters to be used with every locationprefetch in this request.
profileParameters
Invoked when the prefetch is complete.callback
Returns true if the prefetch was successfuland false if the prefetch was unsuccesful.
Executes a batch request for multiple mbox locations that are specified in the requests array. Each object in the array contains a callback function, which will be invoked when content isavailable for its given mbox location.
loadRequests
88Target
DescriptionParameter
Important: If the content for the requested locations is already cached, it will be returnedimmediately in the provided callback. Otherwise, the SDK will send a network request tothe Target servers to retrieve the content.
Syntax:
public static void loadRequests(final List<TargetRequestObject> requestArray, final Map<String, Object> profileParameters)
Parameters:
DescriptionName
Array of TargetRequestObjects thatcontains the name, default content,
requestArray
parameters, and callback function per locationto retrieve.
Contains keys and values of profile parametersto be used with every location prefetch in thisrequest.
profileParameters
Clears the data that was cached by Target Prefetch.clearPrefetchCache
Syntax:
public static void clearPrefetchCache();
Parameters: N/A
Creates and returns an instance of TargetRequestObject with the provided data.createTargetRequestObject
Syntax:
public static TargetPrefetchObject createTargetRequestObject(final String mboxName,final String defaultContent,final Map<String, Object> mboxParams,final Map<String, Object> orderParams,final Map<String, Object> productParams,final Target.TargetCallback<String> callback)
Creates and returns an instance of TargetPrefetchObject with the provided data.createTargetPrefetchObject
Syntax:public static TargetPrefetchObject createTargetPrefetchObject(final String mboxName,final Map<String, Object> mboxParams)final Map<String, Object> orderParams, final Map<String, Object> productParams)
89Target
Public Classes
Here are the public classes that support pre-fetch in Android:
Class Reference: TargetPrefetchObject
Encapsulates the mbox name and the parameters that are used for mbox prefetch.
DescriptionProperty
Type: Stringname
Name of the location that will be prefetched.
Type: Map<String, Object>mboxParameters
Collection of key-value pairs that will be attached as mboxParameters for thisTargetPrefetchObject's request.
Type: Map<String, Object>orderParameters
Collection of key-value pairs that will be attached to current mbox under the order node.
Type: Map<String, Object>productParameters
Collection of key-value pairs that will be attached to current mbox under the product node.
Class Reference: TargetRequestObject
This class encapsulates the mbox name, default content, mbox parameters and the return callback used for Target locationrequests.
DescriptionProperty
Type: StringmboxName
Name of the requested location.
Type: Map<String, Object>mboxParameters
Collection of key-value pairs that will be attached as mboxParameters for thisTargetRequestObject.
Type: Map<String, Object>orderParameters
Collection of key-value pairs that will be attached to current mbox under the order node.
Type: Map<String, Object>productParameters
Collection of key-value pairs that will be attached to current mbox under the product node.
Type: StringdefaultContent
String value that is returned in the callback if the SDK is unable to retrieve content fromTarget servers.
90Target
DescriptionProperty
Type: Target.TargetCallback<String>callback
Function pointer that will be called when content for the given TargetRequestObject isavailable.
Code Sample
Here is an example of how to prefetch content by using the Android SDKs:
// When your app launches, prefetch the content for a list of locations.// Define the list of mboxes that you want to prefetch.List<TargetPrefetchObject> prefetchMboxesList = new ArrayList<>();
Map<String, Object> mboxParameters1 = new HashMap<>();mboxParameters1.put("status", "platinum");prefetchMboxesList.add(Target.createTargetPrefetchObject("mboxName1", mboxParameters1));
Map<String, Object> mboxParameters2 = new HashMap<>();mboxParameters2.put("userType", "paid");
List<String> purchasedIds = new ArrayList<String>();purchasedIds.add("34");purchasedIds.add("125"); Map<String, Object> orderParameters2 = new HashMap<>();orderParameters2.put("id", "ADCKKIM");orderParameters2.put("total", "344.30");orderParameters2.put("purchasedProductIds", purchasedIds);
Map<String, Object> productParameters2 = new HashMap<>();productParameters2.put("id", "24D3412");productParameters2.put("categoryId","Books");
prefetchMboxesList.add(Target.createTargetPrefetchObject("mboxName2", mboxParameters2, orderParameters2, productParameters2));
// Define the profile parameters map.Map<String, Object> profileParameters = new HashMap<>();profileParameters.put("ageGroup", "20-32");
// Define the target callback for the prefetch call status.Target.TargetCallback<Boolean> prefetchStatusCallback = new Target.TargetCallback<Boolean>() { @Override public void call(final Boolean status) { // check the returned status for the prefetch call }};
// Call the prefetchContent API.Target.prefetchContent(prefetchMboxesList, profileParameters, prefetchStatusCallback);
// When the content is required, you can initiate the locations request.// Define the list of target request objects.List<TargetRequestObject> locationRequests = new ArrayList<>();
Target.TargetCallback<String> callback1 = new Target.TargetCallback<String>() { @Override public void call(final String content) { // check the returned content for mboxName1. }};
91Target
locationRequests.add(Target.createTargetRequestObject("mboxName1", "defaultContent1", mboxParameters1, callback1));
Target.TargetCallback<String> callback2 = new Target.TargetCallback<String>() { @Override public void call(final String content) { // check the returned content for mboxName2. }};
locationRequests.add(Target.createTargetRequestObject("mboxName2", "defaultContent2", mboxParameters2, orderParameters2, productParameters2, callback2));
// Call the loadRequests API.Target.loadRequests(locationRequests, profileParameters);
Additional Information
Here is some additional information about these samples:
• ProductParameters only allows the following keys:
• id• categoryId
• OrderParameters only allows the following keys:
• id• total• purchasedProductIds
• purchasedProducts accepts an ArrayList of strings.
92Target
Marketing CloudThis information helps you use the Android SDK with the Adobe Marketing Cloud.
Marketing Cloud Visitor ID Configuration
The Marketing Cloud visitor ID service provides a universal visitor ID across Marketing Cloud solutions. The visitor ID serviceis required by Analytics for Target, video heartbeat, and future Marketing Cloud integrations.
Tip: You do not need to populate the Marketing Cloud Visitor ID unless you are using the Marketing Cloud ID service. Formore information, see Marketing Cloud Visitor ID Service.
Important: This functionality requires SDK version 4.3 or later.
To enable the Marketing Cloud Visitor ID:
1. Add the library to your project and implement lifecycle.2. Import the library:
import com.adobe.mobile.*;
3. Verify that ADBMobileConfig.json contains the marketingCloudorg:"marketingCloud" : { "org": "YOUR-MCORG-ID"}
Marketing Cloud organization IDs uniquely identify each client company in the Adobe Marketing Cloud and are similar tothe following value:016D5C175213CCA80A490D05@AdobeOrg
Important: You must include @AdobeOrg.
If these IDs are not configured, download an updated ADBMobileConfig.json from Adobe Mobile services. For moreinformation, see Before You Start.
After the configuration is complete, a Marketing Cloud visitor ID is generated and is included on all hits. Other visitor IDs, suchas custom and automatically-generated iDs, continue to be sent with each hit.
Marketing Cloud Visitor ID Service Methods
Here are the Marketing Cloud Visitor ID Service methods that are provided by the Android library.
The SDK currently supports multiple Adobe Marketing Cloud Solutions, including Analytics, Target, Audience Manager, andthe Marketing Cloud Visitor ID Service.
Methods are prefixed according to the solution. For example, Marketing Cloud visitor ID methods are prefixed with visitor.For more information, see Marketing Cloud Visitor ID Configuration.
93Marketing Cloud
DescriptionMethod
Appends Adobe visitor data to a URL string for use with the Adobe JavaScript library. You musthave Mobile SDK 4.12+ to use this method. For more information, see Append Visitor ID HelperFunction.
public static StringappendToURL(finalString URL)
Important: This method can cause a blocking network call. Do not call this on time-sensitivethreads.
• Input: URL<java.lang.String>
A required URL string to which the visitor information is appended.
• Output: URL<java.lang.String>
String with the visitor information appended.
Example:String urlSample = "http://example.com"; String urlWithAdobeVisitorInfo = Visitor.appendToURL(urlSample);
Intent i = new Intent(Intent.ACTION_VIEW); i.setData(Uri.parse(urlWithAdobeVisitorInfo)); startActivity(i);
Retrieves the Marketing Cloud visitor ID from the visitor ID service.getMarketingCloudId
• Syntax:public static String getMarketingCloudId();
• Example:String mcid = Visitor.getMarketingCloudId();
Important: This method can cause a blocking network call and should not be called from aUI thread.
With the Marketing Cloud visitor ID, you can set additional customer IDs that can be associatedwith each visitor. The Visitor API accepts multiple customer IDs for the same visitor, with a customer
syncIdentifiers
type identifier to separate the scope of the different customer IDs. This method corresponds tosetCustomerIDs in the JavaScript library.
• Syntax:public static void syncIdentifiers(Map<String, String> identifiers);
• Example:Map<String, String> identifiers = new HashMap<String, String>();identifiers.put("idType", "idValue");Visitor.syncIdentifiers(identifiers);
Synchronizes the provided identifier type and value to the Visitor ID service. Pass in theauthenticationState as one of the following values:
syncIdentifer
94Marketing Cloud
DescriptionMethod
• VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_UNKNOWN• VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_AUTHENTICATED• VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_LOGGED_OUT
• Syntax:public static void syncIdentifier(final String identifierType, final String identifier, final VisitorID.VisitorIDAuthenticationState authenticationState);
• Example:Visitor.syncIdentifier("myIdType", "valueForUser", VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_LOGGED_OUT);
Synchronizes the provided identifiers to the Visitor ID service. Pass in the authenticationStateas one of the following values:
syncIdentifiers
• VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_UNKNOWN• VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_AUTHENTICATED• VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_LOGGED_OUT
• Syntax:public static void syncIdentifiers(final Map<String, String> identifiers, final VisitorID.VisitorIDAuthenticationState authenticationState);
• Example:Map<String, String> identifiers = new HashMap<String, String>(); identifiers.put("myIdType", "valueForUser"); Visitor.syncIdentifiers(identifiers, VisitorID.VisitorIDAuthenticationState.VISITOR_ID_AUTHENTICATION_STATE_AUTHENTICATED);
Retrieves a list of read-only ADBVisitorID objects.getIdentifiers
• Syntax:public static List<VisitorID> getIdentifiers();
• Example:List<VisitorID> myVisitorIDs = Visitor.getIdentifiers();
Public Methodspublic class VisitorID { public final String idOrigin; public final String idType; public final String id; public VisitorIDAuthenticationState authenticationState;
public enum VisitorIDAuthenticationState { VISITOR_ID_AUTHENTICATION_STATE_UNKNOWN(0), VISITOR_ID_AUTHENTICATION_STATE_AUTHENTICATED(1), VISITOR_ID_AUTHENTICATION_STATE_LOGGED_OUT(2); }}
95Marketing Cloud
Marketing Cloud Device Co-op
To start using the Marketing Cloud Device Co-op, contact your Adobe representative.
To enable your mobile apps for the Marketing Cloud Device Co-op, complete the following steps for the Marketing CloudAndroid SDKs:
Important: This functionality requires Android SDK version 4.8.3 or later.
1. Implement the Adobe Mobile SDK.For more information, see Core Implementation and Lifecycle.
2. Enable your Marketing Cloud ID.For more information, see Marketing Cloud Visitor ID Configuration.
3. Pass authenticated identities such as CRM IDs or hashed emails, by using one of the sync methods.For more information, see Marketing Cloud Visitor ID Service Methods.
96Marketing Cloud
Audience ManagerThis information helps you send signals and retrieve visitor segments from Audience Manager.
Audience Manager Configuration
You can send signals and retrieve visitor segments from audience management.
Set the Application Context
(Required) The setContext() method must be called once in the onCreate() method of your main activity.
Example:@Overridepublic void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); Config.setContext(this.getApplicationContext());}
If you already added this method call when you implemented Analytics or Target, you do not need to add it again.
Audience Manager Methods
Here is a list of the Audience Manager methods that are provided by the Android library.
The SDK currently supports multiple Adobe Marketing Cloud Solutions, including Analytics, Target, Audience Manager, andthe Marketing Cloud Visitor ID Service. Methods are prefixed according to the solution. For example, Marketing Cloud visitorID methods are prefixed with audience manager.
If Audience Manager is configured in your JSON file, a signal that contains lifecycle metrics is sent with your lifecycle hit.
Returns the visitor profile that was most recently obtained and, if no signal has been submitted,returns null. The visitor profile is saved in SharedPreferences for easy access across multiplelaunches of your app.
getVisitorProfile
• Syntaxpublic static HashMap<String, Object> getVisitorProfile();
• ExampleHashMap<String, Object> visitorProfile = AudienceManager.getVisitorProfile();
Returns the current DPID.getDpid
• Syntaxpublic static void getDpid();
• ExampleString dpid = AudienceManager.getDpid();
Returns the current DPUUID.getDpuuid
97Audience Manager
• Syntaxpublic static void getDpuuid();
• ExampleString dpuuid = AudienceManager.getDpuuid();
Sets the DPID and DPUUID, and these values are sent with each signal.setDpidAndDpuuid
• Syntaxpublic static void setDpidAndDpuuid(String dpid, String dpuuid);
• ExampleAudienceManager.setDpidAndDpuuid("myDpid", "myDpuuid");
Sends audience management a signal with traits and gets the matching segments returned in a blockcallback.
signalWithData
• Syntax:public static void signalWithData(Map<String, Object> data, AudienceManagerCallback<Map<String, Object>> callback);
• Example:HashMap aamTraits = new HashMap<String, Object>();aamTraits.put("trait", "b");AudienceManager.signalWithData(aamTraits, new AudienceManager.AudienceManagerCallback<Map<String, Object>>() { @Override public void call(Map<String, Object> item) { // segments come back here, normally found in the segs object of your json }});
98Audience Manager
WearablesStarting in Android SDK version 4.5, a new Android extension was added that allows you to collect data from your AndroidWearable app.
Android Wearables: Getting Started
Starting in Android SDK version 4.5, a new Android extension was added that allows you to collect data from your AndroidWearable app.
This section contains the following information:
• Configuring the SDK for a Handheld App (Android Studio)• Configuring the SDK for a Wearable App (Android Studio)
Configuring the SDK for a Handheld App (Android Studio)
For more information about importing the SDK into your project, see Core Implementation and Lifecycle.
1. Add the ADBMobileConfig.json file to the assets folder of your project.2. Add the adobeMobileLibrary-*.jar file to the libs folder or make sure this file is referenced by the project.
Tip: You might need to sync the gradle project after adding the .jar file.
3. In the onCreate method, allow the SDK access to your application context by using Config.setContext:@Overridepublic void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main);
// Allow the SDK access to the application context Config.setContext(this.getApplicationContext());}
4. Add the following code to AndroidManifest.xml: <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" />
<application>.......<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" /></application>
5. Make sure your project includes the Google play-services library.6. Implement WearableListenerService or add the corresponding code to your WearableListenerService:
public class WearListenerService extends WearableListenerService {
@Override public void onMessageReceived(MessageEvent messageEvent) { super.onMessageReceived(messageEvent); }
private GoogleApiClient mGoogleApiClient;
@Override public void onCreate() { super.onCreate(); mGoogleApiClient = new GoogleApiClient.Builder(this)
99Wearables
.addApi(Wearable.API) .build(); mGoogleApiClient.connect(); } @Override public void onDestroy() { super.onDestroy(); mGoogleApiClient.disconnect(); }
@Override public void onDataChanged(com.google.android.gms.wearable.DataEventBuffer dataEvents) {
DataListenerHandheld.onDataChanged(dataEvents, mGoogleApiClient, this); }}
7. Add WearListenerService to AndroidManifest.xml:If you are using Google Play Services < 8.2<application> ...... <service android:name=".WearListenerService" > <intent-filter> <action android:name="com.google.android.gms.wearable.BIND_LISTENER" /> </intent-filter> </service></application>If you are using Google Play Services >= 8.2<application> ...... <service android:name=".WearListenerService" > <intent-filter> <action android:name="com.google.android.gms.wearable.DATA_CHANGED" /> <data android:scheme="wear" android:host="*" android:pathPrefix="/abdmobile" /> </intent-filter> </service></application>Please find more information from google's blog https://android-developers.googleblog.com/2016/04/deprecation-of-bindlistener.html.Permalink Edit
Configuring the SDK for a Wearable App (Android Studio)
1. Complete one of the following tasks:
• Add the same ADBMobileConfig.json file to the assets folder of your wearable project.
• Change the gradle config to use the ADBMobileConfig.json in the assets folder of the handheld app:
android {
sourceSets { main { assets.srcDirs = ['src/main/assets','../mobile/src/main/assets'] } }}
2. Add the adobeMobileLibrary-*.jar file to the libs folder or make sure it get referenced by the project.
You might need to sync the gradle project after adding the jar file.
100Wearables
3. In the onCreate method, allow the SDK access to your application context using Config.setContext:@Overridepublic void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); // Allow the SDK access to the application context Config.setContext(this.getApplicationContext(), Config.ApplicationType.APPLICATION_TYPE_WEARABLE);}
4. Add the following code to AndroidManifest.xml:<application>.......<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" /></application>
5. Ensure that your project includes the Google play-services library.6. Implement WearableListenerService or add the corresponding code to your WearableListenerService:
public class WearListenerService extends WearableListenerService {
@Override public void onDataChanged(com.google.android.gms.wearable.DataEventBuffer dataEvents) {
DataListenerWearable.onDataChanged(dataEvents); }
}
7. Add WearListenerService to AndroidManifest.xml:If you are using Google Play Services < 8.2<application> ...... <service android:name=".WearListenerService" > <intent-filter> <action android:name="com.google.android.gms.wearable.BIND_LISTENER" /> </intent-filter> </service></application>If you are using Google Play Services >= 8.2<application> ...... <service android:name=".WearListenerService" > <intent-filter> <action android:name="com.google.android.gms.wearable.DATA_CHANGED" /> <data android:scheme="wear" android:host="*" android:pathPrefix="/abdmobile" /> </intent-filter> </service></application>Please find more information from google's blog https://android-developers.googleblog.com/2016/04/deprecation-of-bindlistener.html.Permalink Edit
Android Wearables: Additional Notes
Here is some information to help you configure the Android extension, which allows you to collect data from your AndroidWearable app.
• The Adobe Mobile Android Wearables extension requires Android version 4.4 (KitKat) or above.
101Wearables
• There is one additional context value, A.RunMode, which has been added to indicate whether the data comes from thecontaining app or the extension.
• RunMode = Application (the hit comes from handheld app)• RunMode = Extension (the hit comes from wearable app)
• The SDK automatically syncs the aid/vid/visitor service id/privacy status from the handheld app to thewearable app, so do not call setPrivacyStatus/setUserIdentifier/idSync from the wearable app.
• In-app messages, Target, and Audience Manager are disabled for the wearable app.
102Wearables
Android SDK ReferenceThis reference material helps you use the Android SDK for Marketing Cloud Solutions.
App IDs
The following table describes the different app identifiers that are used by the Android SDK and Adobe Mobile services.
DescriptionID
This is a combination of the app name and the bundle version that is submitted to the app store.ID sent with lifecyclemetrics
This value is used for the Versions report in Adobe Mobile services, and you can filter using this valueto segment by a specific release version of your app.
This ID is assigned to your app by the app store, and is provided in Adobe Mobile services when youcreate acquisition links.
App Store ID
This is a unique ID that is assigned to the app instance by Adobe Mobile services for all the associatedmetadata in the system.
AppID in ADBMobileJSON Config
This ID is used to create the unique URLs for acquisition tracking or tracking link. This ID isautomatically added to the ADBMobile JSON config file when this file is downloaded from the UI andcan be found on Manage App Settings under the Acquisition settings for your app.
Visitor Tracking Between an App and Mobile Web
If your app opens mobile web content, ensure that visitors are not identified separately as they move between the native andmobile web.
Visitor IDs in Apps
The Android SDK generates a unique visitor ID when an app is installed. This ID is stored in persistent memory on the mobiledevice, is sent with every hit, and is removed only when the user uninstalls the app.
Tip: App visitor IDs persist through upgrades.
Visitor IDs in the Mobile Web
Typical mobile web implementations use the same standard Analytics s_code.js or AppMeasurement.js that is used indesktop sites. The JavaScript libraries have their own methods of generating unique visitor IDs, which causes a different visitorID to be generated when you open mobile web content from your app.
Implementing Visitor Tracking Between an App and the Mobile Web
To use the same visitor ID in the app and mobile web:
1. Add the library to your project and implement lifecycle.
103Android SDK Reference
2. To append visitor information to the URL that is being used to open the web view, call visitorAppendToURL:String urlString = "http://www.mydomain.com/index.php";String urlStringWithVisitorData = Visitor.appendToURL(urlString);Intent browserIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(urlStringWithVisitorData));startActivity(browserIntent);}
The ID service code on the destination domain extracts the MID from the URL instead of sending a request to Adobe for a newID. The code uses the passed in MID to track the visitor.
On hits from the mobile web content, verify that the mid parameter exists on each hit, and that this value matches the midparameter that is sent by the app code.
Troubleshooting Visitor Tracking
AnswerIssue
Verify that the Adobe SDK that is bundled in the parentapplication is version 4.12.0 or higher.
I do not see Visitor.appendToURL.
Verify the following:I do not see Adobe IDs in my URL.
• The URL string that is used to open the web view wasgenerated by Visitor.appendToURL(urlString).
• The Adobe IDs are encoded.
To ensure that the IDs that are appended to the URL that isbeing opened, verify that the adobe_mc query parameterappears in the URL.
Verify the following:My mid is not identical in my app to my web view.
• The URL string that is being used to open the web view wasgenerated by Visitor.appendToURL(urlString).
• The URL string contains Adobe parameters.
The string should contain adobe_mc="SAMPLE_ID_DATA"where "SAMPLE_ID_DATA" contains the IDs that aregenerated in the Adobe Mobile SDK.
• The VisitorAPI.js is version 1.7.0 or higher.
If these troubleshooting steps do not resolve your issues, contact Adobe Experience Care.
Important: To allow Adobe can validate the implementation, you need to share a sample application and the associatedsite.
Android Widgets
Android widgets can be tracked by using the same methods as your app. Widgets share the application context with your app,so hit order and visitor identification is preserved.
104Android SDK Reference
The following guidelines will help you track Android widgets:
• Do not implement lifecycle metrics (startActivity/stopActivity) calls in the widget.• To track when a widget is added to the home screen, add a trackState or trackEvent call to the onEnabled method of
the widget.• To track when the app is launched from a widget, add a trackState or trackEvent call before you create the intent to
launch your application.• To track the context of an action, you can define a ContextData variable that provides the option to segment each action
separately (for example, AppExperienceType="widget" vs. app).
105Android SDK Reference
Opt-Out and Privacy SettingsThis information helps you configure opt-out and privacy settings in your Android app.
Important: Starting with Android SDK 4.8.3, privacy settings are set by using the setPrivacyStatus method, whichaffects activity from Analytics, Target, and Audience Manager.
You can control whether the Analytics, Target, and Audience Manager activity is allowed on a device by using the followingsettings:
• privacyDefault in ADBMobile JSON Config.
This setting controls the initial setting that persists until it is changed in the code.
• The Config.setPrivacyStatus method.
After the privacy setting is changed by using this method, this change remains effective until you change it again or when youuninstall and install the app again. For more information about the methods, see Configuration Methods.
The following table describes each privacy status:
Value in setPrivacyStatusValue in JSONConfig
DescriptionSetting
MOBILE_PRIVACY_STATUS_OPT_INoptedinOpt in• Analytics: Hits are sent.
• Target: Mbox requests are sent.
• Audience Manager: Signals and ID syncs aresent.
MOBILE_PRIVACY_STATUS_OPT_OUToptedoutOpt out• Analytics: Hits are discarded.
• Target: Mbox requests are not allowed.
• Audience Manager: Signals and ID syncs arenot allowed.
MOBILE_PRIVACY_STATUS_UNKNOWNoptunknownUnknown• Analytics: If offline tracking is enabled, hits
are saved until the privacy status changes toopt-in (hits are sent) or opt-out (hits arediscarded).
If offline tracking is not enabled, hits arediscarded until the privacy status changes toopt-in.
• Target: Mbox requests are sent.
• Audience Manager: Signals and ID syncs aresent.
106Opt-Out and Privacy Settings
Examplespublic void setOptIn(View view) { Config.setPrivacyStatus(MobilePrivacyStatus.MOBILE_PRIVACY_STATUS_OPT_IN); currentStatus = Config.getPrivacyStatus();}public void setOptOut(View view) { Config.setPrivacyStatus(MobilePrivacyStatus.MOBILE_PRIVACY_STATUS_OPT_OUT); currentStatus = Config.getPrivacyStatus();}public void setOptUnknown(View view) { Config.setPrivacyStatus(MobilePrivacyStatus.MOBILE_PRIVACY_STATUS_UNKNOWN); currentStatus = Config.getPrivacyStatus();}
107Opt-Out and Privacy Settings
Using Bloodhound to Test Mobile ApplicationsDuring application development, Bloodhound lets you view server calls locally and optionally forward the data to Adobecollection servers.
For more information about Bloodhound, see the following guides:
• Bloodhound 3.x for Mac
• Bloodhound 2.2 for Windows
Important: As of April 30, 2017, Adobe Bloodhound has been sunset. Starting on May 1, 2017, no additional enhancementsand no additional Engineering or Adobe Expert Care support will be provided.
108Using Bloodhound to Test Mobile Applications
PhoneGap Plug-inThis plug-in allows you to send Android AppMeasurement calls from your PhoneGap project.
To create a PhoneGap project, see PhoneGap Getting Started with Android.
This section contains the following information:
• Install the plug-in using npm• Manually install the plug-in• Implement Custom Tracking
Install the plug-in using npm
Run the following command:cordova plugin add adobe-mobile-services
Manually install the plug-in
Include the Plug-in
1. Drag ADBMobile_PhoneGap.java to your src folder.
To move this file, click OK.
2. Drag ADB_Helper.js into the folder that contains index.html (assets > www).
To move this file, click OK.
3. In the res/xml folder, open config.xml and register an new plugin by adding the following:
<feature name="ADBMobile_PhoneGap"> <param name="android-package" value="[YOUR_PACKAGE_NAME].ADBMobile_PhoneGap" /></feature>
For example, if your package is named com.example.phonegaptest, your android-package value would be thefollowing:<param name="android-package" value="com.example.phonegaptest.ADBMobile_PhoneGap" />
Include the AppMeasurement Library
1. To download the AppMeasurement library, see Download the SDK.
2. Drag adobeMobileLibrary.jar to your src folder.
To move this file, click OK.
3. Right-click adobeMobileLibrary.jar and select Add as Library.
4. Based on the requirements of your project, enter the name, level, and location for the library.
5. Drag ADBMobileConfig.json to your assets folder in the application root.
6. Confirm that you have selected the root application and not an application in an application.
To move this file, click OK.
Add App Permissions
The AppMeasurement library requires the following permissions to send data and record offline tracking calls:
• INTERNET
109PhoneGap Plug-in
• ACCESS_NETWORK_STATE
To add these permissions, add the following lines to your AndroidManifest.xml file, which is in the application projectdirectory:<uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
To enable in-app messaging:
Update AndroidManifest.xml to declare the full screen activity and enable the Message Notification Handler:<activity android:name="com.adobe.mobile.MessageFullScreenActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" /><receiver android:name="com.adobe.mobile.MessageNotificationHandler" />
If you select modal layout when you create a message in Adobe mobile services, select one of the following themes:
• Theme.Translucent.NoTitleBar.Fullscreen• Theme.Translucent.NoTitleBar• Theme.Translucent
For example:<activityandroid:name="com.adobe.mobile.MessageFullScreenActivity"android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"android:windowSoftInputMode="adjustUnspecified|stateHidden" /><receiver android:name="com.adobe.mobile.MessageNotificationHandler" />
Implement Custom Tracking
In html files, add the following to the <head> tag where you want to use tracking:<script type="text/javascript" charset="utf-8" src="ADB_Helper.js"></script>
PhoneGap Plug-in Methods
You can use iOS PhoneGap Plug-in methods to complete a variety of tasks.
Here is a link of the iOS PhoneGap Plug-in methods:
• Configuration• Tracking• Target• Acquisition• Audience Manager• Visitor ID Service• App Extensions• Apple Watch Methods
In html files where you want to use tracking, add the following to the <head> tag:<script type="text/javascript" charset="utf-8" src="ADB_Helper.js"></script>
This section contains the following information:
• Configuration Methods• PII Methods
110PhoneGap Plug-in
• Tracking Methods• Beacon Methods• Target Methods• Acquisition Methods• Advertising Identifier• Audience Manager Methods• Visitor ID Service Methods
Configuration Methods
DescriptionMethod
Returns the privacy status for current user.getPrivacyStatus
Here are the available statuses:
• ADB.optedIn
The hits are sent immediately.
• ADB.optedOut, where hits are discarded.
The hits are discarded.
• ADB.optUnknown
If your report suite is timestamp-enabled, hits are saved until the privacy status changesto opt-in (hits are sent) or opt-out (hits are discarded). If your report suite is nottimestamp-enabled, hits are discarded until the privacy status changes to opt in.
The default value is set in ADBMobileConfig.json.
Example:getPrivacyStatus(function (value) { myTempVal = value; }, function () { myTempVal = null; });
Sets the privacy status for the current user to status.setPrivacyStatus
You can set one of the following statuses:
• ADB.optedIn
The hits are sent immediately.
• ADB.optedOut.
The hits are discarded.
• ADB.optUnknown
If your report suite is timestamp-enabled, hits are saved until the privacy status changesto opt-in (hits are sent) or opt-out (hits are discarded). If your report suite is nottimestamp-enabled, hits are discarded until the privacy status changes to opt in.
111PhoneGap Plug-in
DescriptionMethod
Example:ADB.setPrivacyStatus('ADB.optedIn');
Returns the lifetime value of the current user.getLifetimeValue
The default value is 0.
Example:ADB.getLifetimeValue(function (value) { myTempVal = value; }, function () { myTempVal = null; });
Enables (true) or disables (false) viewing debug information. By default, this variableis false.
setDebugLogging
Example:ADB.setDebugLogging(true);
Gets the library version.getVersion
Example:ADB.getVersion(function (value) { versionNum = value; }, function () { versionNum = 1.0; });
Returns the automatically generated visitor identifier.trackingIdentifier
This is an app-specific, unique visitor ID that is generated when the app is initiallylaunched and is stored and used from that point. This ID is preserved between appupgrades and is removed when the app is uninstalled.
Tip: If your app upgrades from the Marketing Cloud 3.x to 4.x SDK, the previousvisitor ID (custom or automatically generated) is retrieved and stored as the customuser identifier. For more information, see the getUserIdentifier row below.This ID preserves visitor data between SDK upgrades.
For new installations on the 4.x SDK, the user identifier is null and tracking identifieris used.
Example:ADB.trackingIdentifier(function (value) { myTempVal = value; }, function () { myTempVal = null; });
If a customer user identifier has been set, returns this identifier; if the identifier has notbeen set, returns null.
getUserIdentifier
The default value is null.
Example:getUserIdentifier(function (value) { myTempVal = value; }, function () { myTempVal = null; });
112PhoneGap Plug-in
DescriptionMethod
Sets the user identifier to identifier.setUserIdentifier
Example:ADB.setUserIdentifier('testUser');
Sets the device token for push notifications.getUserIdentifier(function (value) { myTempVal = value; }, function () { myTempVal = null; });
setPushIdentifier
Syntax:ADB.setPushIdentifier(pushIdentifier, success, fail);
Example:ADB.setPushIdentifier('test_push_identifier',function (value) { alert('success'); },function (value) { alert('fail'); });
Sets the preference of lifecycle session keep alive.keepLifecycleSessionAlive
Important: Calling keepLifecycleSessionAlive prevents your app fromlaunching a new session the next time it is resumed from background. You shouldonly use this method if your app registers for notifications in the background.
Example:ADB.keepLifecycleSessionAlive();
Forces the library to send all queued hits regardless of current batch options.trackingSendQueuedHits
Example:ADB.trackingSendQueuedHits();
Gets or sets the number of stored tracking calls in the offline queue.trackingGetQueueSize
Example:ADB.trackingGetQueueSize(function (value) { myTempVal = value; }, function () { myTempVal = null; });
Removes all stored tracking calls from the offline queue.trackingClearQueue
: Be careful when clearing the queue manually, because it cannot be reversed.
Example:ADB.trackingClearQueue(function (value) { myTempVal = value; }, function () { myTempVal = null; });
113PhoneGap Plug-in
PII Methods
DescriptionMethod
Submits a PII collection request.collectPII
Syntax:ADB.collectPII(piiData, success, fail);
Example:ADB.collectPII({'k1':'v1','k2':'v2','k3':'v3'}, function (value) { alert('success'); },function (value) { alert('fail'); });
Tracking Methods
DescriptionMethod
Tracks an Adobe Deep Link click-through.trackAdobeDeepLink
Tip: If the Lifecycle call is a launch event, the Adobe Link data will be appended,otherwise an extra call will be sent.
Syntax:
ADB.trackAdobeDeepLink(deeplinkURL, success, fail);
Example:
ADB.trackAdobeDeepLink('xyz-deeplink-url', function (value) { alert('success'); },function (value) { alert('fail'); });
Tracks an app state with optional context data. States are the views that are available inyour app, such as such as home dashboard, app settings, cart, and so on. Thesestates are similar to pages on a website, and trackState calls increment page views.
trackState
cData: JSON object with key-value pairs to send in context data.
Syntax:
ADB.trackState(string stateName[,JSON cData]);
Example:ADB.trackState("login page");
ADB.trackState("login page", {"user":"john","remember":"true"});
Tracks an action in your app. Actions include logins, banner taps, feedsubscriptions, and other metrics that occur in your app and that you want to measure.
trackAction
Syntax:ADB.trackAction(string action[,JSON cData]);
114PhoneGap Plug-in
DescriptionMethod
Example:ADB.trackAction("login");
ADB.trackAction("login", {"user":"john","remember":"true"});
Sends the current x y coordinates. Also uses points of interest defined in theADBMobileConfig.json file to determine if the location provided as a parameter is
trackLocation
within any of your POI. If the current coordinates are within a defined POI, a contextdata variable is populated and sent with the trackLocation call.
Syntax:ADB.trackLocation(x, y[,JSON cData]);
Example:ADB.trackLocation('40.431596', '-111.893713');
Adds amount to the user's lifetime value.trackLifetimeValueIncrease
Syntax:ADB.trackLifetimeValueIncrease(amount[,JSON cData]);
Example:ADB.trackLifetimeValueIncrease('10.01');
Start a timed action with the name action.trackTimedActionStart
If you call this method for an action that has already started, the previous timed actionis overwritten.
Tip: This call does not send a hit.
Syntax:ADB.trackTimedActionStart(action[,JSON cData]);
Example:ADB.trackTimedActionStart("cartToCheckout");
Pass in cData to update the context data that is associated with the action.trackTimedActionUpdate
The cData that is passed is appended to the existing data for the action and, if the samekey is already defined for action, overwrites the data.
Tip: This call does not send a hit.
Syntax:ADB.trackTimedActionUpdate(String action[,JSON cData]);
Example:ADB.trackTimedActionUpdate("cartToCheckout",{'SampleContextDataKey3':'SampleContextDataVal3','SampleContextDataKey4':'SampleContextDataVal4'});
115PhoneGap Plug-in
DescriptionMethod
End a timed action.trackTimedActionEnd
Example:ADB.trackTimedActionEnd("cartToCheckout");
Returns whether a timed action is in progress.trackingTimedActionExists
Syntax:ADB.trackingTimedActionExists(function (value) { myTempVal = value; }, function () { myTempVal = null; });
Beacon Methods
DescriptionMethod
Tracks when a user enters the proximity of a beacon.trackBeacon
Syntax:ADB.trackBeacon(uuid, major, minor, proximity, cData)
Example:ADB.trackBeacon('2F234454-CF6D-4A0F-ADF2-F4911BA9FFA6', 1, 2, ADB.beaconUnknown, {'hp':'hp_val','hp.company':'adobe'}
Clears the beacon data after a user leaves the proximity of the beacon.clearCurrentBeacon
Syntax:ADB.clearCurrentBeacon(success, fail)
Example:ADB.clearCurrentBeacon();
Target Methods
DescriptionMethod
Sends a request to your configured Target server and returns the string value of the offer.targetLoadRequest
Syntax:ADB.targetLoadRequest(success, fail, name, defaultContent, parameters);
Example:ADB.targetLoadRequest(function (value){ myTempVal = value; }, function () { myTempVal = null; }, 'bannerOffer', 'none', {'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'});
116PhoneGap Plug-in
DescriptionMethod
Sends a request to your configured Target server.targetLoadOrderConfirmRequest
Syntax:ADB.targetLoadOrderConfirmRequest(success, fail, name, orderId, orderTotal, productPurchaseId, parameters);
Example:ADB.targetLoadRequest(function (value) { myTempVal = value; }, function (){ myTempVal = null; }, 'name', 'orderId', 'total', 'purchaseId',{'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'});
Clears the Target cookies from shared cookie storage.targetClearCookies
Example:ADB.targetClearCookies();
Processes a Target service request.targetLoadRequestWithNameWithLocationParameters
Syntax:
ADB.targetLoadRequestWithNameWithLocationParameters(success, fail, name, defaultContent, profileParameters, orderParameters, mboxParameters, requestLocationParameters);
Example:ADB.targetLoadRequestWithNameWithLocationParameters (function () { alert('success'); }, function () { alert('fail'); }, 'bannerOffer', 'none', {'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'}, {'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'},{'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'},{'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'});
Processes a Target service request.targetLoadRequestWithName
Syntax:ADB.targetLoadRequestWithRequestLocationParams(success, fail, name, defaultContent, profileParameters, orderParameters, mboxParameters, requestLocationParameters);
Example:ADB.targetLoadRequestWithRequestLocationParams(function () { alert('success'); }, function () { alert('fail'); }, 'bannerOffer', 'none', {'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'}, {'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'},{'hp':'hp_val_new','hp.company':'adobe', 'hp.val2':'hp_val2'});
Gets the value of the SessionID cookie returned for this visitor by the Targetserver.targetSessionID
117PhoneGap Plug-in
DescriptionMethod
Syntax:ADB.targetSessionID (success, fail);
Example:ADB.targetSessionID(function (value) { alert(value); },function (value) { alert('fail'); });
Gets the value of the PcID cookie that is returned for this visitor by the Target server.targetPcID
Syntax:ADB.targetPcID (success, fail);
Example:ADB.targetPcID(function (value) { alert(value); },function (value) { alert('fail'); });
Sets the custom visitor ID for Target.targetSetThirdPartyID
Syntax:ADB.targetSetThirdPartyID(thirdPartyID, success, fail);
Example:ADB.targetSetThirdPartyID('test-third-party-id', function (value) { alert('success'); },function (value) { alert('fail'); });
Gets the custom visitor ID for Target.targetThirdPartyID
Syntax:ADB.targetThirdPartyID(success, fail);
Example:ADB.targetThirdPartyID(function (value) { alert(value); },function (value) { alert('fail'); });
Acquisition Methods
DescriptionMethod
Sends a request to your configured Target server and returns the string value of the offer.acquisitionCampaignStartForApp
Syntax:ADB.acquisitionCampaignStartForApp(appId, data, success, fail);
Example:ADB.acquisitionCampaignStartForApp(“appId”, {‘key’:‘value’}, function() {…}, function() {…}));
ADB.acquisitionCampaignStartForApp(“appId”, {‘key’:‘value’});
118PhoneGap Plug-in
Advertising Identifier
In the main activity that is generated by Cordova, call Config.submitAdvertisingIdentifierTask() in the onResume()method. For more information, see Configuration Methods.
Audience Manager Methods
DescriptionMethod
Gets the visitor’s profile.audienceGetVisitorProfile
Syntax:ADB.audienceGetVisitorProfile();
Example:ADB.audienceGetVisitorProfile(function(value) { profile = value; }, function() { profile = null; });
Returns the DPUUID.audienceGetDpuuid
Syntax:ADB.audienceGetDpuuid(success, fail);
Example:ADB.audienceGetDpuuid(function(value) { dpuuid = value; }, function() { dpuuid = null; });
Returns the DPID.audienceGetDpid
Syntax:ADB.audienceGetDpid(success, fail);
Example:ADB.audienceGetDpid(function(value) { dpid = value; }, function() { dpid = null; });
Sets the DPID and DPUUID.audienceSetDpidAndDpuuid
Syntax:ADB.audienceSetDpidAndDpuuid(dpid, dpuuid, success, fail);
Example:ADB.audienceSetDpidAndDpuuid(‘dpid’, ‘dpuuid’, function() {…}, function() {…});
ADB.audienceSetDpidAndDpuuid(‘dpid’, ‘dpuuid’);
Processes an Audience Manager service request.audienceSignalWithData
Syntax:ADB.audienceSignalWithData(success, fail, data);
119PhoneGap Plug-in
DescriptionMethod
Example:ADB.audienceSignalWithData(function() {}, function() {}, {‘key1’: ’value1’, ‘key2’: ‘value2’});
ADB.audienceSignalWithData({‘key1’: ’value1’, ‘key2’: ‘value2’});
Resets Audience Manager UUID and purges the current visitor profile.audienceReset
Example:ADB.audienceReset();
Visitor ID Service Methods
DescriptionMethod
Returns the Marketing Cloud ID from the Visitor ID Service.visitorGetMarketingCloudId
Syntax:ADB.visitorGetMarketingCloudId(success, fail);
Example:ADB.visitorGetMarketingCloudId(function (value) { mcid = value; }, function () { mcid = null; });
Synchronizes the provided identifiers with the Visitor ID Service.visitorSyncIdentifiers
Syntax:ADB.visitorSyncIdentifiers(identifiers, success, fail);
Example:ADB.visitorSyncIdentifiers({‘key_id_1’:’value_id_1’}, function() {…}, function() {…}));
ADB.visitorSyncIdentifiers({‘key_id_1’: ‘value_id_1’});
Synchronizes the provided identifiers to the Visitor ID Service.visitorSyncIdentifiersWithAuthenticationState
Syntax:ADB.visitorSyncIdentifiersWithAuthenticationState(identifiers, authenticationState, success, fail);
Example:ADB.visitorSyncIdentifiersWithAuthenticationState({'k1':'v1','k2':'v2','k3':'v3'}, ADB.mobileVisitorAuthenticationStateAuthenticated, function (value) { alert('success'); },function (value) { alert('fail'); });
Synchronizes the provided identifier to the Visitor ID Service.visitorSyncIdentifierWithType
120PhoneGap Plug-in
DescriptionMethod
Syntax:
ADB.visitorSyncIdentifierWithType(identifierType, identifier, authenticationState, success, fail);
Example:ADB.visitorSyncIdentifierWithType('test-identifier-type', 'test-identifier', ADB.mobileVisitorAuthenticationStateAuthenticated, function (value) { alert('success'); },function (value) { alert('fail'); });
Appends visitor identifiers to the given URL.visitorAppendToURL
Syntax:ADB.visitorAppendToURL(urlToAppend, success, fail);
Example:ADB.visitorAppendToURL('test_visitor_url', function (value) { alert(value); },'');
Returns all visitorIDs that have been synced.visitorGetIDs
Syntax:ADB.visitorGetIDs (success, fail);
Example:ADB.visitorGetIDs(function (value) { alert(value); },function (value) { alert('fail'); });
121PhoneGap Plug-in
Contact and Legal InformationInformation to help you contact Adobe and to understand the legal issues concerning your use of this product and documentation.
Help & Technical Support
The Adobe Experience Cloud Customer Care team is here to assist you and provides a number of mechanisms by which theycan be engaged:
• Check the Marketing Cloud help pages for advice, tips, and FAQs• Ask us a quick question on Twitter @AdobeExpCare• Log an incident in our customer portal• Contact the Customer Care team directly• Check availability and status of Marketing Cloud Solutions
Service, Capability & Billing
Dependent on your solution configuration, some options described in this documentation might not be available to you. Aseach account is unique, please refer to your contract for pricing, due dates, terms, and conditions. If you would like to add toor otherwise change your service level, or if you have questions regarding your current service, please contact your AccountManager.
Feedback
We welcome any suggestions or feedback regarding this solution. Enhancement ideas and suggestions can be added to ourCustomer Idea Exchange.
Legal
© 2017 Adobe Systems Incorporated. All Rights Reserved.Published by Adobe Systems Incorporated.
Terms of Use | Privacy Center
Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United Statesand/or other countries. A trademark symbol (®, ™, etc.) denotes an Adobe trademark.
All third-party trademarks are the property of their respective owners. Updated Information/Additional Third Party CodeInformation available at http://www.adobe.com/go/thirdparty.
122Contact and Legal Information
