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

(1)

Adobe

®

Marketing Cloud

(2)

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

Release Notes for Android SDK 4.x for Marketing Cloud Solutions...6

Getting Started...8

Before You Start...8

Core Implementation and Lifecycle...9

Processing Rules and Context Data...11

Configuration...13

ADBMobile JSON Config...13

Override the ADBMobile JSON Config Path...20

Hit Batching...20

Configuration Methods...21

Analytics...26

Track App States...26

Track App Actions...27

Track App Crashes...29

Timed Actions...31

Visitor Lifetime Value...32

Products Variable...33

Products Variable with Merchandising eVars and Product-Specific Events...34

Event Serialization...35

Video Analytics...35

Postbacks...39

Postbacks Example...40

Analytics Methods...41

Android SDK 4.x for Marketing Cloud Solutions Last updated 9/15/2015

(3)

Acquisition...45

Mobile App Acquisition...45

Acquisition Methods...46

Messaging...47

In-app Messaging...47

Push Messaging...49

Location...51

Geo-Location and Points of Interest...51

Beacon tracking...53

Target...55

Target Configuration...55

Target Methods...55

Marketing Cloud...58

Marketing Cloud Visitor ID Configuration...58

Marketing Cloud Visitor ID Service Methods...58

Audience Manager...60

Audience Manager Configuration...60

Audience Manager Methods...60

Lifecycle Metrics...62

Wearables...67

Android Wearable Implementation...67

Android SDK Reference...70

App IDs...70

Visitor Tracking Between an App and Mobile Web...70

(4)

Android Widgets...71

Opt-Out and Privacy Settings...72

Using Bloodhound to Test Mobile Applications...73

PhoneGap Plug-in...74

PhoneGap Plug-in Methods...75

4.x Migration Guide...80

Documentation Updates...84

Historical Release Notes...86

Contact and Legal Information...88

(5)

Android SDK 4.x for Marketing Cloud Solutions

Android SDK 4.x for Marketing Cloud Solutions lets you measure native Android applications, deliver targeted content within your app, and leverage and collect audience data through audience management.

Last Update: September 17, 2015

Version 4.6 of the SDK is now available! See Release Notes for Android SDK 4.x for Marketing Cloud Solutions. This SDK supports Android 2.2 or later.

Note: In version 4.2 and later, all hits are now sent using HTTP POST. This has no impact on the data that is collected or reported, but you'll need to use a packet analyzer that supports inspecting POST data to view hits, such as the Bloodhound 3 beta.

If you are upgrading from a previous version, you'll want to take a look at the 4.x Migration Guide.

Adobe Mobile Services

Adobe Mobile services provides a new UI that brings together mobile marketing capabilities for mobile applications from across the Adobe Marketing Cloud. Initially, the Mobile service provides seamless integration of app analytics and targeting capabilities from the Adobe Analytics and Adobe Target solutions.

Learn more at Adobe Mobile Services documentation.

5 Android SDK 4.x for Marketing Cloud Solutions

(6)

Release Notes for Android SDK 4.x for Marketing Cloud

Solutions

Release notes and known issues for Android SDK 4.x for Marketing Cloud Solutions. This section contains the following information:

•Current Release Notes

•Marketing Cloud Release Notes, Documentation Updates, and Historical Release Notes

Current Release Notes

The Android SDK version 4.6 (September 17, 2015) includes the following changes:

Description Feature

Adobe Mobile Services and the Adobe Mobile SDK allow you to send push messages to Analytics segments. The SDK also allows you to easily report users that have opened your app as a result of opening the push message.

Push Messaging to Analytics Segments

See Push Messaging.

Allows developers to start an app acquisition campaign as if the user had clicked a link. This is helpful for creating manual acquisition links and handling the app store redirect yourself. Acquisition Methods

See Acquisition.

Postback Signals let you send data collected by the SDK to a separate third-party server. Leveraging the same triggers and traits you use to display an in-app message, you can configure the SDK to send customized data to a third-party destination.

Postbacks

See Postbacks.

Added the following new identifiers: Identifiers

• The setPushIdentifier method in Configuration Methods.

• The submitAdvertisingIdentifierTask method in Configuration Methods.

Marketing Cloud Release Notes, Documentation Updates, and Historical Release Notes

In addition to the notes for each release, the following resources provide additional information:

Description Resource

View the latest release notes for the Adobe Marketing Cloud solutions.

Marketing Cloud Release Notes

View detailed information about updates to this guide that might not be included in these release notes.

Documentation Updates

6 Release Notes for Android SDK 4.x for Marketing

(7)

Description Resource

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

Historical Release Notes

7 Release Notes for Android SDK 4.x for Marketing

(8)

Getting Started

Information to help you get starting with the Android SDK for Marketing Cloud Solutions.

Before You Start

Complete these steps to configure a report suite to collect app data.

If you are an Analytics administrator: Complete the steps in Set up your App in Adobe Mobile Services to configure a report suite to collect mobile app data. After you complete these steps, create an Analytics account for each app developer and give them access to view the report suite(s) you created.

If you are an app developer: Send a link to this page to your Analytics administrator and ask him or her to complete these steps.

After the report suite is configured, your administrator will provide you with a login you can use to complete steps in Download the SDK and Testing Tools.

This section contains the following information: •Set up your App in Adobe Mobile Services

•Download the SDK and Testing Tools

Set up your App in Adobe Mobile Services

Note: You must be an Analytics Administrator to complete these steps.

Adobe Mobile services is the primary reporting interface for mobile app analytics and targeting. After you complete these steps you can download a configuration file that is pre-configured with your data collection server, report suite, and many other settings.

First, sign in at https://mobilemarketing.adobe.com. Two ways exist for you to sign in:

• Marketing Cloud: Sign in to the Marketing Cloud with your Adobe ID. This method assumes that your company has been

provisioned in the Marketing Cloud, and you have linked your Analytics account. (If you are unsure, use your existing Adobe Analytics account.)

• Adobe Analytics: Click Sign in with Analytics provide your Analytics company, username, and password.

Complete the following steps to set up a new report suite to collect app data and to define an app in Adobe Mobile services. 1. Click the Create New App button. (If you don't see this button, click Manage Apps > Add instead.)

2. From the Report Suite drop-down, select New Report Suite.

3. Provide the name of your App and select a unique report suite ID, for example, mycomobileappdev. Note that you'll need

to set up separate report suites and apps for the development and production versions, so you can repeat these steps when you are ready to set up the production version.

4. Leave Mobile App Template selected. This template enables timestamps to collect offline data and activates the mobile solution variables to capture lifecyle metrics.

5. Select your Timezone and Currency, and then click Save.

Download the SDK and Testing Tools

After an Analytics Administrator has completed the previous steps, complete the following to download the mobile SDKs. 1. Browse to https://mobilemarketing.adobe.com and log-in the with the account your administrator created for you. 2. Select your App from the drop-down list in the left navigation.

3. Click the Gear icon to open the App configuration.

8 Getting Started

(9)

4. Scroll to bottom of the page and download the SDK, Bloodhound, and the Sample App for your platform. A config file for your App is included in the SDK download automatically, so you don't need to download that separately unless you have already downloaded the SDK and you just want to get updated settings.

Core Implementation and Lifecycle

Information to help you implement the Android library and collect lifecyle metrics (launches, upgrades, sessions, engaged users, and so on).

This section contains the following information: •Core Implementation and Lifecycle

•Add the SDK and Config File to your Project (IntelliJ IDEA)

•Add the SDK and Config File to your Project (Eclipse)

•Add App Permissions

•Implement Lifecycle Metrics

Get the SDK

Requires Android 2.2 or later.

Complete the steps in Before You Start to set up a development report suite and download a pre-populated version of the configuration file.

After unzipping the [Your_App_Name_]AdobeMobileLibrary-4.*-Android.zip download file, you'll have the following software components:

•adobeMobileLibrary.jar: Library designed for use with Android devices and simulators. •ADBMobileConfig.json: SDK configuration file customized for your app.

Note: If you download the SDK outside of the Adobe Mobile services UI, the ADBMobileConfig.json must be manually configured. If you are new to Analytics and the mobile SDK, we highly recommend using the steps in Before You Start to set up a development report suite and download a pre-populated version of the configuration file. Configuration is not difficult, but it can be a source of frustration when you are getting started.

Add the SDK and Config File to your Project (IntelliJ IDEA)

For IntelliJ users:

1. Add the ADBMobileConfig.json file to the assets folder of your project. 2. Right click your project in the Project navigation panel.

3. Select Open Module Settings.

4. Select Libraries under Project Settings. 5. Click + icon to add a new library.

6. Select Java and navigate to the adobeMobileLibrary.jar file. 7. Select the modules where you plan to use the mobile library. 8. Click Apply, and then OK to close the Module Settings window.

Add the SDK and Config File to your Project (Eclipse)

For Eclipse users:

1. Add the ADBMobileConfig.json file to the assets folder of your project.

9 Getting Started

(10)

2. In the Eclipse IDE, right-click on the project name. 3. Select Build Path > Add External Archives. 4. Select adobeMobileLibrary.jar. 5. Click Open.

6. Right-click the project again, then select Build Path > Configure Build Path. 7. Click the Order and Export tab.

8. Ensure that adobeMobileLibrary.jar is selected.

Add App Permissions

The AppMeasurement Library requires the following permissions to send data and record offline tracking calls: •INTERNET

•ACCESS_NETWORK_STATE

To add these permissions, add the following lines to your AndroidManifest.xml file (in the application project directory):

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Implement Lifecycle Metrics

After you enable lifecycle, each time your app is launched, a single hit is sent to measure launches, upgrades, sessions, engaged users, and many other Lifecycle Metrics.

In your main activity:

1. Import the library:

import com.adobe.mobile.*;

2. Within the onCreate method, allow the SDK access to your application context using Config.setContext:

@Override

public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);

setContentView(R.layout.main);

// Allow the SDK access to the application context Config.setContext(this.getApplicationContext()); }

3. Within the onResume function, begin collecting lifecycle data: @Override

public void onResume() {

Config.collectLifecycleData(this);

// -or- Config.collectLifecycleData(this, contextData); }

4. Within the onPause function, pause collecting lifecycle data: @Override

public void onPause() {

Config.pauseCollectingLifecycleData(); }

In Each activity within your application:

1. Import the library:

10 Getting Started

(11)

2. Within the onResume function, begin collecting lifecycle data: @Override

Config.collectLifecycleData(this);

// -or- Config.collectLifecycleData(this, contextData); }

3. Within the onPause function, pause collecting lifecycle data:

@Override

public void onPause() {

It is essential that you add these calls to every activity to ensure accurate crash reporting.

Including Additional Data with Lifecycle Calls

To include additional data with lifecycle metric calls, pass an additional parameter to collectLifecycleData that contains

context data:

@Override

HashMap<String, Object> contextData = new HashMap<String, Object>(); contextData.put("myapp.category", "Game");

Config.collectLifecycleData(this, contextData); }

Additional context data values that are sent with collectLifecycleData must be mapped to custom variables in Adobe Mobile services:

Other Lifecycle Metrics are collected automatically. What to do next:

•Track App States

•Track App Actions

Processing Rules and Context Data

Processing rules are used to copy the data you send in context data variables to evars, props, and other variables for reporting.

Processing Rules Training @ Summit 2013

Processing Rules Help

11 Getting Started

(12)

Become authorized to use Processing Rules

We recommend grouping your context data variables using "namespaces", as it helps you keep logical ordering. For example, if you want to collect info about a product, you might define the following variables:

"product.type":"hat" "product.team":"mariners" "product.color":"blue"

Context data variables are sorted alphabetically in the processing rules interface, so namespaces let you quickly see variables that are in the same namespace.

We recommend that you avoid naming context data keys using the evar or prop number:

"eVar1":"jimbo"

This might make it slightly easier when you perform the one time mapping in processing rules, but you lose readability during debugging and future code updates can be more difficult. Instead, we strongly recommend using descriptive names for keys and values:

"username":"jimbo"

Context variables that define counter events should be set to 1:

"logon":"1"

Context data variables that define incrementor events can have the event as the key and the amount to increment as the value:

"levels completed":"6"

Note: Adobe reserves the namespace "a.". Aside from that small restriction, context data variables just need to be unique in your login company to avoid collisions.

12 Getting Started

(13)

Configuration

Information to help you configure the Android SDK, including JSON configuration, hit batching, and SDK methods.

ADBMobile JSON Config

Information to help you use the ADBMobile JSON Config file.

ADBMobileConfig.json Config File Reference

The same config file can be used for your app across multiple platforms.

iOS: The ADBMobileConfig.json can be placed anywhere that it is accessible in your bundle.

Android: The ADBMobileConfig.json must be placed in the assets folder.

Description Minimum

SDK Version Variable

Enables mobile app acquisition. 4.1

acquisition

server - Acquisition server that is checked at the initial launch for an acquisition referrer. appid - Generated ID that uniquely identifies this app on the acquisition server. If this section is missing, you need to enable Mobile App acquisition and then re-download the SDK configuration file.

Override the ADBMobile JSON Config Path

Load a different ADBMobile JSON Config file when the application starts.

The Config.overrideConfigStream(configInput) method enables you to specify the path to a different ADBMobile.json

configuration file when the application starts. This method must be called before any other Marketing Cloud SDK call (before

Config.collectLifecycleData() ), likely in the onCreate method of your first loaded activity.

Calling this method with a different path causes a one-time override of the configuration file until the application is closed.

try {

InputStream configInput = getAssets().open("ExampleJSONFile.json"); Config.overrideConfigStream(configInput);

} catch (IOException ex) {

// do something with the exception if needed }

Hit Batching

Hit batching allows applications with offline tracking enabled to hold hits from being sent until the number of hits in the queue pass a configurable limit.

Requires SDK version 4.1 or later

To enable hit batching, you need to update your ADBMobileConfig.json and specify a value for batchLimit:

"analytics": { "batchLimit": 5, ...

}

When set to a number higher than 0, the SDK queues the number of hits equal to batchLimit. After this threshold is passed, all hits in the queue are sent.

The following methods are used in conjunction with hit batching:

•Analytics.getQueueSize() - Returns a long with the number of hits currently in the hit batching queue.

•Analytics.sendQueuedHits() - Forces the library to send all hits in the queue no matter how many are currently queued. •Analytics.clearQueue() - Clears all hits from the queue without sending them.

: Offline tracking must be enabled to use hit batching.

20 Configuration

(21)

Configuration Methods

List of methods provided by the Android library. This section contains the following information: •Initial Configuration

•SDK Settings (Config Class)

Initial Configuration

The following method must be called once in the onCreate() method of your main activity. Description

Method

Example: @Override

public void onCreate(Bundle savedInstanceState) {

setContext

super.onCreate(savedInstanceState); setContentView(R.layout.main);

Config.setContext(this.getApplicationContext()); }

SDK Settings (Config Class)

Description Method

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

•MOBILE_PRIVACY_STATUS_OPT_IN - hits are sent immediately. •MOBILE_PRIVACY_STATUS_OPT_OUT - hits are discarded.

•MOBILE_PRIVACY_STATUS_UNKNOWN - If your report suite is timestamp-enabled, hits are saved until the privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). If your report suite is not timestamp-enabled, hits are discarded until the privacy status changes to opt in.

Default: The default value is set in ADBMobileConfig.json

Syntax:

public static MobilePrivacyStatus getPrivacyStatus(); Example:

MobilePrivacyStatus privacyStatus = Config.getPrivacyStatus();

Sets the privacy status for the current user to status. Set to one of the following values:

setPrivacyStatus

21 Configuration

(22)

•MOBILE_PRIVACY_STATUS_OPT_IN - hits are sent immediately.

•MOBILE_PRIVACY_STATUS_OPT_OUT - hits are discarded.

•MOBILE_PRIVACY_STATUS_UNKNOWN - If your report suite is timestamp-enabled, hits are

saved until the privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). If your report suite is not timestamp-enabled, hits are discarded until the privacy status changes to opt in.

Syntax:

public static void setPrivacyStatus(MobilePrivacyStatus status); Example:

Config.setPrivacyStatus(MobilePrivacyStatus.MOBILE_PRIVACY_STATUS_OPT_IN);

Returns the lifetime value of the current user. getLifetimeValue

Default: 0

Syntax:

public static BigDecimal getLifetimeValue(); Example:

BigDecimal currentLifetimeValue = Config.getLifetimeValue();

Returns the custom user identifier if a custom identifier has been set. Returns null if a custom identifier is not set.

getUserIdentifier

Default: null

Note: If your app upgrades from the Marketing Cloud 3.x to 4.x SDK, the previous visitor ID (either custom or automatically generated) is retrieved and stored as the custom user identifier. This preserves visitor data between upgrades of the SDK. For new installations on the 4.x SDK, user identifier is null until set.

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

Default: false

22 Configuration

(23)

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);

Indicates to the SDK that lifecycle data should be collected for use across all solutions in the SDK. See Lifecycle Metrics.

collectLifecycleData

Syntax:

public static void collectLifecycleData(final Activity activity, final Map<String, Object> contextData);

Example:

Without extra context data:

@Override

protected void onResume() { super.onResume();

Config.collectLifecycleData(this); }

With extra context data:

@Override

HashMap<String, Object> contextData = new HashMap<String, Object>(); contextData.put("myapp.category", "Game");

Config.collectLifecycleData(this, contextData); }

(4.2 or later) Indicates to the SDK that lifecycle data should be collected for use across all solutions in the SDK. See Lifecycle Metrics.

collectLifecycleData (Activity activity)

Syntax:

public static void collectLifecycleData(final Activity activity); Example:

@Override

protected void onResume() { super.onResume();

// assumes being called in an Activity class Config.collectLifecycleData(this);

}

23 Configuration

(24)

Indicates to the SDK that your app is paused, so that lifecycle metrics are calculated correctly. For example, on pause collects a timestamp to determine previous session length. This also sets a flag so that lifecycle correctly knows that the app did not crash. See Lifecycle Metrics. pauseCollectingLifecycleData

Syntax:

public static void pauseCollectingLifecycleData(); Example:

@Override

protected void onPause() { super.onPause();

(4.2 or later) Set the small icon that will be used for notifications created by the SDK. This icon will show up in the status bar. This will also be the secondary image shown when the user sees the full notification in the notification center.

setSmallIconResourceId(int resourceId)

Syntax:

public static void setSmallIconResourceId(final int resourceId); Example:

Config.setSmallIconResourceId(R.drawable.appIcon);

(4.2 or later) Set the large icon that will be used for notifications created by the SDK. This icon will be the primary image shown when the user sees the full notification in the notification center.

setLargeIconResourceId(int resourceId)

Syntax:

public static void setLargeIconResourceId(final int resourceId); Example:

Config.setLargeIconResourceId(R.drawable.appIcon);

(4.2 or later) Lets you load a different ADBMobile JSON Config file when the application starts. The different configuration is used until the application is closed.

overrideConfigStream(InputStream configInput)

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

24 Configuration

(25)

Syntax:

public static void setPushIdentifier(final String registrationId); Example:

...

// note: the code to retreive the push token must run in the background InstanceID instanceID = InstanceID.getInstance(getApplicationContext()); String token = instanceID.getToken("835015092242",

GoogleCloudMessaging.INSTANCE_ID_SCOPE, null); Config.setPushIdentifier(token);

...

Provide a Callable to the SDK that returns the string of the Advertising Identifier returned from Google Play Services. The SDK runs this task on a background thread and sets an internal variable for Advertising Identifier based on the value returned from the Callable.

submitAdvertisingIdentifierTask

Note, if you want to use Advertising Identifier in Acquisition or Lifecycle, you must call it before calling Config.collectLifecycleData.

Syntax:

public static void submitAdvertisingIdentifierTask(final Callable<String> task);

Example: @Override

public 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); } 25 Configuration

(26)

Analytics

Information to help you use the Android SDK with Adobe Analytics.

Track App States

States are the different screens or views in your application.

Each time a new state is displayed in your application (for example, when a user navigates from the home page to the news feed), you should send a trackState call. In Android, trackState is typically called each time a new Activity is loaded.

How to Track

Prerequisites: Add the library to your project and implement lifecycle. 1. Import the library:

2. Within the onCreate function, call trackState to send a hit for this state view: @Override

// Adobe - track when this state loads Analytics.trackState("State Name", null); }

The "State Name" is reported in the View State variable in Adobe Mobile services, and a view is recorded for each trackState

call. In other Analytics interfaces, View State is reported as Page Name and state views is reported as page views.

Sending Additional Data

In addition to the "State Name", you can send additional context data with each track action call:

@Override

// 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:

26 Analytics

(27)

App State Reporting

States are typically viewed using a pathing report so you can see how users navigate your app, and which states are viewed most. View States Report. This report is based on the paths users took through your application. For example, Login > Home > Settings, or Home > Feed.

Adobe Mobile Services

States can be viewed anywhere Pages can be viewed, such as the Pages Report, Page Views report, and Path Reports.

Adobe Analytics

States can be viewed anywhere Pages can be viewed using the Page dimension, Page Views metric, Path Reports.

Ad hoc analytics

Track App Actions

Actions are the events that occur in your app that you want to measure.

Each action has one or more corresponding metrics that are incremented each time the event occurs. For example, you might send a trackAction call for each new subscription, each time an article is viewed, or each time a level is completed. Actions are not tracked automatically, you must call trackAction when an event you want to track occurs, and then map the action to a custom event.

How to Track

2. When the action that you want to track occurs in your app, call trackAction to send a hit for this action: Analytics.trackAction("myapp.ActionName", null);

3. In Adobe Mobile services, select your app and click Manage App Settings. 4. Click Manage Variables and Metrics and then click the Custom Metrics tab.

5. Map the context data name defined in your code ("myapp.ActionName " in the example) to a custom event.

27 Analytics

(28)

You can also set a prop to hold all action values by mapping a custom prop with a name like "Custom Actions" and setting the value to 'a.action'.

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);

28 Analytics

(29)

Action Reporting

Report Interface

Action Paths Report. View the order in which actions occur in your app. Adobe Mobile Services

You can also click Customize on any report to view actions ranked, trended, or in a breakdown report. Apply a filter to view actions for a specific segment.

Custom Event Report. After an action is mapped to a custom event, you can view mobile events similar to all other Analytics events.

Marketing reports & analytics

Custom Event Report. After an action is mapped to a custom event, you can view mobile events similar to all other Analytics events.

Ad hoc analytics

Track App Crashes

App crashes are tracked as part of lifecycle metrics. To track crashes, add the library to your project and implement lifecycle. When lifecycle metrics are implemented, a call is made to Config.collectLifecycleData in the OnResume method of each activity. In the onPause method, a call is made to Config.pauseCollectingLifeCycleData.

Inside of the pauseCollectingLifeCycleData, a flag is set to indicate a graceful exit. When the app is relaunched or resumed, collectLifecycleData checks this flag for a graceful exit. If the app did not exit successfully (as determined by the flag status), an a.CrashEvent context data is sent with the next call and a crash event is reported.

To ensure accurate crash reporting, you must call the pauseCollectingLifeCycleData inside of the onPause method of each activity. To understand why this is essential, it is helpful to understand the Android activity lifecycle:

29 Analytics

(30)

If a call is not made to pauseCollectingLifeCycleData before your app is paused, when the user returns to your app or when your app is re-launched, the SDK reports a crash event since the flag is not set to indicate a graceful exit.

If Config.collectLifecycleData is called twice in a row during the same session (without a call to

pauseCollectingLifeCycleData in between), then a crash is reported on every call after the first. For example, if you forget

to add a call to pauseCollectingLifeCycleData to onPause for an activity, then a crash might be reported if the app is backgrounded during that activity.

(See http://developer.android.com/guide/components/activities.html for more information on Android activity lifecycle. The Android lifecycle image that appears on this page was created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License)

30 Analytics

(31)

Timed Actions

Timed actions let you measure in-app time and total time between the start and end of an action. The SDK calculates the amount of time in session and the total time (cross-session) it takes for the action to be completed. This can be used to define segments to compare on time to purchase, pass level, checkout flow, and so on.

The following metrics are reported for timed actions:

• Total # of seconds in app between start and end - cross sessions • Total # of seconds between start and end (clock time)

An optional callback allows you to take additional action when the timed action completes: • Run code and add any logic - optional custom logic based on duration results.

• Add context data prior to passing in durations. • Cancel hit and durations not yet sent.

How to Track

2. Call trackTimedActionStart and provide a timed action name and optional context data.

HashMap cdata = new HashMap<String, Object>(); cdata.put("ExperienceName", experience);

Analytics.trackTimedActionStart("TimeUntilPurchase", cdata);

3. (Optional) At any point, you can call trackTimedActionUpdate with the timed action name to add additional context

data.

HashMap cdata = new HashMap<String, Object>(); cdata.put("myapp.ImageLiked", imageName);

Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata);

4. When the event completes, call trackTimedActionEnd and pass the timed action name and TimedActionBlock (callback) which will look up all data and calculate durations. Timed event metrics are saved in mobile solution variables for automatic reporting.

Analytics.trackTimedActionEnd("TimeUntilPurchase", cdata);

In addition to the timed action name, you can send additional context data with the action start and action update calls:

Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata);

31 Analytics

(32)

Examples

// Timed Action Start Example

HashMap cdata = new HashMap<String, Object>(); cdata.put("ExperienceName", experience);

Analytics.trackTimedActionStart("TimeUntilPurchase", cdata); // Timed Action Update Example

cdata = new HashMap<String, Object>(); cdata.put("ImageLiked", imageName);

Analytics.trackTimedActionUpdate("TimeUntilPurchase", cdata); // Timed Action End Example

Analytics.trackTimedActionEnd("TimeUntilPurchase", null); // Timed Action End Example with Callback

Analytics.trackTimedActionEnd("TimeUntilPurchase", new Analytics.TimedActionBlock<Boolean>() {

@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

Lifetime value lets you measure and target on a lifetime value for each user.

Each time you send in a value with trackLifetimeValueIncrease, the value is added to the existing value. Lifetime value

is stored on device and can be retrieved at any time by calling lifetimeValue. This can be used to store lifetime purchases, ad views, video completes, social shares, photo uploads, and so on.

How to Track

2. Call trackLifetimeValueIncrease with the amount to increase the value:

Analytics.trackLifetimeValueIncrease(BigDecimal.valueOf(5.0), null);

32 Analytics

(33)

In addition to the lifetime value, you can send additional context data with each track action call:

Analytics.trackLifetimeValueIncrease(BigDecimal.valueOf(5.0), cdata);

Products Variable

The products variable cannot be set using processing rules. In the mobile SDK, you must use a special syntax within the context data parameter to set products directly on the server call.

To set the products variable, set a context data key to "&&products", and set the value using the syntax defined for the products

variable:

cdata.put("&&products", "Category;Product;Quantity;Price[,Category;Product;Quantity;Price]");

For example:

//create a context data dictionary

HashMap cdata = new HashMap<String, Object>();

// add products, a purchase id, a purchase context data key, and any other data you want to collect.

// Note the special syntax for products

cdata.put("&&products", ";Running Shoes;1;69.95,;Running Socks;10;29.99"); cdata.put("myapp.purchase", "1");

cdata.put("myapp.purchaseid", "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);

Note that products is set directly on the image request, and the other variables are set as context data:

33 Analytics

(34)

All context data variables must be mapped using processing rules:

You do not need to map the products variable using processing rules since it is set directly on the image request by the SDK.

Products Variable with Merchandising eVars and Product-Specific Events

An example of the products variable with Merchandising eVars and product-specific events.

HashMap cdata = new HashMap<String, Object>();

// add products, a purchase id, a purchase context data key, and any other data you want to collect.

// Note the special syntax for products cdata.put("&&events", "event1");

cdata.put("&&products", ";Running Shoes;1;69.95;event1=5.5;eVar1=Merchandising,;Running Socks;10;29.99");

cdata.put("myapp.purchase", "1");

cdata.put("myapp.purchaseid", "1234567890");

Analytics.trackAction("purchase", cdata);

34 Analytics

(35)

// trackState example:

Analytics.trackState("Order Confirmation", cdata);

Note: If you trigger a product-specific event using the &&products variable, you must also set that event in the &&events variable, otherwise the event 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 within the context data parameter to set serialized events directly on the server call.

See Event Serialization.

cdata.put("&&events", "event1:12341234");

For example:

HashMap cdata = new HashMap<String, Object>(); // add events

cdata.put("&&events", "event1:12341234");

Analytics.trackAction("action", cdata); // trackState example:

Analytics.trackState("State Name", cdata);

Video Analytics

This guide describes measuring video on Android using milestone video measurement.

Note: Adobe has a new video measurement solution called video heartbeat. During video playback, frequent "heartbeat" calls are sent to this service to measure time played. These heartbeat calls are sent every 10 seconds , which results in granular video engagement metrics and more accurate video fallout reports. See Measuring Video in Adobe Analytics using Video Heartbeat for details.

Additional information on milestone video measurement is available in the Measuring Video in Analytics guide. The general process to measure video is very similar across all platforms. This quick start section provides a basic overview of the developer tasks along with code samples.

Map Player Events to Analytics Variables

The following table lists the media data that is sent to Analytics. Use processing rules to map the context data in the Context Data Variable column to an Analytics variable as described in the Variable Type column.

Description Variable Type

Context Data Variable

(Required) Collects the name of the video, as specified in the implementation, when a visitor views the video in some way.You can add classifications for this variable.

eVar

Default expiration: Visit Custom Insight (s.prop, used for video pathing)

a.media.name

35 Analytics

(36)

(Optional) The Custom Insight variable provides video pathing information.

(Optional) Provides video pathing information. Pathing must be enabled for this variable by ClientCare.

Custom Insight (s.prop) a.media.name

Event type: Custom Insight (s.prop)

(Required) Collects video segment data, including the segment name and the order in which the segment occurs in the video. eVar

Default expiration: Page view a.media.segment

This variable is populated by enabling the

segmentByMilestones variable when tracking player events automatically, or by setting a custom segment name when tracking player events manually.

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 the following points: video start (play), segment begin, and video end (stop). Analytics counts the first segment view at the start of the segment, when the visitor starts watching. Subsequent segment views as the segment begins.

Collects data about the type of content viewed by a visitor. Hits sent by video measurement are assigned a content type of "video". eVar

Default expiration: Page view a.contentType

This variable does not need to be reserved exclusively for video tracking. Having other content report content type using this same variable lets you analyze the distribution of visitors across the different types of content. For example, you could tag other content types using values such as “article" or “product page" using this variable.

From a video measurement perspective, Content Type lets you identify video visitors and thereby calculate video conversion rates.

Counts the time, in seconds, spent watching a video since the last data collection process (image request).

Event

Type: Counter a.media.timePlayed

Indicates that a visitor has viewed some portion of a video. However, it does not provide any information about how much, or what part, of a video the visitor viewed.

Event

Type: Counter a.media.view

36 Analytics

(37)

Indicates that a visitor has viewed some portion of a video segment. However, it does not provide any information about how much, or what part, of a video the visitor viewed. Event

Type: Counter a.media.segmentView

Indicates that a user has viewed a complete video. By default, the complete event is measured 1 second before the end of the video.

Event

Type: Counter a .media.complete

During implementation, you can specify how many seconds from the end of the video you would like to consider a view complete. For live video and other streams that don't have a defined end, you can specify a custom point to measure completes. 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, mediaStop. mediaPlay is called when playback starts or is resumed.

Classes

Class: MediaSettings public 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 settings

public String parentName; public String parentPod; public String CPM;

public double parentPodPosition; public boolean isMediaAd;

Class: MediaState

public Date openTime = new Date(); public String name;

public String segment; public String playerName; public String mediaEvent; public int offsetMilestone; public int segmentNum;

37 Analytics

(38)

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

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

Syntax:

public static void close(String name); Example:

Media.close("name");

38 Analytics

(39)

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);

Postbacks

Postbacks let you send data collected by the SDK to a separate third-party server. Leveraging the same triggers and traits you use to display an in-app message, you can configure the SDK to send customized data to a third-party destination.

Note: This functionality requires SDK version 4.6.0 or later.

39 Analytics

(40)

Postback messages are queued and follow all existing online/offline rules that govern analytics data collection. Note that postback messages do not cancel the rest of the messages if a message matches (like shown-messages do). This allows for multiple postbacks to occur on the same analytics hit.

See the "postbacks" row in ADBMobile JSON Config for the definition.

Template Expansions

Template expansions are available in both 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 available for template expansion are limited to the

standard Lifecycle variables list, in addition to any custom data attached to the hit that triggers the message. No historical-based or segment-based data is available at this time.

There are also specific, reserved templates that the SDK will replace for you automatically with internal data known to the SDK. This list includes:

Token Description Token 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 used

submitAdvertisingIdentifierTask.

{%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

Definition and source code examples for the Postbacks feature.

: This example is provided for informational purposes only. The ADBMobileConfig.json file should be configured in the Adobe Mobile UI. This file should not be modified manually. Using a manually edited configuration file is especially dangerous if you have remote messages configuration enabled.

This section contains the following information: •ADBMobileConfig.json Definition •Source Code 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}", 40 Analytics

(41)

"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" ] } ] } ] Source Code

HashMap<String, Object> contextData = new HashMap<String, Object>(); contextData.put("user.name", "bob");

contextData.put("user.zip", "90210");

Analytics.trackState("MainMenu", contextData);

Due to the fact that its state is “MainMenu”, this tracking call triggers the above postback message. The URL will replace all template variables with values from the hit. Assuming that the user’s previous session was 132 seconds long and that user is on Android SDK 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

Analytics Methods

List of Adobe Analytics methods provided by the Android library.

The SDK currently has support for multiple Adobe Marketing Cloud Solutions, including Analytics, Target, Audience Manager, and the Marketing Cloud Visitor ID Service. Methods are prefixed according to the solution. Marketing Cloud visitor ID methods are prefixed with "analytics."

Each of these methods is used to send data into your Adobe Analytics report suite.

Tracks an app state with optional context data. 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.

trackState

If state is empty, it displays as "app name app version (build)" in reports. If you see this value in reports, make sure you are setting state in each trackState call.

Note: This is the only tracking call that increments page views. Syntax:

public static void trackState(String state, Map<String, Object> contextData); 41 Analytics

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

Adobe

Marketing Cloud

Contents

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

Release Notes for Android SDK 4.x for Marketing Cloud Solutions...6

Getting Started...8

Before You Start...8

Core Implementation and Lifecycle...9

Processing Rules and Context Data...11

Configuration...13

ADBMobile JSON Config...13

Hit Batching...20

Configuration Methods...21

Analytics...26

Track App States...26

Track App Actions...27

Track App Crashes...29

Timed Actions...31

Visitor Lifetime Value...32

Products Variable...33

Event Serialization...35

Video Analytics...35

Postbacks...39

Analytics Methods...41

Acquisition...45

Mobile App Acquisition...45

Acquisition Methods...46

Messaging...47

In-app Messaging...47

Push Messaging...49

Location...51

Geo-Location and Points of Interest...51

Beacon tracking...53

Target...55

Target Configuration...55

Target Methods...55

Marketing Cloud...58

Marketing Cloud Visitor ID Configuration...58

Marketing Cloud Visitor ID Service Methods...58

Audience Manager...60

Audience Manager Configuration...60

Audience Manager Methods...60

Lifecycle Metrics...62

Wearables...67

Android Wearable Implementation...67

Android SDK Reference...70

App IDs...70

Visitor Tracking Between an App and Mobile Web...70

Android Widgets...71

Opt-Out and Privacy Settings...72

Using Bloodhound to Test Mobile Applications...73

PhoneGap Plug-in...74

PhoneGap Plug-in Methods...75

4.x Migration Guide...80

Documentation Updates...84

Historical Release Notes...86

Contact and Legal Information...88

Android SDK 4.x for Marketing Cloud Solutions

Release Notes for Android SDK 4.x for Marketing Cloud

Solutions

Getting Started

Before You Start

Core Implementation and Lifecycle

Processing Rules and Context Data

Configuration

ADBMobile JSON Config

Override the ADBMobile JSON Config Path

Hit Batching

Configuration Methods

Analytics

Track App States

Track App Actions

Track App Crashes

Timed Actions

Visitor Lifetime Value

Products Variable

Products Variable with Merchandising eVars and Product-Specific Events

Event Serialization

Video Analytics