iOS SDK 4.x for Marketing Cloud Solutions - Adobe Marketing Cloud iOS SDK 4.x for Experience Cloud...

Adobe® Experience Cloud

iOS SDK 4.x for Experience Cloud Solutions

Contents

Release Notes....................................................................................................................5

iOS SDK 4.x for Experience Cloud Solutions...................................................................6

Getting Started.................................................................................................................7Before You Start..................................................................................................................................................................7

Core Implementation and Lifecycle............................................................................................................................8

Processing Rules and Context Data..........................................................................................................................13

Swift Integration..............................................................................................................................................................14

Migrating to the 4.x iOS Library.................................................................................................................................14

Configuration..................................................................................................................20ADBMobile JSON Config...............................................................................................................................................20

Override the ADBMobile JSON Config Path....................................................................................................................................28

Hit Batching.......................................................................................................................................................................28

Configuration Methods.................................................................................................................................................28

App Transport Security.................................................................................................................................................33

Lifecycle Metrics.............................................................................................................35

Analytics..........................................................................................................................40Track App States..............................................................................................................................................................40

Track App Actions...........................................................................................................................................................41

Track App Crashes...........................................................................................................................................................43

Timed Actions...................................................................................................................................................................44

Visitor Lifetime Value.....................................................................................................................................................45

Products Variable............................................................................................................................................................46

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

Event Serialization...........................................................................................................................................................48

iOS SDK 4.x for Experience Cloud SolutionsLast updated 4/12/2018

Video Analytics.................................................................................................................................................................48

Postbacks...........................................................................................................................................................................54

Postback Example.....................................................................................................................................................................................55

PII Postbacks...............................................................................................................................................................................................56

Analytics Methods...........................................................................................................................................................56

Acquisition......................................................................................................................61Mobile App Acquisition................................................................................................................................................61

Acquisition Methods......................................................................................................................................................61

Tracking Deep Links.......................................................................................................................................................62

Tracking Third-Party Deferred Deep Links.......................................................................................................................................63

Testing Marketing Link Acquisition..........................................................................................................................66

Testing Version 3 Acquisition.....................................................................................................................................68

Testing Legacy Acquisition..........................................................................................................................................70

Apple Search Ads............................................................................................................................................................70

Messaging.......................................................................................................................72In-App Messaging...........................................................................................................................................................72

Troubleshooting In-App Messaging..................................................................................................................................................73

Push Messaging...............................................................................................................................................................75

Implement Push Messaging with Deep Linking ...........................................................................................................................78

Receive Rich Push Notifications...........................................................................................................................................................79

Troubleshooting Push Messaging......................................................................................................................................................80

Location...........................................................................................................................82Geo-Location and Points of Interest.........................................................................................................................82

iBeacon tracking..............................................................................................................................................................84

Target..............................................................................................................................86Target Methods................................................................................................................................................................86

Prefetch offer content in iOS.......................................................................................................................................90

Experience Cloud............................................................................................................96


Contents

Experience Cloud ID.......................................................................................................................................................96

Experience Cloud ID Service Methods.....................................................................................................................96

Experience Cloud Device Co-op................................................................................................................................98

Audience Manager.......................................................................................................100Audience Manager Methods....................................................................................................................................100

Apple TV Implementation with tvOS..........................................................................102Adobe Target for TVML/TVJS....................................................................................................................................103

TVJS Methods.................................................................................................................................................................105

iOS Extension Implementation...................................................................................119Stand-Alone Extension Implementation..............................................................................................................120

Apple Watch Implementation with WatchOS 2.........................................................122

iOS SDK Reference........................................................................................................125App IDs.............................................................................................................................................................................125

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

iOS Device Versions......................................................................................................................................................126

Privacy and General Data Protection Regulation......................................................130Retrieving Stored Identifiers.....................................................................................................................................130

Setting the User's Opt Status....................................................................................................................................131

Using Bloodhound to Test Mobile Applications........................................................133

PhoneGap Plug-in........................................................................................................134PhoneGap Plug-in Methods......................................................................................................................................135

Contact and Legal Information...................................................................................148


Release NotesRelease notes and known issues for iOS SDKs 4.x for Experience Cloud Solutions.

Mobile Services

Release date: April 12, 2018

New features, updates, and fixes to Mobile Services:

• Minor bug fixes.

For more information about the current and past release notes for all solutions, see Adobe Experience Cloud Release Notes.

5Release Notes

https://marketing.adobe.com/resources/help/en_US/whatsnew/

iOS SDK 4.x for Experience Cloud SolutionsiOS SDK 4.x for Experience Cloud Solutions lets you measure native Apple iPhone and iPad applications, deliver targeted contentwithin your apps, and leverage and collect audience data through Audience Manager.

Last Update: December 14, 2017

Some information to remember:

• This SDK supports iOS 5 or later.

• In version 4.2 of this SDK 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 inspectingPOST data to view hits, such as Bloodhound.

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 (2.x or 3.x), see the 4.x Migration Guide.

Adobe Mobile User Documentation

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

To learn more about the Mobile Services UI and read the user documentation, see Adobe Mobile Services.

6iOS SDK 4.x for Experience Cloud Solutions

https://marketing.adobe.com/resources/help/en_US/mobile/bloodhound/

https://marketing.adobe.com/resources/help/en_US/mobile/

Getting StartedThe following information helps you get started with the iOS SDK for Experience Cloud Solutions:

Before You Start

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

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

• Experience Cloud

Sign in to the Experience Cloud with your Adobe ID. This method assumes that your company has been provisioned in theExperience Cloud, and you have linked your Analytics account.

Tip: If you are unsure whether your company has been provisioned in the Experience Cloud, use your existing AdobeAnalytics account.

7Getting Started

https://marketing.adobe.com/resources/help/en_US/mobile/c_mob_roles-and-permissions.html

http://marketing.adobe.com

http://marketing.adobe.com/resources/help/en_US/mcloud/?f=admin_getting_started

http://marketing.adobe.com/resources/help/en_US/mcloud/?f=t_link_accounts

• 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 unique report suite ID.

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. 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, 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. In the App SDK Downloads section, 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 just want to get updated settings, download the configfile again.

Core Implementation and Lifecycle

This information helps you implement the iOS library and collect lifecycle metrics, such as launches, upgrades, sessions, engagedusers, and so on.


• Download the SDK• Add the SDK and Config File to your Project• Implement Lifecycle Metrics

Download the SDK

Important: To download the SDKs, you must use iOS 6 or later.

8Getting Started

1. Complete the steps in Create a Report Suite to set up a development report suite and download a pre-populated version ofthe configuration file.

2. Download, unzip the [Your_App_Name_]AdobeMobileLibrary-4.*-iOS.zip file, and verify that you have the followingsoftware components:

• ADBMobile.h, the Objective-C header file that is used for iOS AppMeasurement.• ADBMobileConfig.json, the SDK configuration file that is customized for your app.• AdobeMobileLibrary.a, a bitcode-enabled fat binary that contains the library builds for iOS devices (armv7, armv7s,

arm64) and simulators (i386, x86_64).

This fat binary should be linked when the target is intended for an iOS app.

• AdobeMobileLibrary_Extension.a, a bitcode-enabled fat binary that contains the library builds for iOS devices(armv7, armv7s, arm64) and simulators (i386, x86_64).

This fat binary should be linked when the target is intended for an iOS extension.

• AdobeMobileLibrary_Watch.a, a bitcode-enabled fat binary that contains the library builds for Apple Watch devices(armv7k) and simulators (i386, x86_64).

This fat binary should be linked when the target is intended for an Apple Watch (watchOS 2) extension app.

• AdobeMobileLibrary_TV.a, a bitcode-enabled fat binary that contains the library builds for new Apple TV devices(arm64) and simulator (x86_64).

This fat binary should be linked when target is intended for an Apple TV (tvOS) app.

Important: If you download the SDK outside the Adobe Mobile services UI, the ADBMobileConfig.json must be manuallyconfigured. If you are new to Analytics and the Mobile SDK, see Before You Start to set up a development report suite anddownload a pre-populated version of the configuration file.

Add the SDK and Config File to your Project

1. Launch the Xcode IDE and open your app.

2. In Project Navigator, drag the AdobeMobileLibrary folder and drop it under your project .

3. Verify the following:

• The Copy Items if needed checkbox is selected.• Create groups is selected.• None of the checkboxes in the Add to targets section is selected.

9Getting Started

4. Click Finish.

5. In Project Navigator, select ADBMobileConfig.json.

6. In File Inspector, add the JSON file to any targets in your project that will use the Adobe SDK.

7. In Project Navigator, complete the following steps:

1. Click on your app.2. On the General tab, select your targets and link the required frameworks and libraries in the Linked Frameworks and

Libraries sections.

• iOS App Targets

10Getting Started

• SystemConfiguration.framework• libsqlite3.0.tbd• AdobeMobileLibrary.a

• iOS Extension Target

• SystemConfiguration.framework• libsqlite3.0.tbd• AdobeMobileLibrary_Extension.a

• Apple Watch (watchOS 2) Target

11Getting Started

• libsqlite3.0.tbd• AdobeMobileLibrary_Watch.a

• Apple TV (tvOS) Target

• SystemConfiguration.framework• libsqlite3.0.tbd• AdobeMobileLibrary_TV.a

: Linking more than one AdobeMobileLibrary*.a file in the same target will result in unexpected behavior or theinability to build.

8. Confirm that your app builds without errors.

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 other Lifecycle Metrics.

Add a collectLifecycleData/collectLifecycleDataWithAdditionalData call inapplication:didFinishLaunchingWithOptions:- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [ADBMobile collectLifecycleData]; return YES;}

12Getting Started

Include Additional Data with Lifecycle Calls

To include additional data with lifecycle metric calls, use collectLifecycleDataWithAdditionalData:

Important: Any data that is passed to the SDK through collectLifecycleDataWithAdditionalData: will bepersisted in NSUserDefaults by the SDK. The SDK strips the values in the NSDictionary parameter that are not of theNSString or NSNumber types.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSMutableDictionary *contextData = [NSMutableDictionary dictionary]; [contextData setObject:@"Game" forKey:@"myapp.category"]; [ADBMobile collectLifecycleDataWithAdditionalData:contextData]; return YES;}

Additional context data values that are sent with collectLifecycleDataWithAdditionalData must be mapped to customvariables in Adobe Mobile services:

Other Lifecycle Metrics are collected automatically.

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 Help• Become authorized to use 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.

13Getting Started

http://tv.adobe.com/embed/1181/16506/

https://marketing.adobe.com/resources/help/en_US/reference/?f=processing_rules

https://marketing.adobe.com/resources/help/en_US/reference/

For example, if you want to collect 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"

This might make it slightly easier when you perform the one-time mapping in processing rules, but you lose readability duringdebugging and future code updates, which can be more difficult. Instead, use 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"

Tip: Adobe reserves the namespace "a.". Aside from that restriction, to avoid collisions, the only requirement is that contextdata variables are unique in your login company.

Swift Integration

The iOS Adobe Mobile SDK can be seamlessly integrated in a Swift project by using the Mix and Match feature in the iOSDeveloper Library.

For more information, see Swift and Objective-C in the Same Project.

For example, by using the bridging header method as described in the documentation, you can import the Adobe Mobile iOSSDK header file:#import “ADBMobile.h”

To access methods from the SDK in your Swift files, use the following format:ADBMobile.{methodname}

Migrating to the 4.x iOS Library

This information helps you migrate from the versions 3.x or 2.x of the iOS library to version 4.x.

Important: The SDK uses NSUserDefaults to store data that is needed to calculate unique users, lifecycle metrics, andother data related to core SDK functionality. If you modify or remove the values in NSUserDefaults that are expectedby the SDK, unexpected behavior might result in the form of data inconsistencies.

In the version 4.x of the iOS SDK library, all of the public methods are consolidated into one header. Also, all functionality isnow accessible through class 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

14Getting Started

https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html

• 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 directly in your app. Instead, theSDK uses 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.

Tip: Values that you were assigning directly to variables should now be added to the data NSDictionary.

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" }}

The following tables list the configuration variables that you need to move to the configuration file.

Moving the configuration file

To move 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.

15Getting Started

Migrating from version 3.x

Move the value from the first column to the variable in the second column.

Variable in ADBMobileConfig.jsonConfiguration Variable

"offlineEnabled"offlineTrackingEnabled

"batchLimit"offlineHitLimit

"rsids"reportSuiteIDs

"server"trackingServer

"charset"charSet

"currency"currencyCode

"ssl"ssl

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.


"offlineEnabled"trackOffline

"batchLimit"offlineLimit

"rsids"account

"server", remove the "http://" prefix. The protocol prefix is added automatically basedon the "ssl" setting.

trackingServer

Remove. For secure connections, define "server" and then enable "ssl".trackingServerSecure

"charset"charSet

"currency"currencyCode

"ssl"ssl

16Getting Started


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

Remove, replaced by Lifecycle Metrics.useBestPractices

all calls to churn measurement(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: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.

• trackAction:data: actions , such as logons, banner taps, feed subscriptions, and other metrics that occur inyour app and that you want to measure.

The data parameter for both of these methods is an NSDictionary that contains name-value pairs that are sent as contextdata.

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 by using processing rules. For more information, see ProcessingRules and Context Data.

17Getting Started

Values that you assigned directly to variables should be added to the data NSDictionary instead. This means that calls tosetProp, setEvar, and assignments to persistent context data should all be removed and the values be added to the dataparameter.

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 dataNSDictionary instead. The only data that is sent with a trackState or trackAction call is the payload in the data parameter.

Replace Tracking Calls

In your code, replace the following methods with a call to trackState or trackAction:


• trackAppState (trackState)• trackEvents (trackAction)• track (trackAction)• trackWithContextData (trackAction)• trackLinkURL (trackAction)


• track (trackState)• 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.

In your code, remove calls to the following methods:

3.x

• setOnline• setOffline

2.x

• forceOffline• forceOnline

Products Variable

Since the products variable is not available in processing rules, you can use the following syntax to set products://create a processing rule to set the corresponding product event.// for example, set prodView event when context data a.action = "product view"[ADBMobile trackAction:@"LikeButtonClicked" data:@{@"&&products" : @";Cool Shoe"}];

18Getting Started

Test the Migration

After you have completed the migration, see Using Bloodhound to Test Mobile Applications for more information about inspectingthe data being that is sent by the mobile SDK.


19Getting Started

ConfigurationThe following information helps you configure the iOS SDK, including JSON configuration, hit batching, and SDK methods:

ADBMobile JSON Config

This information helps you use the ADBMobile.json config file.


• 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 can be placed anywhere that it is accessible in your bundle.• On Android, the ADBMobileConfig.json must be placed in the assets folder.

DescriptionMinimumSDKVersion

Variable

Enables mobile app acquisition.4.1acquisition

• 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, enable Mobile App acquisition and download the SDKconfiguration file again. For more information, see referrerTimeout below.

The default value is false.4.8.0analyticsForwardingEnabled

The property in the audienceManager object. If Audience Manager is configured andanalyticsForwardingEnabled is set to true, all Analytics traffic is also forwarded toAudience Manager.

Session info hits currently consist of crashes and session length. When disabled, the AdobeSDK will attach the session info to the current lifecycle. The default value is false.

4.6backdateSessionInfo

When enabled, the Adobe SDK will backdate the session info hit to 1 second after the lasthit of the previous session. This means that crashes and session data will correlate withthe correct date on which they occurred. One side effect is that the SDK might create avisit for the backdated hit. One hit will be backdated on every new launch of the application.

When you set backdateSessionInfo to false, the SDK returns to its pre-4.1 behaviorof lumping the session info for the previous session with the first hit of the subsequentsession, which avoids the creation of an inflated visit. This option causes an immediatedrop in visit counts because inflated visits are no longer created.

20Configuration


Variable

Important: Backdated session hit information is sent in a session info server call,and additional server calls might apply.

Threshold for number of hits to be sent in consecutive calls.4.1batchLimit

For example, if batchLimit is set to 10, each hit before the 10th hit will be stored in thequeue. Once the 10th hit comes in, all 10 hits will be sent consecutively.

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.0charset

The charset is used to convert incoming data into UTF-8 for storage and reporting. Formore information, see Using the charSet Property.

4.0clientCodeImportant: This variable is required by Target.

Your assigned client code.

Default value is 300 seconds.4.0lifecycleTimeout

Specifies the length of time, in seconds, that must elapse between the time the app launchesbut before the launch is considered to be a new session. This timeout also applies whenyour application is sent to the background and reactivated.

The time that your app spends in the background is not included in the session length.

Generated automatically by Adobe Mobile services, defines the settings for in-appmessaging. For more information, see Messages Description below.

4.2messages

When enabled, hits are queued while the device is offline and sent later when the deviceis online. Your report suite must be timestamp-enabled to use offline tracking.

4.0offlineEnabled

The default value is false.

Important: If timestamps are enabled on your report suite, your offlineEnabledconfiguration property must be true. if your report suite is not timestamp enabled,your offlineEnabled configuration property must be false. If this is not configuredcorrectly, data will be lost. If you are not sure if a report suite is timestamp enabled,contact Customer Care or download the configuration file from Adobe Mobile services.

21Configuration

http://microsite.omniture.com/t2/help/en_US/whitepapers/multibyte/?f=multibyte_charset.html


Variable

If you are currently reporting AppMeasurement data to a report suite that also collectsdata from JavaScript, you might need to set up a separate report suite for mobile data orinclude a custom timestamp on all JavaScript hits that use the s.timestamp variable.

Specifies the Experience Cloud org ID for the Experience Cloud ID service.4.3org

Each POI array holds the POI name, latitude, longitude, and radius (in meters) for thearea of the point. The POI name can be any string.

4.0poi

When a trackLocation call is sent, if the current coordinates are in a defined POI, acontext data variable is populated and sent with the trackLocation 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 Mobile interface andsynchronized dynamically to the app configuration file. This synchronization requiresthe analytics.poi setting:“analytics.poi”: “https://assets.adobedtm.com/…/yourfile.json”,

If this setting is not configured, the ADBMobile.json file must be updated to includethis line. To download an updated configuration file, see Before You Start.

The definition for the "callback" message template is shown below:"payload": { "templateurl": "", // required - will be token-expanded prior to

4.6postback

being sent "templatebody": "", // optional - if this length > 0 POST will be used as transport method. This is a base64 encoded blob, which will be decoded and token-expanded prior to being sent. "contenttype": "", // optional - if this is length > 0 and POST type is selected this will be set as the Content-Type header. if this is not supplied for a POST request, the default will be "application/x-www-form-urlencoded" "timeout": 0 // optional - number of seconds to wait before timing out. Default is 2.}

The payload object in the code is an example payload for a message definition that wouldgo in ADBMobileConfig.json.

For more information, see the relevant topic:

• Android: Postbacks

• iOS: Postbacks

Default value is optedin.4.0privacyDefault

• For optedin, the hits are sent immediately.

22Configuration

https://marketing.adobe.com/resources/help/en_US/mobile/android/postbacks.html

https://marketing.adobe.com/resources/help/en_US/mobile/ios/postback.html


Variable

• 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 are discarded).

If your report suite is not timestamp-enabled, hits are discarded until the privacy statuschanges to opt in.

This only sets the initial value. If this value is set or changed in code, the new value is useduntil it is changed again, or when the app is uninstalled and reinstalled.

Number of seconds the SDK waits for acquisition referrer data on the initial launch beforetiming out. If you are using acquisition, we recommend a 5-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 for acquisition 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 against thecurrent version at each launch, and the updates are downloaded and saved.

4.2remotes

• analytics.poi is the endpoint for hosted POI configuration.• messages is the endpoint for hosted in-app message configuration.

4.0rsidsImportant: This variable is required by Analytics.

One or more report suites to receive Analytics data. Multiple report suite IDs should becomma-separated with no space between."rsids" : "rsid"

"rsids" : "rsid1,rsid2"

4.0serverImportant: This variable is required by Analytics and/or Audience Management.

The Analytics or Audience Management server, based on the parent node.

This variable should be populated with the server domain, without an http:// orhttps:// protocol prefix. This prefix is handled automatically by the library and isbased on the ssl variable.

If ssl is true, a secure connection is made to this server. If ssl is false, a non-secureconnection is made to this server.

The default value is false.4.0ssl

23Configuration


Variable

Enables (true) or disables (false) the ability to send measurement data by using 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 definition that goesin ADBMobileConfig.json.

For more information, see the relevant topic:

• Postbacks (Android)

• Postbacks (iOS)

Determines how long Target waits for a response.4.0timeout

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,

24Configuration

https://marketing.adobe.com/resources/help/en_US/mobile/android/postbacks.html

https://marketing.adobe.com/resources/help/en_US/mobile/ios/postback.html

"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"

}}

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

• "payload"

• "html"

• fullscreen template only, required•

• html defining the message

• "image"

• fullscreen only, optional•

25Configuration

• url to the image to be used for a fullscreen image

• "altImage"

• fullscreen only, optional•

• name of the bundled image to use if the url specified in

image

is unreachable

• "title"

• fullscreen and alert, required•

• title text for a fullscreen or alert message

• "content"

• alert and local notification, required•

• 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

• "showOffline"

• true or false

• default is false

•• "showRule"

• "always", "once", or "untilClick"

• required

• "endDate"

• number of seconds since Jan 1, 1970

26Configuration

• default is 2524730400

• "startDate"

• number of seconds since Jan 1, 1970

• default is 0

• "audiences"

An array of objects that defines how the message should be shown

• "key"

• Variable name to look for in the hit, and it is required.

• "matches"

Type of matcher used when doing the comparison

• • eq = equals

• ne = does not equal

• co = contains

• nc = does not contain

• sw = starts with

• ew = ends with

• ex = exists

• nx = does not exist

• lt = less than

• le = less than or equals

• gt = greater than

• ge = greater than or equals

• "values"

An array of values used to match against the value of the variable named in the following:

• key• with the matcher type in• matches

• "triggers"

Same as audiences, but here are the actions instead of the audience:

• "key"

• "matches"

• "values"

27Configuration

Override the ADBMobile JSON Config Path

You can load a different ADBMobile JSON Config file when the application starts.

The [ADBMobile overrideConfigPath:filePath] method allows you to specify the path to a different ADBMobile.jsonconfiguration file when the application starts. This method must be called in theapplicationDidFinishLaunchingWithOptions method, and the call must occur before any other Experience Cloud SDKcall, such as collectLifecycleData.

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

For example:NSString *filePath = [[NSBundle mainBundle] pathForResource:@"ExampleJSONFile" ofType:@"json"];[ADBMobile overrideConfigPath:filePath];

Hit Batching

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

Important: Hit batching 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, allhits in the queue are sent.

The following methods are used with hit batching:

• trackingGetQueueSize() returns an NSUInteger with the number of hits currently in the hit batching queue.• trackingSendQueuedHits() forces the library to send all hits in the queue no matter how many are currently queued.• trackingClearQueue() clears all hits from the queue without sending them.

: Offline tracking must be enabled to use hit batching.

Configuration Methods

Here is a list of methods that are provided by the iOS library.

The SDK currently has support for multiple Adobe Experience Cloud Solutions, including Analytics, Target, Audience Manager,and the Experience Cloud ID service.

DescriptionMethod

Configures the Adobe Mobile SDK setting to determine what kind of extension is currentlybeing executed.

setAppExtensionType

Set to one of the following values:

• ADBMobileAppExtensionTypeRegular - extension is bundled with a containing app

28Configuration

DescriptionMethod

• ADBMobileAppExtensionTypeStandAlone - extension is not bundled with a containingapp

Tip: This method should only be used if your app has an extension or is a stand-aloneextension. For more information, see ADBMobileAppExtensionType.

Syntax:+ (void) setAppExtensionType:(ADBMobileAppExtensionType)type;

Example:[ADBMobile setAppExtensionType:ADBMobileAppExtensionTypeStandAlone];

Returns the current version of the Adobe Mobile library.version

Syntax:+ (NSString *) version;

Example:NSString *libraryVersion = [ADBMobile version];

Returns the enum representation of the privacy status for current user:privacyStatus

• ADBMobilePrivacyStatusOptIn - hits are sent immediately.• ADBMobilePrivacyStatusOptOut - hits are discarded.• ADBMobilePrivacyStatusUnknown - If offline tracking is enabled, hits are saved until the

privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). Ifoffline tracking is not enabled, hits are discarded until the privacy status changes to opt in.

The default value is set in ADBMobileConfig.json.

Syntax:+ (ADBMobilePrivacyStatus) privacyStatus;

Example:ADBMobilePrivacyStatus privacyStatus = [ADBMobile privacyStatus];

Sets the privacy status for the current user to status.setPrivacyStatus:

Set to one of the following values:

• ADBMobilePrivacyStatusOptIn - hits are sent immediately.• ADBMobilePrivacyStatusOptOut - hits are discarded.• ADBMobilePrivacyStatusUnknown - If offline tracking is enabled, hits are saved until the

privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). Ifoffline tracking is not enabled, hits are discarded until the privacy status changes to opt in.

Syntax:+ (void) setPrivacyStatus:(ADBMobilePrivacyStatus)status;

29Configuration

DescriptionMethod

Example:[ADBMobile setPrivacyStatus:ADBMobilePrivacyStatusOptIn];

Returns the lifetime value of the current user.lifetimeValue

Default: 0

Syntax:+ (NSDecimalNumber *) lifetimeValue;

Example:NSDecimalNumber *lifeValue = [ADBMobile lifetimeValue];

Returns the automatically generated visitor identifier. This is an app-specific unique visitor IDthat is generated by Adobe’s servers. If Adobe's servers cannot be reached at the time of

trackingIdentifier

generation, then the ID is generated using Apple's CFUUID. The value is generated at the initiallaunch and is stored and used from that point forward. This ID is preserved between appupgrades, is saved and restored during the standard application backup process, and is removedat uninstall.

Tip: If your app upgrades from the Experience Cloud 3.x to the 4.x SDK, the previouscustom or automatically generated visitor ID is retrieved and stored as the custom useridentifier. For more information, see the userIdentifier row below.

This preserves visitor data between SDK upgrades. For new installations on the 4.x SDK, theuser identifier is nil and tracking identifier is used.

Syntax:+ (NSString *) trackingIdentifier;

Example:NSString *tid = [ADBMobile trackingIdentifier];

If a custom identifier has been set, the user identifier is returned. If a custom identifier is notset, nil is returned.

userIdentifier

Default: nil

Tip: If your app upgrades from the Experience Cloud 3.x to 4.x SDK, the previous customor automatically generated visitor ID 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, the user identifier is nil until set.

Syntax:+ (NSString *) userIdentifier;

Example:NSString *uid = [ADBMobile userIdentifier];

30Configuration

DescriptionMethod

Sets the user identifier to identifier.setUserIdentifier:

Syntax:+ (void) setUserIdentifier:(NSString *)identifier;

Example:[ADBMobile setUserIdentifier:@"billybob"];

Returns the current debug logging preference.debugLogging

Default: NO

Syntax:+ (BOOL) debugLogging;

Example:BOOL debugging = [ADBMobile debugLogging];

Sets the debug logging preference to debug.setDebugLogging:

Syntax:+ (void) setDebugLogging:(BOOL)debug;

Example:[ADBMobile setDebugLogging:YES];

Indicates to the SDK that your next resume from background should not start a new session,regardless of the value of lifecycle session timeout in your config file.

keepLifecycleSessionAlive

Tip: This method is intended to be used for apps that register for notifications while inbackground and should only be called from the code that runs while your app is in thebackground.

Syntax:+ (void) keepLifecycleSessionAlive;

Example:[ADBMobile keepLifecycleSessionAlive];

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

collectLifecycleData

Tip: The preferred location to invoke this method is inapplication:didFinishLaunchingWithOptions:

Syntax:+ (void) collectLifecycleData;

31Configuration

DescriptionMethod

Example:[ADBMobile collectLifecycleData];

collectLifecycleDataWithAdditionalData:Important: To use collectLifecycleDataWithAdditionalData:, you must haveSDK version 4.4 or later.

Allows you to pass in additional data when collecting lifecycle metrics.

Tip: This method must be called from the entry point of your app. Where applicable, thismay include one or both of the methodsapplication:didFinishLaunchingWithOptions: and/orapplicationWillEnterForeground: in your AppDelegate class.

Important: Data that is passed to the SDK viacollectLifecycleDataWithAdditionalData: will be persisted by the SDK inNSUserDefaults. The SDK will strip values in the NSDictionary parameter that arenot of type NSString or NSNumber.

Syntax:+ (void) collectLifecycleDataWithAdditionalData:(nullable NSDictionary *)data;

Example:[ADBMobile collectLifecycleDataWithAdditionalData:@{@"entryType":@"appShortcutIcon"}];

overrideConfigPathImportant: To use overrideConfigPath , you must have SDK version 4.2 or later.

Lets you load a different ADBMobile JSON config file when the application starts. The differentconfiguration is used until the application is closed.

Syntax:+ (void) overrideConfigPath: (nullable NSString *) path;

Example:NSString *filePath = [[NSBundle mainBundle] pathForResource:@"ExampleJSONFile" ofType:@"json"];[ADBMobile overrideConfigPath:filePath];

Sets the device token for push notifications.setPushIdentifier

Important: This method should only be used in theapplication:didRegisterForRemoteNotificationsWithDeviceToken:

method.

32Configuration

DescriptionMethod

Syntax:+ (void) setPushIdentifier:(NSData *)deviceToken;

Example:- (void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { [ADBMobile setPushIdentifier:deviceToken]; }

Sets the IDFA in the SDK. If the IDFA has been set in the SDK, the IDFA will be sent in lifecycle.It can also be accessed in Signals (Postbacks).

setAdvertisingIdentifier

Tip: Retrieve the IDFA from Apple APIs only if you are using an ad service. If you retrieveIDFA, and are not using it properly, your app might be rejected.

Syntax:+ (void) setAdvertisingIdentifier:(NSString *)identifier;

Example:NSString *idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];[ADBMobile setAdvertisingIdentifier:idfa];

ADBMobileAppExtensionType enum/** * @brief An enum type. * The possible types of app extension you might use * @see setAppExtensionType */typedef NS_ENUM(NSUInteger, ADBMobileAppExtensionType) { ADBMobileAppExtensionTypeRegular = 0, /*!< Enum value ADBMobileAppExtensionTypeRegular. */ ADBMobileAppExtensionTypeStandAlone = 1 /*!< Enum value ADBMobileAppExtensionTypeStandAlone. */};

App Transport Security

This information helps you work with App Transport Security (ATS), which is a new set of security requirements for iOS 9.

Starting with iOS 9, Apple introduced App Transport Security, a set of requirements that conforms to best practices for secureconnections. For the Adobe Mobile SDK version 4.7 or later to work seamlessly with ATS, use the enable SSL option in theManage App Settings page. For more information, see Manage App Settings or ADBMobile JSON Config.

In Adobe Mobile Services, by selecting the Use HTTPS option in the Manage App Settings page, all hits from Analytics,Audience Manager, Target, and Experience Cloud ID services are sent via HTTPS.

As an alternative, you can also choose to whitelist service the following servers:

33Configuration

https://developer.apple.com/library/prerelease/ios/technotes/App-Transport-Security-Technote/

https://marketing.adobe.com/resources/help/en_US/mobile/c_manage_app_settings.html

InstructionsProduct

To whitelist your Analytics server, add your tracking server domain to your info.plistfile as an exception domain for ATS.

Analytics

The tracking server domain can be found in the Analytics section of theADBMobileConfig.json file or in the Analytics section in the Manage App Settingspage.

Your Audience Manager domain is found in the server property of the audienceManagerobject in your ADBMobileConfig.json file.

Audience Manager

If you are using Audience Manager in your app, and SSL is not enabled, add this server as anexception domain for ATS in your Info.plist file

You can add your Target endpoint to your Info.plist file as an exception domain forATS.

Target

To find your Target endpoint, find the clientCodeproperty in the target object of yourADBMobileConfig.json file. Your endpoint will behttp://{clientCode}.tt.omtrdc.net.

For example, if your clientCodeproperty is “myCompany”, your endpoint will behttp://myCompany.tt.omtrdc.net.

You can add the Experience Cloud server as an exception domain for ATS in yourInfo.plist file. This domain is dpm.demdex.net.

Experience Cloud ID service

Whitelist the Acquisition server as an exception domain for ATS in your Info.plistfile. This domain is c00.adobe.com.

Mobile Services: Acquisition

If you are using in-app messages, you might need to add entries into the exception domainfor ATS for each URL you use that is not HTTPS. This list includes hosted images and anyURL embedded into your custom full screen message HTML.

Mobile Services: In-AppMessages

For more detail on setting up exceptions domain in a info.plist file, see the Exceptionssection on Apple’s App Transport Security Technote page.

Tip: These considerations affect the connections that are made by the Adobe Mobile SDK and do not impact web view orother connections that are made by your app.

34Configuration

https://developer.apple.com/library/prerelease/ios/technotes/App-Transport-Security-Technote/

Lifecycle MetricsThe following tables list the metrics and dimensions that can be automatically measured by the mobile library after lifecycle isimplemented.

This topic contains the following information:

• Lifecycle Metrics and Dimensions• Additional Mobile Metrics and Dimensions

Lifecycle Metrics and Dimensions

After lifecycle metrics are configured, the metrics are sent in context data parameters to Analytics, parameters to Target witheach mbox call, and as a signal to Audience Manager. Analytics and Target use the same format, while Audience Manager usesa different prefix for each metric.

For Analytics, the context data that is sent with each lifecycle tracking call is automatically captured in and reported by usingthe metric or dimension that listed in the first column.

Tip: Exceptions are provided 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 upgrade or anytimethe 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.

35Lifecycle Metrics

DescriptionAudience Manager SignalAnalytics ContextData/Target Parameter

Metric

Triggered on every run, including crashes andinstalls. Also triggered when the app is resumed

c_a_LaunchEventa.LaunchEventLaunches

from the background after the lifecycle sessiontimeout is exceeded.

Triggered when the application is notbackgrounded before closing. The event is sent

c_a_CrashEventa.CrashEventCrashes

when the application is started again after thecrash.

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. MM/DD/YYYYc_a_InstallDatea.InstallDateInstall Date

Stores the Application name and version in thefollowing format:

c_a_AppIDa.AppIDApp ID

[AppName] [BundleVersion]

For example, myapp 1.1

Number of times the application was launched orbrought out of the background.

c_a_Launchesa.LaunchesLaunch Number

Number of days since first run.c_a_DaysSinceFirstUsea.DaysSinceFirstUseDays since first use

Number of days since last use.c_a_DaysSinceLastUsea.DaysSinceLastUseDays since last use

Measures the hour the app was launched and usesthe 24-hour numerical format. Used for time partingto determine peak usage times.

c_a_HourOfDaya.HourOfDayHour of Day

Number of the week day the app was launched.c_a_DayOfWeeka.DayOfWeekDay of Week

36Lifecycle 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


Stores the device name.c_a_DeviceNamea.DeviceNameDevice Name

Comma-separated two-digit string that identifiesthe iOS device. The first number typically representsthe device generation, and the second numbertypically versions different members of the devicefamily. For a list of common device names, see iOSDevice Versions.

Stores the name of the mobile service provider asprovided by the device.

c_a_CarrierNamea.CarrierNameCarrier Name


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.

37Lifecycle Metrics

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

Populated by trackLifetimeValue methods.c_a_ltv_amounta.ltv.amountLifetime Value(event)

Dimensions

DescriptionAudience ManagementTrait


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 in a defined POI.

c_a_loc_poia.loc.poiPoint of InterestName

Populated by trackLocation methods whendevice is in 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. Generatedautomatically 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

38Lifecycle Metrics

DescriptionAudience ManagementTrait


Dimension

Marketing medium, such as banner or email.Populated by Mobile App Acquisition.

c_a_referrer_campaign_mediuma.referrer.campaign.mediumCampaign Medium

Original referrer, such as newsletter or social medianetwork. Populated by Mobile App Acquisition.

c_a_referrer_campaign_sourcea.referrer.campaign.sourceCampaign Source

Paid keywords or other terms you want to trackwith this acquisition. Populated by Mobile AppAcquisition.

c_a_referrer_campaign_terma.referrer.campaign.termCampaign Term

39Lifecycle Metrics

AnalyticsThis information helps you use the iOS 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 track state call should be sent. In iOS, a state is typically trackedin the viewDidLoad method of each view.

Tip: To track states, make a call to trackState. States are not automatically tracked.

Tracking States

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

#import "ADBMobile.h"

3. Call trackState to send a hit for this state view.

[ADBMobile trackState:@"Login Screen" data:nil];

In Adobe Mobile services, the State Name is reported in the View State variable, and a view is recorded for each trackStatecall. 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:NSMutableDictionary *contextData = [NSMutableDictionary dictionary];[contextData setObject:@"logged in" forKey:@"myapp.login.LoginStatus"];[ADBMobile trackState:@"Home Screen" data:contextData];

Context data values must be mapped to custom variables in Adobe Mobile services:

App State Reporting

States are typically viewed by using a pathing report so you can see how users navigate your app and which states are viewedmost.

40Analytics

https://mobilemarketing.adobe.com

The View States report.Adobe MobileServices

This report is based on the paths that the users took through your application. For example, after you log in,click 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 using the Pagedimension, Page Views metric, and Pathreports.

Ad hocanalytics

Track App Actions

Actions are the events that occur in your app that you want to measure. Each action has one or more corresponding metricsthat are incremented each time the event occurs. For example, you might track a new subscription, each time an article is viewedor each time a level is completed. The corresponding metrics for these events are configured as subscriptions, articles read, andlevels completed.

Actions are not tracked automatically, so to track an event, you must call trackAction.

Tracking Actions

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


3. When the action that you want to track occurs in your app, call trackAction to send a hit for this action.

[ADBMobile trackAction:@"myapp.ActionName" data:nil];

Tip: If the code where you are adding this call might run while the app is in the background, calltrackActionFromBackground instead of trackAction.

4. In Adobe Mobile services, select your app and click Manage App Settings.5. Click Manage Variables and Metrics and click the Custom Metrics tab.6. Map the context data name that is defined in your code (for example, a.action=myapp.ActionName to a custom event.

41Analytics

https://mobilemarketing.adobe.com/

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.


In addition to the action name, you can send additional context data with each track action call:NSMutableDictionary *contextData = [NSMutableDictionary dictionary];[contextData setObject:@"Twitter" forKey:@"myapp.social.SocialSource"];[ADBMobile trackAction:@"myapp.SocialShare" data:contextData];


Tracking Background Actions

If you are tracking an action in code that might run when the app is in the background, call trackActionFromBackgroundinstead of trackAction. Although trackActionFromBackground contains some additional logic to prevent lifecycle callsfrom firing when they should not, the parameters are the same.

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 to view actions ranked, trended, or in a breakdownreport or apply a filter to view actions for a specific segment.

42Analytics

ReportInterface

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.

Important: You should upgrade to iOS SDK version 4.8.6, which contains critical changes that prevent false crashes frombeing reported.

When does Adobe report a crash?

If your application is terminated without having first been backgrounded, the SDK reports a crash the next time your app islaunched.

How does crash reporting work?

iOS uses system notifications that allow developers to track and respond to different states and events in the application lifecycle.

The AdobeMobile iOS SDK has a notification handler that responds to theUIApplicationDidEnterBackgroundNotification notification. In this code, a value is set that indicates that the userhas backgrounded the app. On a subsequent launch, if that value cannot be found, a crash is reported.

Why does Adobe measure crashes this way?

This approach of measuring crashes provides a high-level answer to the question, Did the user exit my app intentionally?

Crash reporting libraries provided by companies like Apteligent (formerly Crittercism) use a global NSException handler toprovide more detailed crash reporting. Your app is not allowed to have more than one of these kind of handlers. Adobe decidedto not implement a global NSException handler to prevent build errors, knowing that our customers might be using othercrash reporting providers.

What can cause a false crash to be reported?

The following scenarios are known to falsely cause a crash to be reported by the SDK:

1. If you are debugging using Xcode, launching the app again while it is in the foreground, causes a crash.

Tip: You can avoid a crash in this scenario by backgrounding the app before launching the app again from Xcode.

2. If your app is in the background and sends Analytics hits through a call other than trackActionFromBackground,trackLocation, or trackBeacon, and the app is terminated (manually or by the OS) while in the background, and thenext launch will be a crash.

43Analytics

Tip: Background activity that occurs beyond the lifecycleTimeout threshold might also result in an additional falselaunch.

3. If your app is launched in the background because of a background fetch, location update, and so on, and is terminated bythe OS without coming to the foreground, the next launch (background or foreground) results in a crash.

4. If you programmatically delete Adobe’s pause flag from NSUserDefaults, while the app is in the background, the nextlaunch or resume causes a crash.

How can I prevent false crashes from being reported?

The following practices can help you prevent false crashes from being reported:

• In iOS SDK 4.8.6, code was added to better determine whether a new lifecycle session is actually wanted.

This code fixes false crashes #2 and #3 in the previous section.

• Ensure that you perform your development against non-production report suites, which should prevent false crash #1 fromoccurring.

• Do not delete or modify any values that the AdobeMobile SDK puts in NSUserDefaults.

If these values are modified outside the SDK, the data reported will be invalid.

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 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.

Tracking Timed Actions

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


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

[ADBMobile trackTimedActionStart:@"TimeUntilPurchase" data:@{@"ExperienceName" : experience}];

4. (Optional) To add additional context data at any time, you can call trackTimedActionUpdate with the timed actionname.

[ADBMobile trackTimedActionUpdate:@"TimeUntilPurchase" data:@{@"myapp.ImageLiked" : imageName}];

44Analytics

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.

Timed event metrics are saved in mobile solution variables for automatic reporting.[ADBMobile trackTimedActionEnd:@"TimeUntilPurchase" logic:nil];


In addition to the timed action name, you can send additional context data with the action start and action update calls:[ADBMobile trackTimedActionUpdate:@"TimeUntilPurchase" data:@{@"myapp.ImageLiked" : imageName}];


Examples// Timed Action Start Example[ADBMobile trackTimedActionStart:@"TimeUntilPurchase" data:@{@"ExperienceName" : experience}];

// Timed Action Update Example[ADBMobile trackTimedActionUpdate:@"TimeUntilPurchase" data:@{@"ImageLiked" : imageName}];

// Timed Action End Example[ADBMobile trackTimedActionEnd:@"TimeUntilPurchase" logic:nil];

// Timed Action End Example with Callback[ADBMobile trackTimedActionEnd:@"TimeUntilPurchase" logic:^BOOL(NSTimeInterval inAppDuration, NSTimeInterval totalDuration, NSMutableDictionary *data) { [data setObject:@"PurchaseItem" forKey:@"Item453"]; return YES; //return YES to send the hit, NO to cancel

}];

Visitor Lifetime Value

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

45Analytics


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. This can be used to store lifetime purchases,ad views, video completes, social shares, photo uploads, and so on.

How to Track


import com.adobe.mobile.*;

3. Call trackLifetimeValueIncrease with the amount to increase the value:[ADBMobile trackLifetimeValueIncrease:increaseAmount data:nil];


In addition to the lifetime value, you can send additional context data with each track action call:NSMutableDictionary *contextData = [NSMutableDictionary dictionary];[contextData setObject:imageName forKey:@"myapp.ImageLiked"];[ADBMobile trackLifetimeValueIncrease:increaseAmount data:contextData];


Products Variable

The products variable cannot be set by using processing rules. In the iOS 4.x SDK, you must use a special syntax in the contextdata 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 by using the syntax that is defined forthe products variable:[contextData setObject:@"Category;Product;Quantity;Price[,Category;Product;Quantity;Price]" forKey:@"&&products"];

For example://create a context data dictionaryNSMutableDictionary *contextData = [NSMutableDictionary dictionary];

// add products, a purchase id, a purchase context data key, and any other data you want to collect.// Note the special syntax for products[contextData setObject:@";Running Shoes;1;69.95,;Running Socks;10;29.99" forKey:@"&&products"];[contextData setObject:@"1234567890" forKey:@"m.purchaseid"];

46Analytics


http://microsite.omniture.com/t2/help/en_US/sc/implement/?f=c_products

[contextData setObject:@"1" forKey:@"m.purchase"];

// send the tracking call - use either a trackAction or TrackState call.// trackAction example:[ADBMobile trackAction:@"purchase" data:contextData];// trackState example:[ADBMobile trackState:@"Order Confirmation" data:contextData];

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

All context data variables must be mapped by using processing rules:

You do not need to map the products variable using processing rules because it is set directly on the image request by 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 dictionaryNSMutableDictionary *contextData = [NSMutableDictionary dictionary];

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

47Analytics

collect.// Note the special syntax for products[contextData setObject:@"event1" forKey:@"&&events"];[contextData setObject:@";Running Shoes;1;69.95;event1=5.5;eVar1=Merchandising,;Running Socks;10;29.99" forKey:@"&&products"];[contextData setObject:@"1234567890" forKey:@"m.purchaseid"];[contextData setObject:@"1" forKey:@"m.purchase"];

// send the tracking call - use either a trackAction or TrackState call.// trackAction example:[ADBMobile trackAction:@"purchase" data:contextData];// trackState example:[ADBMobile trackState:@"Order Confirmation" data:contextData];

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.[contextData setObject:@"eventN:serial number" forKey:@"&&events"];

For example://create a context data dictionaryNSMutableDictionary *contextData = [NSMutableDictionary dictionary];

// add events[contextData setObject:@"event1:12341234" forKey:@"&&events"];

// send the tracking call - use either a trackAction or TrackState call.// trackAction example:[ADBMobile trackAction:@"action" data:contextData];// trackState example:[ADBMobile trackState:@"State Name" data:contextData];

Video Analytics

Here is some information about measuring video on iOS by using milestone video measurement.

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, see Measuring Video in Adobe Analytics using Video Heartbeat.

The general process to measure video is very similar across all platforms. This content provides a basic overview of the developertasks with code samples.


• Map Player Events to Analytics Variables• Configure Media Settings• Track Player Events• Classes• Media Measurement Class and Method Reference

48Analytics

https://marketing.adobe.com/resources/help/en_US/sc/appmeasurement/hbvideo/

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 ContextData Variable column to an Analytics variable as described in the Variable Type column.

DescriptionVariable TypeContext Data Variable

(Required) Collects the name of the video, as specified in theimplementation, 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 forvideo pathing)

a.media.name

(Optional) The Custom Insight variable provides video pathinginformation.

(Optional) Provides video pathing information. Pathing mustbe 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 segmentname 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 thesegmentByMilestones variable when tracking player eventsautomatically, or by setting a custom segment name whentracking 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 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.

eVar

Default expiration: Page view

a.contentType

This variable does not need to be reserved exclusively for videotracking. Having other content report content type by using thissame variable lets you analyze the distribution of visitors acrossthe different types of content. For example, you could tag other

49Analytics

DescriptionVariable TypeContext Data Variable

content types using values such as “article" or “product page"using this variable.

From a video measurement perspective, Content Type allowsyou to identify video visitors and calculate video conversionrates.

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

Event

Type: Counter

a.media.timePlayed

Indicates that a visitor has viewed some portion of a video.Eventa.media.view

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

Type: Counter

Indicates that a visitor has viewed some portion of a videosegment.

Event

Type: Counter

a.media.segmentView

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

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

Event

Type: Counter

.media.complete

During implementation, you can specify how many secondsfrom the end of the video you would like to consider a viewcomplete. For live video and other streams that do not have adefined end, you can specify a custom point to measurecompletes, for example, after a specific time viewed.

Configure Media Settings

Configure an ADBMediaSettings object with the settings you want to use to track video:ADBMediaSettings *mediaSettings = [ADBMobile mediaCreateSettingsWithName:MEDIA_NAME length:MEDIA_LENGTH playerName:PLAYER_NAME playerID:PLAYER_ID];

// milestone tracking. Use either standard milestones (percentage of total length)// or offset milestones (seconds elapsed from the beginning of the video)mediaSettings.milestones = @"25,50,75";mediaSettings.segmentByMilestones = YES;

mediaSettings.offsetMilestones = @"60,120";mediaSettings.segmentByOffsetMilestones = YES;

// seconds tracking - sends a hit every x secondsmediaSettings.trackSeconds = 30; // sends a hit every 30 seconds

// open the video[ADBMobile mediaOpenWithSettings:mediaSettings callback:nil];

// You are now ready to play the video, for example, [movieViewController.moviePlayer play];

50Analytics

// Note the the mediaPlay, mediaStop and mediaClose methods are called in the// event handlers described in the next section

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.

The following example demonstrates configuring notifications and calling the media methods to measure video:// configure notifications for when the video is finished, and when themedia playback state changes

- (void) configureNotifications:(MPMoviePlayerController *) movieController { [[NSNotificationCenter defaultCenter] addObserver: self selector: @selector(mediaFinishedCallback:) name: MPMoviePlayerPlaybackDidFinishNotification object: movieController];

[[NSNotificationCenter defaultCenter] addObserver: self selector: @selector(mediaPlaybackChangedCallback:) name: MPMoviePlayerPlaybackStateDidChangeNotification object: movieController];}

// define your notification callbacks.

- (void) mediaFinishedCallback: (NSNotification*) notification { [ADBMobile mediaClose:MEDIA_NAME];}

- (void) mediaPlaybackChangedCallback: (NSNotification*) notification { MPMoviePlayerController *mediaController = notification.object; if (mediaController.playbackState == MPMoviePlaybackStatePlaying) { [ADBMobile mediaPlay:MEDIA_NAME offset: isnan(mediaController.currentPlaybackTime) ? 0.0 : mediaController.currentPlaybackTime]; } else if (mediaController.playbackState == MPMoviePlaybackStateSeekingBackward) { [ADBMobile mediaStop:MEDIA_NAME offset:mediaController.currentPlaybackTime]; } else if (mediaController.playbackState == MPMoviePlaybackStateSeekingForward) { [ADBMobile mediaStop:MEDIA_NAME offset:mediaController.currentPlaybackTime]; } else if (mediaController.playbackState == MPMoviePlaybackStatePaused) { [ADBMobile mediaStop:MEDIA_NAME offset:mediaController.currentPlaybackTime]; } else if (mediaController.playbackState == MPMoviePlaybackStateInterrupted) { [ADBMobile mediaStop:MEDIA_NAME offset:mediaController.currentPlaybackTime]; } else if (mediaController.playbackState == MPMoviePlaybackStateStopped) { [ADBMobile mediaStop:MEDIA_NAME offset:mediaController.currentPlaybackTime]; }}

Classes

Class: ADBMediaSettingsbool segmentByMilestones;bool segmentByOffsetMilestones;double length;NSString *channel;NSString *name;NSString *playerName;NSString *playerID;NSString *milestones;NSString *offsetMilestones;

51Analytics

NSUInteger trackSeconds;NSUInteger completeCloseOffsetThreshold;// settings used for ad tracking. For bool isMediaAd;double parentPodPosition;NSString *CPM;NSString *parentName;NSString *parentPod;

Class: ADBMediaStatebool ad;bool clicked;bool complete;bool eventFirstTime;double length;double offset;double percent;double segmentLength;double timePlayed;double timePlayedSinceTrack;double timestamp;NSDate *openTime NSString *nameNSString *playerNameNSString *mediaEventNSString *segmentNSUInteger milestoneNSUInteger offsetMilestoneNSUInteger segmentNumNSUInteger eventType

Media Measurement Class and Method Reference

DescriptionMethod

Returns an ADBMediaSettings object with specified parameters.mediaCreateSettingsWithName:length:playerName:playerID: Syntax:

+ (ADBMediaSettings *) mediaCreateSettingsWithName:(NSString *)name length:(double)length playerName:(NSString *)playerName

playerID:(NSString *)playerID;

Example:ADBMediaSettings *myCatSettings = [ADBMobile mediaCreateSettingsWithName:@"catVideo" length:85 playerName:@"catVideoPlayer" playerID:@"catPlayerId"];

Returns an ADBMediaSettings object for use with tracking an ad video.mediaAdCreateSettingsWithName:length:

Syntax:+ (ADBMediaSettings *) mediaAdCreateSettingsWithName:(NSString *)name length:(double)length

playerName:parentName:parentPod:parentPodPosition:CPM:

playerName:(NSString *)playerName

parentName:(NSString *)parentName

parentPod:(NSString *)parentPod

52Analytics

DescriptionMethodparentPodPosition:(double)parentPodPosition CPM:(NSString *)CPM;

Example:ADBMediaSettings *mySettings = [ADBMobile mediaAdCreateSettingsWithName:@"ad" length:30 playerName:@"adPlayer" parentName:@"catVideo" parentPod:@"catCollection" parentPodPosition:2 CPM:nil];

Opens an ADBMediaSettings object for tracking.mediaOpenWithSettings:callback:

Syntax:+ (void) mediaOpenWithSettings:(ADBMediaSettings *)settings callback:(void (^)(ADBMediaState *mediaState))callback;

Example:[ADBMobile mediaOpenWithSettings:mySettings callback:^(ADBMediaState *mediaState) { // do something with media state if you want}];

Closes the media item named name.mediaClose:

Syntax:+ (void) mediaClose:(NSString *)name;

Example:[ADBMobile mediaClose:@"kittiesPlaying"];

Plays the media item named name at the given offset (in seconds).mediaPlay:offset:

Syntax:+ (void) mediaPlay:(NSString *)name offset:(double)offset;

Example:[ADBMobile mediaPlay:@"cats" offset:25];

Manually mark the media item as complete at the offset provided (in seconds).mediaComplete:offset:

Syntax:+ (void) mediaComplete:(NSString *)name offset:(double)offset;

Example:[ADBMobile mediaComplete:@"meowzah" offset:90];

Notifies the media module that the video has been stopped or paused at the given offset.mediaStop:offset:

53Analytics

DescriptionMethod

Syntax:+ (void) mediaStop:(NSString *)name offset:(double)offset;

Example:[ADBMobile mediaStop:@"toonses" offset:30];

Notifies the media module that the media item has been clicked.mediaClick:offset:

Syntax:+ (void) mediaClick:(NSString *)name offset:(double)offset;

Example:[ADBMobile mediaClick:@"soManyCats" offset:47];

Sends a track action call (no page view) for the current media state.mediaTrack:withData:

Syntax:+ (void) mediaTrack:(NSString *)name withData:(NSDictionary *)data;

Example:

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 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 thestandard Lifecycle variables list, in addition to any custom data attached to the hit that triggers the message. No historical-basedor 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 DescriptionToken Name

Returns SDK version.{%sdkver%}

Resolves to a random number between 1 and 100000000.{%cachebust%}

54Analytics

https://marketing.adobe.com/resources/help/en_US/mobile/ios/metrics.html

Token DescriptionToken Name

Returns IDFA. Note, this only works if you have used setAdvertisingIdentifier.{%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%}

Postback 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 theAdobe Mobile UI and should not be manually modified. A manually edited configuration file can be dangerous when you haveremote messages configuration enabled.


• ADBMobileConfig.json Definition• Code Sample

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 SampleNSDictionary *contextData = @{@"user.name":@"bob", @"user.zip":@"90210"};[ADBMobile trackState:@"MainMenu" data:contextData];

55Analytics

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 iOS SDKversion 4.6.0, the resulting URL would look like this:

http://my.server.com/?user=bob&zip=90210&c16=4.6.0-iOS&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 any 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



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 iOS library.

The SDK currently has support for multiple Adobe Experience Cloud Solutions, including Analytics, Target, Audience Manager,and the Experience Cloud ID service. Methods are prefixed according to the solution. Experience Cloud ID methods are prefixedwith track.

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

DescriptionMethod

States are the views that are available in your app, such as home dashboard, appsettings, cart, and so on. These states are similar to pages on a website, andtrackState calls increment page views.

trackState:data:

If state is empty, it displays as app name app version (build) in reports. If you see thisvalue in reports, ensure you are setting state in each trackState call.

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

Syntax:+ (void) trackState:(NSString *)state data:(NSDictionary *)data;

56Analytics

https://marketing.adobe.com/resources/help/en_US/mobile/ios/dev_qs.html

DescriptionMethod

Example:[ADBMobile trackState:@"loginScreen" data:nil];

Tracks an action in your app.trackAction:data:

Actions that you want to measure, such as logons, banner taps, feed subscriptions,and other metrics, occur in your app.

Tip: If you have code that might run while the app is in the background (for example,a background data retrieval), use trackActionFromBackground instead.

Syntax:+ (void) trackAction:(NSString *)action data:(NSDictionary *)data;

Example:[ADBMobile trackAction:@"heroBannerTouched" data:nil];

Retrieves the analytics tracking identifier.trackingIdentifier

Syntax:+ (NSString *) trackingIdentifier;

Example:NSString *trackingId = [ADBMobile trackingIdentifier];

Tracks an action that occurred in the background, which suppresses lifecycle events fromfiring in certain scenarios.

trackActionFromBackground:data:

Tip: This method should only be called in code that runs while your app is in thebackground.

Syntax:+ (void) trackActionFromBackground:(NSString *)action data:(NSDictionary *)data;

Example:[ADBMobile trackActionFromBackground:@"downloadedUpdate" data:nil];

Sends the current x y coordinates.trackLocation:data:

Also uses points of interest that are defined in the ADBMobileConfig.json file todetermine if the location provided as a parameter is in any of your POIs. If the currentcoordinates are in a defined POI, a context data variable is populated and sent with thetrackLocation call.

57Analytics

DescriptionMethod

Syntax:+ (void) trackLocation:(CLLocation *)location data:(NSDictionary *)data;

Example:[ADBMobile trackLocation:userLocation data:nil];

Tracks when a users enters proximity of a beacon.trackBeacon:data:

Syntax:+ (void) trackLocation:(CLBeacon *)beacon data:(NSDictionary *)data;

Example:[ADBMobile trackBeacon:beacon data:nil];

Clears beacons data after a user leaves the proximity of the beacon.trackingClearCurrentBeacon

Syntax:+ (void) trackingClearCurrentBeacon;

Example:[ADBMobile trackingClearCurrentBeacon];

Adds amount to the user's lifetime value.trackLifetimeValueIncrease:data:

Syntax:+ (void) trackLifetimeValueIncrease:(NSDecimalNumber *)amount data:(NSDictionary *)data;

Example:[ADBMobile trackLifetimeValueIncrease:30 data:nil];

Start a timed action with name action.trackTimedActionStart:data:

If you call this method for an action that has already started, the previous timed action isoverwritten.

Tip: This call does not send a hit.

Syntax:+ (void) trackTimedActionStart:(NSString *)action data:(NSDictionary *)data;

Example:[ADBMobile trackTimedActionStart:@"cartToCheckout" data:nil];

58Analytics

DescriptionMethod

Pass in data to update the context data associated with the given action.trackTimedActionUpdate:data:

The data that is passed in is appended to the existing data for the action, and if the samekey is already defined for action, overwrites the data.


Syntax:+ (void) trackTimedActionUpdate:(NSString *)action data:(NSDictionary *)data;

Example:[ADBMobile trackTimedActionUpdate:@"cartToCheckout" data:@{@"quantity":@"3"}];

End a timed action.trackTimedActionEnd:logic:

If you provide block, you will have access to the final time values and be able to manipulatedata prior to sending the final hit.

Tip: If you provide block, you must return YES to send a hit. Passing in nil forblock sends the final hit.

Syntax:+ (void) trackTimedActionEnd:(NSString *)action logic:(BOOL (^) (NSTimeInterval inAppDuration, NSTimeInterval totalDuration, NSMutableDictionary *data))block;

Example:[ADBMobile trackTimedActionEnd:@"cartToCheckout" logic:^(NSTimeInterval inApp, NSTimeInterval total, NSMutableDictionary *data) { data[@"price"] = @"49.95"; return YES; }];

Returns whether a timed action is in progress.trackingTimedActionExists

Syntax:+ (BOOL) trackingTimedActionExists:(NSString *)action;

Example:BOOL *actionExists = [ADBMobile trackingTimedActionExists];

Requires SDK 4.1trackingSendQueuedHits

Regardless of how many hits are currently queued, forces the library to send all hits in theoffline queue.

59Analytics

DescriptionMethod

Syntax:+ (void) trackingSendQueuedHits;

Example:[ADBMobile trackingSendQueuedHits];

Retrieves the number of hits currently in the offline queue.trackingGetQueueSize

Syntax:+ (NSUInteger) trackingGetQueueSize;

Example:NSUInteger *queueSize = [ADBMobile trackingGetQueueSize];

Clears all hits from the offline queue.trackingClearQueue

Syntax:+ (void) trackingClearQueue;

Example:[ADBMobile trackingClearQueue];

: Use caution when clearing the queue manually. This process cannot be reversed.

Tracks a push message click-through.trackPushMessageClickThrough

Important: This method does not increment page views.

Syntax:+ (void) trackPushMessageClickThrough:(NSDictionary *)userInfo;

Example:- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { // only send the hit if the app is not active if (application.applicationState != UIApplicationStateActive) { [ADBMobile trackPushMessageClickThrough:userInfo]; } completionHandler(UIBackgroundFetchResultNoData);}

60Analytics

AcquisitionThis information helps you use acquisition tracking links in your in your iOS 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 Apple App Store after clicking on the generated link, the SDK automatically collects and sends the acquisitiondata to Adobe Mobile services.

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.

The updates described in this section enable the SDK to send acquisition data from an acquisition link.

Tracking Mobile App Acquisition



3. 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, acquisition data is sent automatically with the initial lifecycle call after the initial launch of theapp.

: referrerTimeout must be set to a value higher than 0 to enable app acquisition.

Acquisition Methods

The following Acquisition methods are provided by the iOS library:

The following methods are supported:

61Acquisition

https://marketing.adobe.com/resources/help/en_US/mobile/?f=acquisition


DescriptionMethod

Allows developers to start an app acquisition campaign as if the user had clicked alink. This is helpful for creating manual acquisition links and handling the app storeredirect yourself, such as with an SKStoreView.

acquisitionCampaignStartForApp:data:

Syntax:+ (void) acquisitionCampaignStartForApp:(NSString *)appId data:(NSDictionary *)data;

Example: [ADBMobile acquisitionCampaignStartForApp:@"0652024f-adcd-49f9-9bd7-2552a4564d2f" data:@{@"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 iOS SDK.

For more information about how marketers use deep linking in their applications, see Acquisition in the Adobe Mobile Servicesdocumentation.


• 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 Inter-App Communications or Support Universal Links.3. Track deep link in openURL.

Here is a sample track deep link:- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url { [ADBMobile trackAdobeDeepLink:url]; /* Handle deep link */

return YES;}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options { [ADBMobile trackAdobeDeepLink:url]; /* Handle deep link */

return YES;}

62Acquisition

https://marketing.adobe.com/resources/help/en_US/mobile/index.html?f=acquisition_main

https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter-AppCommunication.html#//apple_ref/doc/uid/TP40007072-CH6-SW10

https://developer.apple.com/library/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html

The Adobe Mobile SDK can parse key and value pairs of data appended to any deep or universal link, provided that the linkcontains a key with a a.deeplink.id label and a corresponding non-null and user generated value. All key and value pairs ofdata that are appended to the link will be parsed, attached to a lifecycle hit, and sent to Adobe Analytics, provided the linkcontains the a.deeplink.id key and value.

Additionally, you might also choose to append one or more of the following reserved keys (with user-generated values) to thedeep or universal link:

• a.launch.campaign.trackingcode• 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

1. Register Adobe data callback.[ADBMobile registerAdobeDataCallback:^(ADBMobileDataEvent event, NSDictionary * _Nullable adobeData) {}];

2. Handle ADBMobileDataEventDeepLink within AdobeDataCallback.[ADBMobile registerAdobeDataCallback:^(ADBMobileDataEvent event, NSDictionary * _Nullable adobeData) { if (event == ADBMobileDataEventDeepLink) { [self handleDeepLink:adobeData[ADBConfigKeyCallbackDeepLink]]; }}];

Deep Link Public Information

Methods/** * @brief Tracks a Adobe Deep Link click-through * @param url The URL resource received from UIApplication delegate method. * @note Adobe Link data will be appended to the lifecycle call if it is a launch event, otherwise an extra call will be sent. */+ (void) trackAdobeDeepLink:(nullable NSURL *)url;

Constants/* * Used within ADBMobileDataCallback * Key for deep link URL. */FOUNDATION_EXPORT NSString *const __nonnull ADBConfigKeyCallbackDeepLink;

Tracking Third-Party Deferred Deep Links

Use the iOS SDK to implement tracking of third-party deferred deep links.


• Classic Adobe Mobile SDK Deep Linking• Facebook Deep Linking

63Acquisition

• Setting up the SDKs• Enable Feature in Sample Application

Classic Adobe Mobile SDK Deep Linking

The Adobe Mobile SDK currently supports deep linking where the app developer is expected to call the trackAdobeDeepLinkAPI and pass the deep linking URL (fingerprinter URL generated in Adobe Mobile Services during configuration). The SDKpings the fingerprinter to get acquisition data and appends it to the install/launch analytics calls context data as a part of lifecycle.In addition, it also appends the deeplink data from the deeplink URL parameters. For more information on deep linking, seeTracking Deep Links.

Facebook Deep Linking

An ad creator can create an ad on Facebook as a deep link. When users click the ad on Facebook, it goes directly to the informationin which they are interested in the app. The deep link, is not a fingerprinter URL. However, during ad configuration, there isan option to provide a third-party deep link URL. An app developer who is using the Experience Cloud Mobile SDKs and servicesis expected to enter the Mobile Services configured fingerprinter URL in this field. If everything is set up correctly, the FacebookSDK passes this URL to the application when the app is installed or launched.

Setting up the SDKs

1. Set up the Facebook SDK:

• Getting Started with the Facebook SDK for iOS

• Deeplinking Setup

2. Set up the Adobe Mobile SDK:

Call trackAdobeDeepLink and pass the URL to AMSDK:- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{ [ADBMobile trackAdobeDeepLink:url]; return YES;}

Tip: Ensure that the deep link URL has a key with the name a.deeplink.id. No URL parameters will be appendedto the context data if the URL missed the a.deeplink.id parameter.

If the application is set up as described above, the current AMSDK version will work fine and append the deep link data toinstall/launch analytics calls correctly.

Enable Feature in Sample Application

1. Register a URL scheme.

Ensure that you registered a URL scheme, which is the same as the deep link URL.<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>sampleapptest</string> </array> </dict> </array>

64Acquisition

https://marketing.adobe.com/resources/help/en_US/mobile/ios/tracking-deep-links.html

https://developers.facebook.com/docs/ios/getting-started

https://developers.facebook.com/docs/app-ads/deep-linking#os

2. Link the Facebook SDKs.

3. Edit AppDelegate.

a. Import the headers./*************************************************************************ADOBE SYSTEMS INCORPORATEDCopyright 2015 Adobe Systems IncorporatedAll Rights Reserved.NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with theterms of the Adobe license agreement accompanying it. If you have received this file from asource other than Adobe, then your use, modification, or distribution of it requires the priorwritten permission of Adobe.

**************************************************************************/

#import "AppDelegate.h"#import "GalleryViewController.h"#import "SimpleTrackingController.h"#import "PostbackController.h"#import "InAppMessageViewController.h"#import "LifetimeValueController.h"#import "LocationTargetingController.h"#import "MediaViewController.h"#import "TimedActionController.h"

// Uncomment after including the facebook sdks.@import FBSDKCoreKit;@import Bolts;

b. Add handle for deferred deep linking.- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { /* * Adobe Tracking - Analytics * * turn on debug logging for the ADBMobile SDK * enable the collection of lifecycle data */

65Acquisition

if (launchOptions[UIApplicationLaunchOptionsURLKey] == nil) { if (NSClassFromString(@"FBSDKAppLinkUtility") != nil) { [NSClassFromString(@"FBSDKAppLinkUtility") performSelector:@selector(fetchDeferredAppLink:) withObject:^(NSURL *url, NSError *error) { if (error) { NSLog(@"Received error while fetching deferred app link %@", error); } if (url) { [[UIApplication sharedApplication] openURL:url]; } }]; } } ..... ..... return YES;}

c. Call trackAdobeDeepLink API and pass the deep link URL to AMSDK.- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options { [self handleDeepLink:url];

return YES;}

Testing Marketing Link Acquisition

The following instructions help you roundtrip an acquisition campaign with a marketing link that is based on a device fingerprint.

1. Complete the prerequisite tasks in Mobile App Acquisition.2. In the Adobe Mobile Services UI, click Marketing Links Builder and generate an acquisition marketing link URL that sets

the App Store as the destination for iOS devices.

For more information, see Marketing Links Builder.

For example:https://c00.adobe.com/v3/da120731d6c09658b82d8fac78da1d5fc2d09c48e21b3a55f9e2d7344e08425d/start?a_dl=57477650072932ec6d3a470f

3. Open the generated link on the iOS device and open http://c00.adobe.com/v3/<appid>/end.

You should see the contextData in the JSON response:{"fingerprint":"bae91bb778f0ad52e37f0892961d06ac6a5c935b","endCallbacks":["***"],"timestamp":1464301217,"appguid":"da120731d6c09658b82d8fac78da1d5fc2d09c48e21b3a55f9e2d7344e08425d","contextData":{"a.launch.campaign.trackingcode":"twdf4546","a.referrer.campaign.name":"iOS Demo","a.referrer.campaign.trackingcode":"twdf4546"},"adobeData":{"unique_id":"8c14098d7c79e8a180c15e4b2403549d3cc21ea8","deeplinkid":"57477650072932ec6d3a470f"}}

4. 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.

66Acquisition

https://marketing.adobe.com/resources/help/en_US/mobile/index.html?f=c_marketing-links-builder

ValueSetting

referrerTimeout should have a value greater than 0.analytics

5. (Conditional) If the SSL setting in your app's config file is false, update your acquisition link to use the HTTP protocolinstead of HTTPS.

6. Click the generated link from the mobile device on which you want to install the app.

Adobe's servers (c00.adobe.com) store the fingerprint and redirect to the App Store. The app does not need to bedownloaded for testing.

7. Launch the application for the first time from the same mobile device that you used in step 6.

You can delete and install the app again, if necessary.

8. (Optional) Enable debug logging of the SDK to obtain additional information.

If everything works correctly, you should see following logs:"Analytics - Trying to fetch referrer data from <acquisition end url>""Analytics - Received Referrer Data(<Json Object>)"

If you do not see the above logs, verify that you completed steps 4 and 5.

The following table contains information about possible errors:

DescriptionError

A network error occurred.Analytics - Unable to retrieve

acquisition service response (<error

message>)

The response is not in the correct format.Analytics - Unable to parse acquisition

service response (<error message>)

There is 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, ignoring

Failed to get the response in the time that is defined byreferrerTimeout. Increase the value and try again.

Analytics - Acquisition referrer timed

out

You should also ensure that you opened the acquisition linkbefore installing the app and that you are using the samenetwork when you click the URL and open the app.


• The acquisition server provides an attribution match that based on the IP address and user-agent information that was recordedin the link click (step 6) and when the app is launched (step 7).

67Acquisition

You should be on the same network when you click the URL and when you open the app.

• By using HTTP monitoring tools, hits that are sent from the app can be monitored to provide verification of the acquisitionattribution.

You should see one /v3/<appid>/start request and one /v3/<appid>/end request that are sent to the acquisitionserver.

• Variations in the user-agent sent might cause attribution to fail.

Ensure that http://c00.adobe.com/v3/<appid>/start and http://c00.adobe.com/v3/<appid>/endhave the same user-agent values.

• The acquisition link and the hit from the SDK should be using the same HTTP/HTTPS protocol.

If the link and the hit are using different protocols (for example, the link uses HTTP and the SDK uses HTTPS) the IP addressmight differ for each request (on some carriers). This could cause the attribution to fail.

• The marketing links are cached on the server side with a ten-minutes expiration time.

When you make changes to marketing links, you should wait about 10 minutes before using the links.

Testing Version 3 Acquisition

This information helps you roundtrip a V3 acquisition campaign link based on a device fingerprint.

Important: V3 Acquisition refers to the acquisition links that you create with the Acquisition Builder in the Adobe MobileServices UI. To use this feature, you must upgrade to iOS SDK version 4.6.0 or later.

If the mobile app is not yet in the App Store, when you create the campaign link, select any mobile app as a destination. Thisonly affects the app to which the acquisition server redirects you after you click the acquisition link, but does not affect the abilityto test the link.

1. Complete the prerequisite tasks in Mobile App Acquisition.2. Navigate to the Acquisition Builder in the Adobe Mobile Services UI and generate an acquisition campaign URL.

For example:http://c00.adobe.com/v3/<appid>/start?a_i_id=iostestapp&a_g_id=com.adobe.android&a_dd=i&ctxa.referrer.campaign.name=name&ctxa.referrer.campaign.trackingcode=trackingcode

If you refer to both iOS and Android apps in the acquisition link, use the Apple Store as the default store.

3. Open the generated link in a desktop browser and go to http://c00.adobe.com/v3/<appid>/end.

You should 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 it is missing, ensure that the acquisition URL follows the format that is specifiedin Create Acquisition Link Manually.

4. 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.

68Acquisition

https://marketing.adobe.com/resources/help/en_US/mobile/index.html?f=acquisition_link_manual

ValueSetting

referrerTimeout should have a value greater than 0.analytics

5. (Conditional) If the ssl setting in your app's config file is true, update your acquisition link to use the HTTPS protocol.6. Click the generated link from the mobile device on which you will install the app.

Adobe's servers (c00.adobe.com) store the fingerprint and redirect to the App Store. The app does not need to bedownloaded for testing.

7. Launch the application for the first time from the same mobile device that you used in step 6.

You can delete and install the app again, if necessary.

8. (Optional) You can enable debug logging of the SDK to obtain additional information.

If everything works correctly, you should see following logs:"Analytics - Trying to fetch referrer data from <acquisition end url>""Analytics - Received Referrer Data(<Json Object>)"

If you do not see the above logs, ensure that you have completed steps 4 and 5.

The following table contains information to explain possible errors:

DescriptionError

A network error occurred."Analytics - Unable to retrieve acquisition service response(<error message>)"

The response is not in the correct format."Analytics - Unable to parse acquisition service response(<error message>)"

There in no contextData parameter in the response."Analytics - Unable to parse acquisition service response (nocontextData parameter in response)"

a.referrer.campaign.name is not included incontextData.

"Analytics - Acquisition referrer data was not complete,ignoring"

Failed to get the response in the time that is defined byreferrerTimeout. Increase the value and try again.

"Analytics - Acquisition referrer timed out"

You should also ensure that you opened the acquisition linkbefore installing the app and that you are using the samenetwork when you click the URL and open the app.


• The acquisition server provides an attribution match that is based on the IP address and user-agent information that is recordedin the link click (step 6) and when the app is launched (step 7).

You should be on the same network when you click the URL and when you open the app.

• By using HTTP monitoring tools, hits sent from the app can be monitored to provide verification of the acquisition attribution.

69Acquisition

You should see one /v3/<appid>/start request and one /v3/<appid>/end request sent to the acquisition server. Variationsin the user-agent sent might cause attribution to fail.

Tip: Ensure that http://c00.adobe.com/v3/<appid>/start and http://c00.adobe.com/v3/<appid>/endhave the same user-agent values.

• The acquisition link and the hit from the SDK should be using the same HTTP/HTTPS protocol.

If they are using different protocols (for example, the link uses HTTP and the SDK uses HTTPS), the IP address might differfor each request (on some carriers), and the attribution might fail.

Testing Legacy Acquisition

The following information helps you roundtrip an legacy acquisition campaign link that is based on a device fingerprint.

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 which app the acquisition server redirects you to, after you click the acquisition link, not the ability to test theacquisition link.

1. Navigate to Use Legacy Acquisition Links in Adobe Mobile Services and generate an acquisition campaign URL.2. From the mobile device on which you will install the app, click the generated link.

Adobe's servers (c00.adobe.com) store the fingerprint and then redirect to the App Store. The app does not have to bedownloaded for testing.

3. On the same mobile device that you used in step 2, launch the application for the first time.

The easiest way to ensure that this happens is to delete and install the app again.


• The acquisition server provides an attribution match that is based on IP address and user-agent information that recorded inthe link click (step 2) and when the app is launched (step 3).

• By using HTTP monitoring tools, hits that are sent from the app can be monitored to provide verification of the acquisitionattribution.

Tip: Variations in the user-agent sent might cause attribution to fail.

Apple Search Ads

The Adobe SDK leverages Apple's Search Ads App Attribution APIs to enable developers and marketers to track and attributeapp downloads that originate from Search Ads campaigns in the Apple App Store.

For more information about Search Ad campaigns, see Apple Search Ads.

Benefits

Here are some benefits to using Apple ads:

• Easily measure the effectiveness of your Search Ads app download campaigns by adding a few lines of code to your app.• Developers can access the date/time of the download and the bidded keyword that drove the conversion.

70Acquisition

https://marketing.adobe.com/resources/help/en_US/mobile/index.html?f=c_use_legacy_acquisition_links

http://searchads.apple.com

Implementing Apple Ads

Tip: To implement Apple Ads, you must have iOS SDK version 4.13.2 or later.

To enable your app for Search Ad attribution:

1. Implement the Adobe SDK version 4.13.2 or above.

For more information, see Getting Started.

2. Add the iAd framework to the Xcode project file for your app.

Reporting on Search Ads Attribution

1. Apple Search Ads attribution data is provided in the acquisition name, the source, and the term values.

If attribution = true, all of the iad-* fields will be included in the lifecycle hit.

In addition, the following values will be mapped from the "iad" dictionary to our typical acquisition context data fields:

• "iad-campaign-id" --> "a.referrer.campaign.trackingcode"• "iad-campaign-name" --> "a.referrer.campaign.name"• "iad-adgroup-id" --> "a.referrer.campaign.content"• "iad-keyword" --> "a.referrer.campaign.term"

This mapping will make the values available in our standard reporting.

71Acquisition

MessagingThis information helps you use messaging in your iOS apps.

In-App Messaging

This information helps you use in-app messaging in your iOS apps.

To use in-app messaging, you must have SDK version 4.2 or later.

Some information to remember:

• Messages and the rules that define when messages are displayed are created in Adobe Mobile services. For more information,see Create an in-app message.

• The updates described in this section must be made to the SDK to display in-app messages.

Tip: You can complete these steps even if you do not have any messages defined. After you define messages, they will bedelivered dynamically to your app and displayed without an app store update.


• Enabling In-App Messages• Tracking In-App Messages• Local Fallback Image

Enabling In-App Messages



3. Verify that ADBMobileConfig.json contains the required settings for In-App messaging.4. For in-app messages to be updated dynamically 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”}

Tip: messages or remotes is required.

72Messaging

https://marketing.adobe.com/resources/help/en_US/mobile/?f=t_in_app_message

If these objects are not configured, download an updatedADBMobileConfig.json from Adobe Mobile services.

Tracking In-App Messages

The iOS Mobile Services SDKs track the following metrics for your in-app messages:

• For full screen and alert style in-app messages:

• Impressions: when user triggers an in-app message.• Click throughs: when user pushes the Click-through button.• Cancels: when user pushes the Cancel button.

• For custom, full screen in-app messages, the HTML content in the message needs to include the correct code to notify theSDK tracking about the following buttons:

• Click-through (redirect) example tracking: adbinapp://confirm/?url=http://www.yoursite.com• Cancel (close) example tracking: adbinapp://cancel

• For local (remote) notifications:

• Impressions: when user triggers the notification.• Opens: when user opens app from the notification.

Here is an example about how to include open tracking:

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

// handle local notification click-throughs for iOS 10 and older NSDictionary *localNotificationDictionary = launchOptions[UIApplicationLaunchOptionsLocalNotificationKey]; if ([localNotificationDictionary isKindOfClass:[NSDictionary class]]) { [ADBMobile trackLocalNotificationClickThrough:localNotificationDictionary]; }

}- (void) application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification { [ADBMobile trackLocalNotificationClickThrough:notification.userInfo];}

Local Fallback Image

When creating a full screen message in Adobe Mobile services, you can optionally specify a fallback image. If your message isunable to retrieve its intended image from the web, the SDK attempts to load the image with the same name from your applicationbundle. This allows you to display your message in its original form even if the user is offline, or the predetermined image isunreachable.

The fallback image asset name is specified when configuring the message in Adobe Mobile services.

Important: You need to ensure that the specified resource is available.

Troubleshooting In-App Messaging

This information helps you troubleshoot in-app messaging.

If you completed all the requirements for In-App Messaging, but messages do not display, check the following items:

73Messaging

SuggestionSituation or Issue

Verify that the SDK is version 4.2 or higher and correctly configured. For moreinformation, see View Hits.

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.

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 isn't working. For more information, see step 2 under Enabling In-App Messages.

Check on the list view on the Manage In-App Message page in the Status column, andverify if it is live.

Is the message live?

Verify 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.

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.

74Messaging

https://marketing.adobe.com/resources/help/en_US/mobile/bloodhound/view_hits.html

https://marketing.adobe.com/resources/help/en_US/mobile/ios/messaging.html

https://marketing.adobe.com/resources/help/en_US/mobile/android/messaging.html

https://marketing.adobe.com/resources/help/en_US/mobile/bloodhound/view_hits.html

https://marketing.adobe.com/resources/help/en_US/mobile/ios/json_config.html

SuggestionSituation or Issue

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.

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 that have opened your app as a result of clicking through a push message.

To use push messaging, you must have SDK version 4.6 or later.

Important: Do not manually set the Experience Cloud ID inside your app. This causes the creation of a new unique userthat will not receive push messages because of its opt-in status. For example, suppose a user that has opt-ed in to receive pushmessages logs in to your app. After logging in, if you manually set the ID inside your app, a new unique user is created thathas not opted to receive push messages. This new user will not receive your push messages.


• Prerequisites• Enabling Push Messaging• Example

Prerequisites

• Add the library to your project and implement lifecycle metrics.

75Messaging

• SDK must be enabled for the ID Service.

Enabling Push Messaging

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": "3CE342C92046435B0A490D4C@AdobeOrg"}

2. Import the library in your AppDelegate.#import "ADBMobile.h"

3. Configure your application to request push permissions.

For more information see Configuring Remote Notification Support in the iOS Developer Library.- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // if device is running iOS 8.0 or newer, use the new method to ask permission to send them notifications if ([application respondsToSelector:@selector(registerUserNotificationSettings:)]) { UIUserNotificationType types = UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound; UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:types categories:nil]; [application registerUserNotificationSettings:settings]; [application registerForRemoteNotifications]; } else { [application registerForRemoteNotificationTypes:UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound]; } return YES;}

4. The push token must be passed to the SDK using the method setPushIdentifier: in ADBMobile class.- (void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { ... [ADBMobile setPushIdentifier:deviceToken]; ...}

5. Enable reporting by passing the userInfo dictionary to the SDK when your app launches or resumes because the userclicked on your push message.- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { ... // only send the hit if the app is not active if (application.applicationState != UIApplicationStateActive) { [ADBMobile trackPushMessageClickThrough:userInfo]; } ...}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { ... // only send the hit if the app is not active if (application.applicationState != UIApplicationStateActive) { [ADBMobile trackPushMessageClickThrough:userInfo]; }

76Messaging

https://marketing.adobe.com/resources/help/en_US/mobile/t_config_visitor.html

https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/HandlingRemoteNotifications.html#//apple_ref/doc/uid/TP40008194-CH6-SW1

...}

6. To enable reporting on users who disabled push messaging for your app, call [ADBMobile setPushIdentifier: nil]in the method applicationDidBecomeActive: in your AppDelegate.- (void)applicationDidBecomeActive:(UIApplication *)application { ... //if the user has disabled push notifications, set the push identifier to nil in the Adobe Mobile SDK

//for devices running iOS 8.0+ if([application respondsToSelector:@selector(isRegisteredForRemoteNotifications)]) { if(![application isRegisteredForRemoteNotifications]) { [ADBMobile setPushIdentifier:nil]; } } else if ([application enabledRemoteNotificationTypes] == UIRemoteNotificationTypeNone) { [ADBMobile setPushIdentifier:nil]; } ...}

Example

The following is an example of what an AppDelegate.m implementation might look like:#import "AppDelegate.h"#import "ADBMobile.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // if device is running iOS 8.0 or newer, use the new method to ask permission to send them notifications if ([application respondsToSelector:@selector(registerUserNotificationSettings:)]) { UIUserNotificationType types = UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound; UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:types categories:nil]; [application registerUserNotificationSettings:settings]; [application registerForRemoteNotifications]; } else { [application registerForRemoteNotificationTypes:UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound]; } return YES;}

- (void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { [ADBMobile setPushIdentifier:deviceToken];}

- (void) application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error { [ADBMobile setPushIdentifier:nil];}

// app target < iOS 7- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { // only send the hit if the app is not active if (application.applicationState != UIApplicationStateActive) { [ADBMobile trackPushMessageClickThrough:userInfo];

77Messaging

}}

// app target >= iOS 7- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { // only send the hit if the app is not active if (application.applicationState != UIApplicationStateActive) { [ADBMobile trackPushMessageClickThrough:userInfo]; } completionHandler(UIBackgroundFetchResultNoData);}

@end

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.

1. In AppDelegate, you can get the deep link URL back and handle it on your own in the following locations:

• In application:didFinishLaunchingWithOptions:

If the app is not running when a push click through happens, you can get the push payload from launchOptions, and deeplink URL is in the payload dictionary by the adb_deeplink key.

• The delegate methods for Remote Notification

In the didReceiveRemoteNotification: application or in thedidReceiveRemoteNotification:fetchCompletionHandler: application, you can get the URL by accessing theuserInfo dictionary with the adb_deeplink key.

For example:- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

NSDictionary* remoteNotification = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey]; if (remoteNotification && [remoteNotification isKindOfClass:[NSDictionary class]]) { NSString* deeplink = remoteNotification[@"adb_deeplink"]; //handle deep link url }

return YES;}

// app target < iOS 7- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { // only send the hit if the app is not active if (application.applicationState != UIApplicationStateActive) { [ADBMobile trackPushMessageClickThrough:userInfo]; NSString* deeplink = userInfo[@"adb_deeplink"]; // handle deep link url }}

// app target >= iOS 7- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { [ADBMobile trackPushMessageClickThrough:userInfo]; NSString* deeplink = userInfo[@"adb_deeplink"];

78Messaging

// handle deep link url }

Receive Rich Push Notifications

You can attach image files to your Apple notifications. Adding visual components can significantly increase your users' engagementwith push notifications.

To receive rich push notifications in your iOS app:

1. Implement push messaging for the app by completing the steps in Push Messaging.

2. Verify that you can send a text push message to your app.

3. Add a Notification Service Extension by completing the following steps:

1. In your Xcode project, select File > New > Target.2. Select Notification Service Extension.3. Verify that the NotificationService.m file exists.

4. Open the NotificationService.m file and verify that the following delegate methods exist:

• One method to receive a notification request.• One method to handle the expiration of the service extension.

To receive rich push notifications, the first method is used:(void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent *contentToDeliver))contentHandler;

In this method, you can get the Media URL from userInfo by using the ‘attachment-url’ key, and after you downloadthe file to a local directory, add the local path to bestAttemptContent.attachments.

Here is an example of the code in this method:- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { self.contentHandler = contentHandler; self.bestAttemptContent = [request.content mutableCopy]; NSDictionary* userInfo = request.content.userInfo; if(userInfo[@"attachment-url"]){ NSURL* url = [[NSURL alloc] initWithString:userInfo[@"attachment-url"]]; NSURLSessionDownloadTask* task = [[NSURLSession sharedSession] downloadTaskWithURL:url completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) { if(!location){ return; } NSString* tmpDirectory = NSTemporaryDirectory(); NSString* tmpFilePath = [NSString stringWithFormat:@"file://%@%d%d%@", tmpDirectory, arc4random_uniform(100000), arc4random_uniform(100000), [url lastPathComponent]]; NSURL* tmpUrl = [[NSURL alloc] initWithString:tmpFilePath]; NSError * fileError = nil; [[NSFileManager defaultManager] moveItemAtURL:location toURL:tmpUrl error:&fileError]; if(fileError){ return; } UNNotificationAttachment* attachment = [UNNotificationAttachment attachmentWithIdentifier:@"video" URL:tmpUrl options:nil error:&fileError]; if(fileError){ return; } self.bestAttemptContent.attachments = @[attachment];

79Messaging

self.contentHandler(self.bestAttemptContent);

}]; [task resume]; }

}

For more information about rich push notifications with iOS, see UNNotificationAttachment.

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

Sending push messages requires a valid Push Service Certificate. Mobile Services willnotify you when your certificate is close to expiring or has expired. If you receive thisnotification, complete the following steps to renew your certificate:

How do I renew my Apple PushService Certificate?

1. Click Manage App Settings.2. To delete the current certificate, scroll to Push Services and click Delete.

80Messaging

https://developer.apple.com/documentation/usernotifications/unnotificationattachment

https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html#//apple_ref/doc/uid/TP40008194-CH100-SW4

https://developers.google.com/cloud-messaging/concept-options#lifetime

DescriptionSituation or issue

3. Configure and test a new certificate.

For more information, see Prerequisites to Enable Push Messaging

4. Click Save.

81Messaging

https://marketing.adobe.com/resources/help/en_US/mobile/prerequisites_push_messaging.html

LocationThis information helps you use the Location features in your iOS 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 iOSapps.

Each trackLocation call sends the following:

• Latitude, longitude, and location in a point of interest (POI) that is defined in Adobe Mobile services.

This information is passed to mobile solution variables for automatic reporting.

• Distance from center & 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.


• Dynamic POI updates• How to Track• Sending Additional Data• Location Context Data• Additional Information

Dynamic POI updates

Starting in version 4.2, POIs are defined in the Adobe Mobile interface and synchronized dynamically to the app configurationfile. 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, an updated version of the ADBMobile.json file must be downloaded and added to your app. For moreinformation and instructions, see Download the SDK.

How to Track



3. Call trackLocation to track the current location:CLLocation *currentLocation = location;[ADBMobile trackLocation: currentLocation data: nil];

Tip: You can call trackLocation at any time.

You can use Getting the User’s Location 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 in Location reports. An a.loc.dist context variable is also sent with the distancein meters from the defined coordinates.

82Location


https://developer.apple.com/Library/ios/documentation/UserExperience/Conceptual/LocationAwarenessPG/CoreLocation/CoreLocation.html


In addition to the location data, you can send additional context data with each track location call:NSMutableDictionary *contextData = [NSMutableDictionary dictionary];[contextData setObject:@"GPS" forKey:@"myapp.location.LocationSource"];[ADBMobile trackLocation: currentLocation data:contextData];


Location Context Data

The latitude and longitude are each sent using three different context data parameters, with each parameter representing adifferent level of precision, for a total of six context data parameters.

For example, the coordinates lat = 40.93231, lon = -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


• A trackLocation request sends in the equivalent of a trackAction call.• POIs are not passed as part of normal 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 based on the requirements of the application.

• POIs are populated only after they are defined in the app configuration file.

83Location


They are not applied to historical trackLocation calls that were sent previously.

• 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 granular to least granular to ensure that the most granular POI is reported.

iBeacon tracking

iBeacon tracking allows you to measure and target micro locations using iBeacon and Low Energy Bluetooth.

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 in a store• a.beacon.prox - The following values represent how close the user is to the beacon:

• 0 is unknown• 1 is immediate• 2 is near• 3 is far


• Tracking iBeacons• Sending Additional Data• Examples

Tracking iBeacons



3. When a device is within the proximity of a beacon, call trackBeacon:[ADBMobile trackBeacon:beacon data:nil];

4. When the user leaves the proximity of the beacon, clear the current beacon:[ADBMobile trackingClearCurrentBeacon];


In addition to the timed action name, you can send additional context data with each track action call:[ADBMobile trackBeacon:beacon data:@{@"myapp.ImageLiked" : imageName}];


84Location


Examples- (void)locationManager:(CLLocationManager *)manager didRangeBeacons:(NSArray *)beacons inRegion:(CLBeaconRegion *)region { if (beacons.count > 0) { CLBeacon *beacon = beacons[0]; // Adobe - track when in range of a beacon [ADBMobile trackBeacon:beacon data:@{@"sampleContextData" : @"sampleContextDataVal"}];

}}

// When the user leaves the proximity of the beacon, clear the current beacon[ADBMobile trackingClearCurrentBeacon];

85Location

TargetThis information helps you deliver targeted content in iOS applications.

Target Methods

Here is the list of Adobe Target methods that are provided by the iOS library.

The SDK currently has support for multiple Adobe Experience Cloud Solutions, including Analytics, Target, Audience Manager,and the Experience Cloud ID service. Methods are prefixed according to the solution. For example, Target methods are prefixedwith target.

Tip: Lifecycle Metrics are sent as parameters to each mbox load.

Class Reference : ADBTargetLocationRequest

PropertiesNSString *name;NSString *defaultContent;NSMutableDictionary *parameters;

String Constants

Tip: The following constants are for ease of use when you set keys for custom parameters.

NSString *const ADBTargetParameterOrderId;NSString *const ADBTargetParameterOrderTotal;NSString *const ADBTargetParameterProductPurchasedId;NSString *const ADBTargetParameterCategoryId;NSString *const ADBTargetParameterMbox3rdPartyId;NSString *const ADBTargetParameterMboxPageValue;NSString *const ADBTargetParameterMboxPc;NSString *const ADBTargetParameterMboxSessionId;NSString *const ADBTargetParameterMboxHost;

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 offerthat is generated in a block callback.

targetLoadRequest:callback:

Syntax:+ (void) targetLoadRequest:(ADBTargetLocationRequest *)request callback:(void (^)(NSString *content))callback;

Example:[ADBMobile targetLoadRequest:myRequest callback:^(NSString *content) {

86Target

http://developers.adobetarget.com/api/#input-parameters

http://developers.adobetarget.com/api/#batch-input-parameters

DescriptionMethod

// do something with content }];

Sends a request to your configured Target server and returns the string value of the offerthat is generated in a block callback.

targetLoadRequestWithName:defaultContent:profileParameters:orderParameters:mboxParameters:requestLocationParameters:callback:

Syntax:+ (void) targetLoadRequestWithName:(nullable NSString *)name defaultContent:(nullable NSString *)defaultContent profileParameters:(nullable NSDictionary *)profileParameters orderParameters:(nullable NSDictionary *)orderParameters mboxParameters:(nullable NSDictionary *)mboxParameters requestLocationParameters:(nullable NSDictionary *)requestLocationParameters callback:(nullable void (^)(NSString* __nullable content))callback;

Returns: N/A

Parameters:

Description:Name:

Type: NSString *name

Name of the Target mbox/location that you want to retrieve.

Type: NSString *defaultContent

Value returned in the callback if the Target server isunreachable, or the user does not qualify for the campaign.

Type: NSDictionary *profileParameters

Values in this dictionary will go in the"profileParameters" object in the request to Target.

Type: NSDictionary *orderParameters

Values in this dictionary will go in the "order" object in therequest to Target.

Type: NSDictionary *mboxParameters

Values in this dictionary will go in the "mboxParameters"object in the request to Target.

Type: NSDictionary *requestLocationParameters

87Target

DescriptionMethod

Description:Name:

Values in this dictionary will go in the "requestLocation"object in the request to Target.

Type: Functioncallback

This method will be called with the content of the offer fromthe Target server. If the Target server is unreachable, or theuser does not qualify for the campaign, defaultContentwill be returned.

Example:[ADBMobile targetLoadRequestWithName:@"myHeroBanner" defaultContent:@"defaultHeroBanner.png" profileParameters:@{@"age":@"20-29"} orderParameters:nil

mboxParameters:@{@"customParam":@"customValue"} requestLocationParameters:@{@"host":@"my.hostname.com"}

callback:^(NSString *content){ // do something with content myImageView.image = [UIImage imageNamed:content]; }];

For more information about the underlying Target API, see the Delivery documentationon the Target Developers website.

Sends request to your configured Target server and returns the string value of the offergenerated in a block callback.

targetLoadRequestWithName:defaultContent:profileParameters:orderParameters:mboxParameters:callback:

Syntax:+ (void) targetLoadRequestWithName:(nullable NSString *)name defaultContent:(nullable NSString *)defaultContent profileParameters:(nullable NSDictionary *)profileParameters orderParameters:(nullable NSDictionary *)orderParameters

mboxParameters:(nullable NSDictionary *)mboxParameters

callback:(nullable void (^)(NSString* __nullable content))callback;

Example:[ADBMobile targetLoadRequestWithName:@"mboxName" defaultContent:@"defaultContent" profileParameters:@{@"profile-parameter-key": @"profile-parameter-value"} orderParameters:@{@"order-parameter-key": @"order-parameter-value"} mboxParameters:@{@"mbox-parameter-key": @"mbox-parameter-value"} callback:^(NSString* content) { //do something with content } }];

88Target

https://docs.adobe.com/dev/products/target/reference/delivery.html

https://docs.adobe.com/dev/products/target/reference/delivery.html

DescriptionMethod

Creates an ADBTargetLocationRequest.targetCreateOrderConfirmRequestWithName:orderId: Syntax:

+ (ADBTargetLocationRequest *) targetCreateOrderConfirmRequestWithName:(NSString *)name

orderTotal:productPurchasedId:parameters:

orderId:(NSString *)orderId orderTotal:(NSString *)orderTotal productPurchasedId:(NSString *)productPurchasedId parameters:(NSDictionary *)parameters;

Convenience constructor to create an ADBTargetLocationRequest object with thegiven parameters.

targetCreateRequestWithName:defaultContent:parameters

Syntax:+ (ADBTargetLocationRequest *) targetCreateRequestWithName:(NSString *)name defaultContent:(NSString *)defaultContent parameters:(NSDictionary *)parameters;

Example:ADBTargetLocationRequest *myRequest = [ADBMobile targetCreateRequestWithName:@"heroBanner" defaultContent:@"default.png" parameters:nil];

Returns the third-party ID.targetThirdPartyID

Syntax:+ (nullable NSString *) targetThirdPartyID;

Example:NSString *thirdPartyId = [ADBMobile targetThirdPartyID];

Sets the third-party ID.targetSetThirdPartyID:

Syntax:+ (void) targetSetThirdPartyID:(nullable NSString *)thirdPartyID;

Example:[ADBMobile targetSetThirdPartyID:@"thirdPartyID"];

Clears any target cookies from your app.targetClearCookies

Tip: Since version 4.10.0 of the SDK, Target no longer uses cookies. This methodresets the thirdPartyID and sessionID.

Syntax:+ (void) targetClearCookies;

89Target

DescriptionMethod

Example:[ADBMobile targetClearCookies];

Returns the PcID.targetPcID

Syntax:+ (nullable NSString *) targetPcID;

Example:NSString *myTargetPcID = [ADBMobile targetPcID];

Returns the SessionID.targetSessionID

Syntax:+ (nullable NSString *) targetPcID;

Example:NSString *myTargetSessionID = [ADBMobile targetSessionID];

Example:// make your requestADBTargetLocationRequest *myRequest = [ADBMobile targetCreateRequestWithName:@"heroBanner" defaultContent:@"default.png" parameters:nil];// load your request[ADBMobile targetLoadRequest:myRequest callback:^(NSString *content) { // do something with content heroImage.image = [UIImage imageNamed:content]; }];

Prefetch offer content in iOS

The Adobe Target prefetch feature uses the iOS Mobile SDKs to fetch offer content as few times as possible by caching the serverresponses.

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

90Target

http://developers.adobetarget.com/api/#batch-input-parameters

DescriptionParameter

Sends a prefetch request with an array of locations to the configured Target server and returnsthe request status in the provided callback.

targetPrefetchContent

Syntax

(void) targetPrefetchContent:(nonnull NSArray *)targetPrefetchObjectArray withProfileParameters:(nullable NSDictionary *)profileParameters callback:(nullable void(^)(BOOL success))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 successful andfalse if the prefetch was unsuccesful.

Executes a batch request for multiple mbox locations that are specified in the requests array. Eachobject in the array contains a callback function, which will be invoked when content is availablefor its given mbox location.

targetLoadRequests

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 to theTarget servers to retrieve the content.

Syntax:(void) targetLoadRequests:(nonnull NSArray *)requests withProfileParameters:(nullable NSDictionary *)profileParameters;

Parameters:

DescriptionName

Array of TargetRequestObjects thatcontains the name, default content, parameters,and callback function per location to retrieve.

requests

91Target

DescriptionParameter

DescriptionName

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.targetPrefetchClearCache

Syntax:

(void) targetPrefetchClearCache;

Parameters: N/A

Creates and returns an instance of TargetRequestObject with the provided data.targetRequestObjectWithName

Syntax:

+ (nullable ADBTargetRequestObject *) targetRequestObjectWithName:(nonnull NSString *)name

defaultContent:(nonnull NSString *)defaultContent

mboxParameters:(nullable NSDictionary *)mboxParameters

callback:(nullable void (^)(NSString* __nullable content))callback;

Creates and returns an instance of TargetPrefetchObject with the provided data.createTargetPrefetchObject

Syntax:

+ (nullable ADBTargetPrefetchObject *) targetPrefetchObjectWithName:(nonnull NSString *)name

mboxParameters:(nullable NSDictionary *)mboxParameters;

Public Classes

Here are the public classes that support pre-fetch in iOS :

Class Reference: TargetPreFetchObject

Encapsulates the mbox name and the parameters that are used for mbox prefetch.

DescriptionProperty

Type: NSString*name

The NSString value that represents the name for the location/mbox you want to retrieve.

Type: NSDictionary*mboxParameters

An optional dictionary that contains the key-value pairs of mbox parameters.

92Target

DescriptionProperty

Type: NSDictionary*orderParameters

Dictionary that contains the key-value pairs of order parameters.

Type: NSDictionary*productParameters

Dictionary that contains the key-value pairs of product parameters.

Class Reference: TargetRequestObject

This class encapsulates the mbox name, default content, mbox parameters and the return callback used for Target locationrequests.

DescriptionProperty

Type: NSString*name

Name of the requested location.

Type:mboxParameters

The NSString value that represents the name for the location/mbox you want to retrieve.

Type: NSString*defaultContent

The default content that will be returned if Target servers are unreachable.

Type: Functioncallback

When the batch requests Target locations, callback will be invoked when content is availablefor this location.

Code Sample

Here is an example of how to prefetch content by using the iOS SDKs:

/** * Prefetch Content */

NSDictionary *mboxParameters1 = @{@"status":@"platinum"}; NSDictionary *productParameters1 = @{@"id":@"24D3412", @"categoryId":@"Books"}; NSDictionary *orderParameters1 = @{@"id":@"ADCKKIM", @"total":@"344.30", @"purchasedProductIds":@"34, 125, 99"};

NSDictionary *mboxParameters2 = @{@"userType":@"Paid"}; NSDictionary *productParameters2 = @{@"id":@"764334", @"categoryId":@"Online"};

NSArray *purchaseIDs = @[@"id1",@"id2"]; NSDictionary *orderParameters2 = @{@"id":@"4t4uxksa", @"total":@"54.90", @"purchasedProductIds":purchaseIDs};

93Target

// Creating Prefetch Objects ADBTargetPrefetchObject *prefetch1 = [ADBMobile targetPrefetchObjectWithName:@"logo" mboxParameters:mboxParameters1]; prefetch1.productParameters = productParameters1; prefetch1.orderParameters = orderParameters1;

ADBTargetPrefetchObject *prefetch2 = [ADBMobile targetPrefetchObjectWithName:@"buttonColor" mboxParameters:mboxParameters2]; prefetch2.productParameters = productParameters2; prefetch2.orderParameters = orderParameters2;

// Creating prefetch Array NSArray *prefetchArray = @[prefetch1,prefetch2];

// Creating Profile parameters NSDictionary *profileParmeters = @{@"age":@"20-32"};

// Target API Call [ADBMobile targetPrefetchContent:prefetchArray withProfileParameters:profileParmeters callback:^(BOOL isSuccess){ // do something with the Boolean result }];

Here is an example of the batch loadRequest by using the iOS SDKs:/** * Batch loadRequest */

NSDictionary *mboxParameters1 = @{@"status":@"platinum"}; NSDictionary *productParameters1 = @{@"id":@"24D3412", @"categoryId":@"Books"}; NSDictionary *orderParameters1 = @{@"id":@"ADCKKIM", @"total":@"344.30", @"purchasedProductIds":@"34, 125, 99"};

NSDictionary *mboxParameters2 = @{@"userType":@"Paid"}; NSDictionary *productParameters2 = @{@"id":@"764334", @"categoryId":@"Online"}; NSArray *purchaseIDs = @[@"id1",@"id2"]; NSDictionary *orderParameters2 = @{@"id":@"4t4uxksa", @"total":@"54.90", @"purchasedProductIds":purchaseIDs};

ADBTargetRequestObject *request1 = [ADBMobile targetRequestObjectWithName:@"logo" defaultContent:@"BlueWhale" mboxParameters:mboxParameters1 callback:^(NSString *content){ // do something with the received content }];

request1.productParameters = productParameters1; request1.orderParameters = orderParameters1;

ADBTargetRequestObject *request2 = [ADBMobile targetRequestObjectWithName:@"buttonColor" defaultContent:@"red" mboxParameters:mboxParameters2 callback:^(NSString *content){ // do something with the received content }]; request2.productParameters = productParameters1; request2.orderParameters = orderParameters1;

// create request object array NSArray *requestArray = @[request1,request2];

94Target

// Call the API [ADBMobile targetLoadRequests:requestArray withProfileParameters:profileParmeters];


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 array of strings.

95Target

Experience CloudThis information helps you use the iOS SDK with the Adobe Experience Cloud.

Experience Cloud ID

The Experience Cloud ID service provides a universal visitor ID across Experience Cloud solutions. The ID service is requiredby Analytics for Target, video heartbeat, and future Experience Cloud integrations.

Tip: You do not need to populate the Experience Cloud ID unless you are using the Experience Cloud ID service. For moreinformation, see Experience Cloud ID Service.

Requires SDK version 4.3 or later

Enabling the Experience Cloud ID



3. Verify that ADBMobileConfig.json contains the marketingCloudorg:"marketingCloud" : { "org": "YOUR-MCORG-ID"}

Experience Cloud organization IDs uniquely identify each client company in the Adobe Experience Cloud and are similarto the following value: 016D5C175213CCA80A490D05@AdobeOrg.

Important: You must include @AdobeOrg.

If these values are not present, download an updated ADBMobileConfig.json from Adobe Mobile services.

After the configuration, a Experience Cloud ID is generated and is included on all hits. Other visitor IDs, such as custom andautomatically-generated, will continue to be sent with each hit.

Experience Cloud ID Service Methods

Here are the Experience Cloud ID service methods that are provided by the iOS library.

The SDK currently supports multiple Adobe Experience Cloud Solutions, including Analytics, Target, Audience Manager, andthe Experience Cloud Visitor ID service.

Methods are prefixed according to the solution, and Experience Cloudr ID methods are prefixed with visitor. For moreinformation, see Enabling the Experience Cloud ID.

DescriptionMethod

Appends Adobe visitor data to a URL string for use with the Adobe JavaScript library. Touse this method, you must have Mobile SDK 4.12+. For more information, see AppendVisitor ID Helper Function).

+ (nullable NSURL *)visitorAppendToURL: (nullableNSURL *) url;

96Experience Cloud

https://marketing.adobe.com/resources/help/en_US/mcvid/

https://marketing.adobe.com/resources/help/en_US/mcvid/mcvid-appendvisitorid.html

https://marketing.adobe.com/resources/help/en_US/mcvid/mcvid-appendvisitorid.html

DescriptionMethod

Important: This method can cause a blocking network call. Do not call this ontime-sensitive threads.

• Input: URL<NSURL>

A required URL string that the visitor information will be appended to.

• Output: URL<NSURL>

String with the visitor info appended.

Example:NSURL *url = [NSURL URLWithString:@"http://www.example.com"]; NSURL *decoratedURL = [ADBMobile visitorAppendToURL: url]; [[UIApplication sharedApplication] openURL: decoratedURL];

Retrieves the Experience Cloud ID from the ID service.visitorMarketingCloudID

Syntax:+ (NSString *) visitorMarketingCloudID;

Example:NSString *mcid = [ADBMobile visitorMarketingCloudID];

Important: This method can cause a blocking network call and should not be calledfrom a UI thread.

With the Experience Cloud 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

visitorSyncIdentifiers:

a customer type identifier to separate the scope of the different customer IDs. This methodcorresponds to setCustomerIDs in the JavaScript library.

Syntax:+ (void) visitorSyncIdentifiers:(NSDictionary *)identifiers;

Example:[ADBMobile visitorSyncIdentifiers:@{@"idType":@"idValue"}];

Synchronizes the provided identifiers to the ID service. Pass in the authState as one ofthe following values:

visitorSyncIdentifiers:authenticationState:

• ADBMobileVisitorAuthenticationStateUnknown• ADBMobileVisitorAuthenticationStateAuthenticated• ADBMobileVisitorAuthenticationStateLoggedOut

Syntax:+ (void) visitorSyncIdentifiers:(nullable NSDictionary *)identifiers authenticationState:(ADBMobileVisitorAuthenticationState)authState;

97Experience Cloud

DescriptionMethod

Example:[ADBMobile visitorSyncIdentifiers:@{@"myIdType":@"valueForUser"} authenticationState:ADBMobileVisitorAuthenticationStateAuthenticated];

Synchronizes the provided identifier type and value to the ID service. Pass in the authStateas one of the following values:

visitorSyncIdentifierWithType:identifier:authenticationState:


Syntax:+ (void) visitorSyncIdentifierWithType:(nullable NSString *)identifierType identifier:(nullable NSString *)identifier authenticationState:(ADBMobileVisitorAuthenticationState)authState;

Example:[ADBMobile visitorSyncIdentifierWithType:@"myIdType" identifier:@"valueForUser" authenticationState:ADBMobileVisitorAuthenticationStateLoggedOut];

Retrieves an array of read-only ADBVisitorID objects.visitorGetIDs

Syntax:+ (nullable NSArray *) visitorGetIDs;

Example:NSArray *myVisitorIDs = [ADBMobile visitorGetIDs];

ADBVisitorID interface

Public Methods:

- (nullable NSString *) idType;- (nullable NSString *) identifier;- (ADBMobileVisitorAuthenticationState) authenticationState;

ADBMobileVisitorAuthenticationState enumADBMobileVisitorAuthenticationStateUnknown,ADBMobileVisitorAuthenticationStateAuthenticated,ADBMobileVisitorAuthenticationStateLoggedOut

Experience Cloud Device Co-op

To start using the Experience Cloud Device Co-op, contact your Adobe representative.

To enable your mobile apps for the Experience Cloud Device Co-op, complete the following steps for the Experience Cloud iOSSDKs.

Important: This functionality requires iOS SDK version 4.8.5 or later.

98Experience Cloud

1. Implement the Adobe Mobile SDK.For more information, see Core Implementation and Lifecycle.

2. Enable your Experience Cloud ID.For more information, see Experience Cloud ID.

3. Pass authenticated identities such as CRM IDs or hashed emails using one of the sync methods contained here.For more information, see Experience Cloud ID Service Methods.

99Experience Cloud

Audience ManagerThis information helps you send signals and retrieve visitor segments from Audience Manager.

Audience Manager Methods

Here is a list of the Audience Manager methods that are provided by the iOS library.

The SDK currently supports multiple Adobe Experience Cloud Solutions, including Analytics, Target, Audience Manager, andthe Experience Cloud ID service. Methods are prefixed according to the solution, and Audience Manager methods are prefixedwith "audience."

If Audience Manager is configured in your JSON file, a signal that contains lifecycle metrics is sent withapplication:didFinishLaunchingWithOptions:.

Returns the visitor profile that was most recently obtained and, if no signal has beensubmitted, returns null. The visitor profile is saved in NSUserDefaults for easy accessacross multiple launches of your app.

audienceVisitorProfile

Syntax:+ (NSDictionary *) audienceVisitorProfile;

Example:NSDictionary *profile = [ADBMobile audienceVisitorProfile];

Returns the current DPID.audienceDpid

Syntax:+ (NSString *) audienceDpid;

Example:NSString *currentDpid = [ADBMobile audienceDpid];

Returns the current DPUUID.audienceDpuuid

Syntax:+ (NSString *) audienceDpuuid;

Example:NSString *currentDpuuid = [ADBMobile audienceDpuuid];

Sets the DPID and DPUUID. When set, both will be appended to each signal.audienceSetDpid:dpuuid:

• The Data Provider ID (DPID) is the data partner ID that is assigned by AudienceManager.

• The Data Provider Unique User ID (DPUUID) is the data provider's unique ID forthe user.

Important: Before version 4.13.x, DPUUID was not automatically encoded. Startingin version 4.13.x, the SDK first un-encodes the value that was passed in and then

100Audience Manager

re-encodes this value. This process ensures that the SDK does not break backwardscompatibility.

Syntax:+ (void) audienceSetDpid:(NSString *)dpid dpuuid:(NSString *)dpuuid;

Example:[ADBMobile audienceSetDpid:@"290" dpuuid:@"99301393920493"];

Resets the Audience Manager UUID and purges the current visitor profile.audienceReset

Syntax:+ (void) audienceReset;

Example:[ADBMobile audienceReset];

Sends audience management a signal with traits and gets the matching segments thatare returned in a block callback.

audienceSignalWithData::callback:

Syntax:+ (void) audienceSignalWithData:(NSDictionary *)data callback:(void (^)(NSDictionary *response))callback;

Example:[ADBMobile audienceSignalWithData:traits callback:^(NSDictionary *response) { // do something with returned segments

}];

Example:// setup your traits dictionaryNSDictionary *traits = @{@"trait":@"b"};// submit your signal and take action on results[ADBMobile audienceSignalWithData:traits callback:^(NSDictionary *response) { // do something with visitor segments here if ([response[@"gender"] isEqualToString:@"male"]) { // do something with gender } }];

101Audience Manager

Apple TV Implementation with tvOSThis information helps you implement Apple TV with tvOS.

With Apple TV, you can now create applications to run in the native tvOS environment. You can create a native app by usingseveral frameworks in iOS, or you can create your app by using XML templates and JavaScript.

Tip: tvOS suppor is available starting in AdobeMobileLibrary version 4.7.0.


• Getting Started• Configuring a Native App for tvOS• Configuring a TVML/TVJS App for tvOS

Getting Started

Tip: We assume that your project has a target that is an Apple TV app that is targeting tvOS. For more information, seetvOS.

Configuring a Native App for tvOS

Complete the following steps in your Xcode project:

1. Drag the AdobeMobileLibrary folder into your project.

2. Ensure that ADBMobileConfig.json is a member of your target.

3. On the Build Phases tab of your tvOS app’s target, expand the Link Binary with Libraries section and add the followinglibraries:

• AdobeMobileLibrary_TV.a• libsqlite3.0.tbd• SystemConfiguration.framework

For information, see the iOS documentation on iOS.

Configuring a TVML/TVJS App for tvOS


2. Ensure that ADBMobileConfig.json is a member of your target.

3. On the Build Phases tab of your tvOS app’s target, expand the Link Binary with Libraries section and add the followinglibraries:

• AdobeMobileLibrary_TV.a• libsqlite3.0.tbd• SystemConfiguration.framework

4. In the implementation file of your TVApplicationControllerDelegate class, import the SDK.#import “ADBMobile.h"

5. In the application:didFinishLaunchWithOptions: method of your TVApplicationControllerDelegate class,pass your TVApplicationController object to the SDK with the installTVMLHooks: method.

102Apple TV Implementation with tvOS

https://developer.apple.com/tvos/documentation/

https://developer.apple.com/ios/resources/

The Adobe SDK needs access to your app’s TVApplicationController to register itself into the JSContext of your app.This step allows you to call the native methods in the Adobe SDK from your JavaScript files.[ADBMobile installTVMLHooks:appController];

6. In your JavaScript files, use the ADBMobile object to access the native methods of the Adobe SDK.

For a complete listing of the available methods, see TVJS Methods.

Adobe Target for TVML/TVJS

You can leverage Adobe Target in your TVML/TVJS apps by making direct replacements to your .xml files. Designate areasof your page to be replaced by Target content by using the custom ADBTarget XML element.


• Getting Started• Configuring Your Mbox in Target• Configuring Your ADBTarget Element• Examples

Prerequisite: Before using the ADBTarget element in your TVML pages, you must configure your TVML/TVJS app to usethe tvOS SDK. For more information, see Apple TV Implementation with tvOS.

Getting Started

1. Identify the .xml file in which you want to use your Target location.2. Add an ADBTarget element to the file as a child of the <document> element.3. If Target fails to find your Mbox location, or it times out, the value between your <ADBTarget> and </ADBTarget> tags

is used as default content.

Configuring Your Mbox in Target

The returned content from Target replaces all content between <ADBTarget> and </ADBTarget>, including both ADBTargettags.

Tip: You should plan what you want to replace accordingly.

Your use case might be as simple as replacing a string value in a label or as complex as replacing an entire page.

Configuring Your ADBTarget Element

In the ADBTarget element, you must provide the Mbox name in the mbox property. You can optionally add custom propertiesto your request in the customParameterName="customParameterValue" format.

Required?Property ValueProperty TypeProperty Name

YesName of your Mbox locationStringmbox

NoOrder IDStringid

NoOrder TotalStringtotal


Required?Property ValueProperty TypeProperty Name

NoA comma-separated list of purchased product IDs for this order.

For example:purchasedProductIds="product1,product2,product3"

StringpurchasedProductIds

NoA list of key-value pairs for mboxParameters. Each entry in thisstring is separated by a semicolon (;), and key-values are separatedby a colon : .

StringmboxParameters

For example:

mboxParameters="mboxparameterKey:mboxParameterValue;mboxParameterKey1:mboxParameterValue1;mboxParameterKey2:mboxParameterValue2"

NocustomParameterValueStringcustomParameterName

Examples

Example 1

The following example uses an ADBTarget element in the LandingPage.xml.js page to replace the contents of an alert:

Configure Target

Assume that you have an Mbox location named landingPage and the offer content is set to be the following:<title>My cool landing page</title><description>Thanks for coming to my page</description>

Configure landingPage.xml.js

• Here is the configuration for landingPage.xml.js:<alertTemplate> <ADBTarget mbox="landingPage"> <title>TargetTestPage</title> <description>Load fail or timeout (defaultContent)</description> </ADBTarget> </alertTemplate>

• If the request to Target is successful, and your offer content is returned, your page will result with:<alertTemplate> <title>My cool landing page</title> <description>Thanks for coming to my page</description></alertTemplate>

• If the Target server cannot be reached or the request times out, your page will result with:<alertTemplate> <title>TargetTestPage</title> <description>Load fail or timeout (defaultContent)</description></alertTemplate>

Example 2

The following example illustrates how to add custom data to your ADBTarget element. This method lets you create conditionalexperiences and offer content for this Mbox location in Target:<alertTemplate> <ADBTarget mbox="landingPage" customData="custom data" moreCustomData="more custom data"> <title>TargetTestPage</title> <description>Load fail or timeout (defaultContent)</description>


</ADBTarget> </alertTemplate>

TVJS Methods

Here is a list of TVJS methods that are provided by the tvOS library.

This section contains the following information

• Configuration Methods• Analytics Methods• Audience Manager Methods• ID Service Methods• Target Methods


DescriptionMethod

Returns the current version of the Adobe Mobile library.version

• Syntax:version()

• Returns: String

• Parameters: None

• Example:var sdkVersion = ADBMobile.version();

Returns the NSUInteger representation of the privacy status enum for current user.privacyStatus

Here are the options:

• ADBMobilePrivacyStatusOptIn (1): Hits are sent immediately.

• ADBMobilePrivacyStatusOptOut (2): Hits are discarded.

• ADBMobilePrivacyStatusUnknown (3): If offline tracking is enabled, hits aresaved until the privacy status changes to opt-in (then hits are sent) or opt-out (thenhits are discarded).

If offline tracking is not enabled, hits are discarded until the privacy status changes toopt-in.

• Default: The default value is set in ADBMobileConfig.json.

• Syntax:privacyStatus()

• Returns: Number


• Example:var privacyStatus = ADBMobile.privacyStatus();


DescriptionMethod

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

• ADBMobilePrivacyStatusOptIn: Hits are sent immediately.

• ADBMobilePrivacyStatusOptOut: Hits are discarded.

• ADBMobilePrivacyStatusUnknown: If offline tracking is enabled, hits are saveduntil the privacy status changes to opt-in (then hits are sent) or opt-out (then hits arediscarded).

If offline tracking is not enabled, hits are discarded until the privacy status changes toopt-in.

• Syntax:setPrivacyStatus(privacyStatus)

• Returns: N/A

• Parameters:

Type: ADBMobilePrivacyStatusprivacyStatus

New privacy status for this user.

• Example:ADBMobile.setPrivacyStatus(ADBMobilePrivacyStatusOptIn);

Returns the lifetime value of the current user.lifetimeValue

• Default: 0

• Syntax:lifetimeValue()

• Returns: Number


• Example:var ltv = ADBMobile.lifetimeValue();

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

userIdentifier

Default: nil

Important: If your app upgrades from the Experience Cloud 3.x to 4.x SDK, theprevious custom or automatically generated visitor ID is retrieved and stored as thecustom user identifier. This preserves visitor data between SDK upgrades. For newinstallations on the 4.x SDK, user identifier is nil until set.


DescriptionMethod

• Syntax:userIdentifier()

• Returns: String


• Example:var uid = ADBMobile.userIdentifier();

Sets the user identifier.setUserIdentifier

• Syntax:setUserIdentifier(userId)

• Returns: N/A

• Parameters:

Type: StringuserID

New identifier for this user.

• Example:ADBMobile.setUserIdentifier(‘myUserId’);

Sets the IDFA in the SDK, and the IDFA will be sent in lifecycle if it has been set in theSDK. The IDFA can also be accessed in Signals (Postbacks).

setAdvertisingIdentifier

Important: Retrieve the IDFA from Apple APIs only if you are using an ad service.If you retrieve IDFA, and are not using it properly, your app might be rejected.

• Syntax:setAdvertisingIdentifier(idfa)

• Returns: N/A

• Parameters:

Type: Stringidfa

IDFA retrieved from Apple API.

• Example:ADBMobile.setAdvertisingIdentifier(‘myIdfa’);

Sets the debug logging preference.setDebugLogging


DescriptionMethod

• Syntax:setDebugLogging(logging)

• Returns: N/A

• Parameters:

Type: Boollogging

Value indicating whether the Adobe SDK should log to thedebug console.

• Example:ADBMobile.setDebugLogging(true);

Analytics Methods

DescriptionMethod

Tracks an app state with optional context data. States are the views that are available inyour app, such as home dashboard, app settings, cart, and so on. These states aresimilar to pages on a website, and trackState calls increment page views.

trackStateData

If the state is empty, it displays as app name app version (build) in reports. Ifyou see this value in reports, ensure you set the state in each trackState call.

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

• Syntax:trackStateData(stateName [, contextData])

• Returns: N/A

• Parameters:

Type: StringstateName

Page state name.

Type: ObjectcontextData

Additional context data for this hit.

• Example:ADBMobile.trackStateData(‘homepage’, {‘userid’:12345});


DescriptionMethod

Tracks an action in your app. Actions are the things that happen in your app that youwant to measure, such as logons, banner taps, feed subscriptions, and othermetrics.

trackActionData

• Syntax:trackActionData(actionName [, contextData])

• Returns: N/A

• Parameters:

Type: StringactionName

Name of the action being tracked.



• Example:ADBMobile.trackActionData(‘likeClicked’, {‘imageName’:’funnyKitty’});

Sends the current latitude and longitude coordinates.trackLocationWithLatLonData

Also uses points of interest (POI) that are defined in the ADBMobileConfig.jsonfile to determine whether the location that you entered as a parameter is within any ofyour POI. If the current coordinates are within a defined POI, a context data variable ispopulated and sent with the trackLocation call.

• Syntax:trackLocationWithLatLonData(lat, lon [, contextData]);

• Returns: N/A

• Parameters:

Type: Numberlat

Latitude of the location.

Type: Numberlon

Longitude of the location.




DescriptionMethod

• Example:ADBMobile.trackLocationWithLatLonData(43.36, -116.12, null);

Adds an amount to the user's lifetime value.trackLifetimeValueIncreaseJsData

• Syntax:trackLifetimeValueIncreaseJsData(increaseAmount)

• Returns: N/A

• Parameters:

Type: NumberincreaseAmount

Amount to add to the user's current lifetime value.

• Example:ADBMobile.trackLifetimeValueIncreaseJsData(5);

Start a timed action with name action.trackTimedActionStartData

If you call this method for an action that has already started, the previous timed actionis overwritten.


• Syntax:trackTimedActionStartData(name [, contextData])

• Returns: N/A

• Parameters:

Type: Stringname

Name of the timed action being started.



• Example:ADBMobile.trackTimedActionStartData(‘level1’, {‘userId’:42423});

Pass in data to update the context data that is associated with the given action.trackTimedActionUpdateData


DescriptionMethod

The data passed in is appended to the existing data for the given action, and if the samekey is already defined for action, the data is overwritten.


• Syntax:trackTimedActionUpdateData(name [, contextData])

• Returns: N/A

• Parameters:

Type: Stringname

Name of the timed action being updated.



• Example:ADBMobile.trackTimedActionUpdateData(‘level1’);

End a timed action.trackTimedActionEndJsLogic

If you provide a callback function, you can access the final time values. If no callback isprovided, or if the callback returns true, the Adobe SDK automatically sends a hit. Whena false is returned from the callback, the timed action hit will be suppressed.

• Syntax:trackTimedActionEndJsLogic(name [, callback])

• Returns: N/A

• Parameters:

Type: Stringname

Name of the timed action being ended

Type: function(inAppDuration, totalDuration, data)callback

Callback method that will have inAppDuration (number),totalDuration (number), and data (context data object) in itsparameters.

Note that you can suppress the final hit from being sent by theSDK by returning false in your callback function.


DescriptionMethod

• Example:ADBMobile.trackTimedActionEndJsLogic(‘level1’, function(inAppDuration, totalDuration, data) { // do something with final values return true; });

Returns whether a timed action is in progress.trackingTimedActionExistsJs

• Syntax:trackingTimedActionExistsJs(name)

• Returns: Bool

• Parameters:

Type: Stringname

Name of the timed action to check existence of.

• Example:var actionExists = ADBMobile.trackTimedActionExistsJs(‘level1’);

Returns the automatically generated visitor identifier.trackingIdentifier

This is an app-specific unique visitor ID that is generated by Adobe’s servers. If Adobe'sservers cannot be reached at the time of generation, the ID is generated by using Apple'sCFUUID. The value is generated at the initial launch and is stored and used from thatpoint. This ID is preserved between app upgrades, is saved and restored during thestandard application back up process, and is removed when the app is uninstalled.

Tip: If your app upgrades from the Experience Cloud 3.x to 4.x SDK, the previouscustom or automatically generated visitor ID is retrieved and stored as the customuser identifier. This preserves visitor data between SDK upgrades. For newinstallations on the 4.x SDK, the user identifier is nil, and the tracking identifieris used. For more information, see the userIdentifier row below.

• Syntax:trackingIdentifier()

• Returns: String


• Example:var trackingId = ADBMobile.trackingIdentifier();

Forces the library to send all hits in the offline queue no matter how many are currentlyqueued.

trackingSendQueuedHits


DescriptionMethod

• Syntax:trackingSendQueuedHits()

• Returns: N/A


• Example:ADBMobile.trackingSendQueuedHits();

Clears all hits from the offline queue.trackingClearQueue

• Syntax:trackingClearQueue()

• Returns: N/A


• Example:ADBMobile.trackingClearQueue();

Retrieves the number of hits currently in the offline queue.trackingGetQueueSize

• Syntax:trackingGetQueueSize()

• Returns: Number


• Example:var queueSize = ADBMobile.trackingGetQueueSize();


DescriptionMethod

Returns the visitor profile that was most recently obtained.audienceVisitorProfile

Returns null if no signal has been submitted yet. The visitor profile is saved inNSUserDefaults for easy access across multiple launches of your app.

• Syntax:audienceVisitorProfile()

• Returns: Object


• Example:var profile = ADBMobile.audienceVisitorProfile();


DescriptionMethod

Returns the current DPID.audienceDpid

• Syntax:audienceDpid()

• Returns: String


• Example:var dpid = ADBMobile.audienceDpid();

Returns the current DPUUID.audienceDpuuid

• Syntax:audienceDpuuid()

• Returns: String


• Example:var dpuuid = ADBMobile.audienceDpuuid();

Sets the dpid and dpuuid, and if they are set, they are sent with each signal.audienceSetDpidDpuuid

• Syntax:audienceSetDpidDpuuid(dpid, dpuuid)

• Returns: N/A

• Parameters:

Type: Stringdpid

Audience Manager data provider ID.

Type: Stringdpuuid

Identifier for the user and data provider combination.

• Example:ADBMobile.audienceSetDpidDpuuid(‘myDpid’, ‘userDpuuid’);

Sends Audience Manager a signal with traits and gets the matching segments that arereturned in a callback function.

audienceSignalWithDataJsCallback

• Syntax:audienceSignalWithDataJsCallback(traits [, callback])

• Parameters:


DescriptionMethod

Type: Objecttraits

Traits dictionary for this user.

Type: function(profile)callback

The profile returned from Audience Manager in the parameterfor the callback function.

• Example:ADBMobile.audienceSignalWithDataJsCallback({‘trait’:’something’}, function(profile) { // do something with the user’s segments found in profile });

Resets the Audience Manager UUID and purges the current visitor profile.audienceReset

• Syntax::audienceReset()

• Returns: N/A


• Example:ADBMobile.audienceReset();

ID Service Methods

DescriptionMethod

Retrieves the Experience Cloud ID from the ID service.visitorMarketingCloudID

• Syntax:visitorMarketingCloudID()

• Returns: String


• Example:var mcid = ADBMobile.visitorMarketingCloudID();

In addition to the Experience Cloud ID, you can set additional customer IDs to beassociated with each visitor. The Visitor API accepts multiple Customer IDs for the same

visitorSyncIdentifiers

visitor, with a customer type identifier to separate the scope of the different customerIDs. This method corresponds to setCustomerIDs in the JavaScript library.


DescriptionMethod

• Syntax:visitorSyncIdentifiers(identifiers)

• Returns: N/A

• Parameters:

Type: Objectidentifiers

Identifiers to sync to the ID service for this user.

• Example:ADBMobile.visitorSyncIdentifiers({‘idType’:’idValue’});

Synchronizes the provided identifiers to the ID service.visitorSyncIdentifiersAuthenticationState

• Syntax:visitorSyncIdentifiersAuthenticationState(identifiers, authState)

• Returns: N/A

• Parameters:

Type: Objectidentifiers

Identifiers to sync to the ID service for this user.

Type: ADBMobileVisitorAuthenticationStateauthState

Authentication state of the user. Possible values include:


• Example:ADBMobile.visitorSyncIdentifiersAuthenticationState({'myIdType':'valueForUser'}, ADBMobileVisitorAuthenticationStateLoggedOut);

Synchronizes the provided identifier type and value to the ID service.visitorSyncIdentifierWithTypeIdentifierAuthenticationState

• Syntax:visitorSyncIdentifierWithTypeIdentifierAuthenticationState(idType, identifier, authState)

• Returns: N/A

• Parameters:


DescriptionMethod

Type: StringidType

Type of identifier you are syncing.

Type: Stringidentifier

Value of the identifier you are syncing.

Type: ADBMobileVisitorAuthenticationStateauthState

Authentication state of the user. Possible values include:


• Example:ADBMobile.visitorSyncIdentifierWithTypeIdentifierAuthenticationState('myIdType', 'valueForUser', ADBMobileVisitorAuthenticationStateAuthenticated);

Retrieves an array of read-only ADBVisitorID objects. The following code sample isan example of a VisitorID object:{ idType: "abc",

visitorGetIDsJs

authenticationState: 1, identifier: "123"}

Syntax:visitorGetIDsJs()

Returns: Array[Object]

Parameters: None

Example:var myVisitorIds = ADBMobile.visitorGetIDsJs();

Target Methods

DescriptionMethod

Returns the third-party ID.targetThirdPartyID

• Syntax:targetThirdPartyID()

• Returns: String



DescriptionMethod

• Example:var thirdPartyID = ADBMobile.targetThirdPartyID();

Sets the third-party ID.targetSetThirdPartyID

• Syntax:targetSetThirdPartyID(thirdPartyID)

• Returns: N/A

• Parameters:

Type: StringthirdPartyID

Third-party ID to use for target requests.

• Example:ADBMobile.targetSetThirdPartyID(‘thirdPartyID’);

Returns the PcID.targetPcID

• Syntax:targetPcID()

• Returns: String


• Example:

var pcID = ADBMobile.targetPcID();

Returns the session ID.targetSessionID

• Syntax:targetSessionID()

• Returns: String


• Example:var sessionID = ADBMobile.targetSessionID();


iOS Extension ImplementationYou can use the iOS extension helps you collect usage data from your Apple Watch Apps (WatchOS 1), Today Widgets, PhotoEditing widgets, and other iOS extension apps.


• Recommendations for Using the iOS SDK Instead of Your Wrapper• Getting Started• Additional Notes

Recommendations for Using the iOS SDK Instead of Your Wrapper

Important: We strongly recommend that you use the iOS SDK rather than using your wrapper.

Apple provides a set of APIs that lets the Watch app communicate with the containing app by sending requests to the containingapp and receiving the responses. Although you can send tracking data as a dictionary from the Watch app to the containing appand call any tracking method on the containing app to send the data, this solution has limitations.

In most cases when a user is using the Watch app, the containing app is running in the background, and it is only safe to callTrackActionInBackground, TrackLocation, and TrackBeacon. Calling other tracking methods interferes with lifecycledata, so you should use only these three methods to send the data from Watch app.

Even if these three tracking methods meet your requirements, use the iOS SDK, because the SDK for the Watch app includesall Mobile features except in-app messaging.

Getting Started

Prerequisite: Ensure that you have a project with at least the following targets:

• One target to contain the app.• One target for the extension.

If you are working on a WatchKit app, you should have a third target. For more information on developing for Apple Watch,see Developing for Apple Watch in the Apple Watch Programming Guide.

Configuring the Containing App


1. Drag the AdobeMobileLibrary folder into your project.2. Ensure that ADBMobileConfig.json is a member of the containing app's target.3. On the Build Phases tab of your containing app's target, expand the Link Binary with Libraries section and add the following

libraries:

• AdobeMobileLibrary.a• libsqlite3.dylib• SystemConfiguration.framework

4. Open the Capabilities tab of the containing app's target, enable App Groups, and add a new app group (for example,group.com.adobe.testApp).

119iOS Extension Implementation

https://developer.apple.com/library/ios/documentation/General/Conceptual/WatchKitProgrammingGuide/index.html#//apple_ref/doc/uid/TP40014969-CH8-SW1

5. In your application delegate, set the app group in application:didFinishLaunchingWithOptions before makingany interactions with the Adobe Mobile library:

[ADBMobile setAppGroup:@"group.com.adobe.testApp"];

6. Confirm that your app builds without unexpected errors.

Configuring the Extension

1. Ensure that ADBMobileConfig.json is a member of the extension's target.2. On the Build Phases tab of your extension’s target, expand the Link Binary with Libraries section and add the following

libraries:

• AdobeMobileLibrary_Extension.a• libsqlite3.dylib• SystemConfiguration.framework

3. Open the Capabilities tab of the extension's target, enable App Groups, and select the app group that you added in step 4of Configuring the Containing App above.

4. In your InterfaceController, set the app group in awakeWithContext: before making any other interactionswith the Adobe Mobile library:[ADBMobile setAppGroup:@"group.com.adobe.testApp"];


Additional Notes

Here is some information to remember:

• An additional context data value, a.RunMode has been added to indicate whether the data comes from your containing appor your extension:

• a.RunMode = Application

This value means that the hit came from the containing app.

• a.RunMode = Extension

This value means that the hit came from the extension.

• If you upgrade from a older version of the SDK, when the containing app is launched, Adobe automatically migrates all theuser defaults and cached files from the containing app's folder to the app group's shared folder.

• If the containing app is never launched, hits from the extension are discarded.• The version number and build number must be the same between your containing app and the extension app.• No lifecycle call is triggered on iOS extension apps.

Stand-Alone Extension Implementation

Starting with iOS 10, Apple allows you to create an extension called a stand-alone extension that can be distributed without acontaining app. With this extension, you do not need an app group, as there is no containing app with which to share data.

Important: Mobile SDK version 4.13.0 or above is required to use stand-alone extensions.



• Configure your stand-alone extension for use with the SDK• Additional Notes

Configure your stand-alone extension for use with the SDK

To configure your stand-alone extension:

1. Ensure that ADBMobileConfig.json is a member of your extension's target.2. Link the following libraries and frameworks:

• AdobeMobileLibrary_Extension.a• libsqlite3.tbd• SystemConfiguration.framework

3. In the main view controller of your extension, set the extension type to ADBMobileAppExtensionTypeStandAlone inthe SDK before completing any SDK-related activities.[ADBMobile setAppExtensionType:ADBMobileAppExtensionTypeStandAlone];


Additional Notes

Here is some additional information:

• An additional context data value, a.RunMode has been added to indicate whether the data comes from your containing appor your extension:

• a.RunMode = Application

This value means that the hit came from the containing app.

• a.RunMode = Extension

This value means that the hit came from the extension.

• No lifecycle call is triggered on iOS extension apps.


Apple Watch Implementation with WatchOS 2Starting with WatchOS 2, your WatchKit Extensions will run on an Apple Watch device. Applications that run in this environmentrequire the WatchConnectivity framework to share data with their containing iOS app.

Tip: Starting with AdobeMobileLibrary v4.6.0, WatchConnectivity is supported.


• Getting Started• Configuring the Containing App• Configuring the WatchKit Extension• Additional Information

Getting Started

Prerequisite: Ensure that you have a project with at least the following targets:

• The containing app• The WatchKit app• The WatchKit extension

For more information about developing WatchKit apps, see The Watch App Architecture.

Configuring the Containing App



2. Ensure that ADBMobileConfig.json is a member of the containing app’s target.

3. In the Build Phases tab of your containing app’s target, expand the Link Binary with Libraries section and add the followinglibraries:

• AdobeMobileLibrary.a• libsqlite3.tbd• SystemConfiguration.framework

4. In your class that implements the UIApplicationDelegate protocol, add the WCSessionDelegate protocol.#import <WatchConnectivity/WatchConnectivity.h>@interface AppDelegate : UIResponder <UIApplicationDelegate, WCSessionDelegate>

5. In the implementation file of your app delegate class, import the AdobeMobileLibrary.#import “ADBMobile.h”

6. Before making a call to the ADBMobile library, in application:didFinishLaunchingWithOptions: of your appdelegate, configure your WCSession.// check for session availabilityif ([WCSession isSupported]) { WCSession *session = [WCSession defaultSession]; session.delegate = self; [session activateSession];}

122Apple Watch Implementation with WatchOS 2

https://developer.apple.com/library/ios/documentation/General/Conceptual/WatchKitProgrammingGuide/DesigningaWatchKitApp.html#//apple_ref/doc/uid/TP40014969-CH3-SW1

7. In your app delegate, implement the session:didReceiveMessage: and session:didReceiveUserInfo: methods.

syncSettings: is called in the ADBMobile library, which returns a bool that indicates whether the dictionary was meantfor consumption by the ADBMobile library. If it returns No, the message was not initiated from the Adobe SDK.

- (void) session:(WCSession *)session didReceiveMessage:(NSDictionary<NSString *,id> *)message { // pass message to ADBMobile if (![ADBMobile syncSettings:message]) { // handle your own custom messages }}

- (void) session:(WCSession *)session didReceiveUserInfo:(NSDictionary<NSString *,id> *)userInfo { // pass userInfo to ADBMobile if (![ADBMobile syncSettings:userInfo]) { // handle your own custom messages }}

Configuring the WatchKit Extension

1. Ensure that ADBMobileConfig.json is a member of your WatchKit extension’s target.

2. In the Build Phases tab of your WatchKit extension’s target, expand the Link Binary with Libraries section and add thefollowing libraries:

• AdobeMobileLibrary_Watch.a• libsqlite3.tbd

3. In your class that implements the WKExtensionDelegate protocol, import WatchConnectivity and add theWCSessionDelegate protocol.#import <WatchConnectivity/WatchConnectivity.h>@interface ExtensionDelegate : NSObject <WKExtensionDelegate, WCSessionDelegate>

4. In the implementation file of your extension delegate class, import the AdobeMobileLibrary.#import “ADBMobile.h”

5. In applicationDidFinishLaunching of your extension delegate, configure your WCSession before making any callsto the ADBMobile library.// check for session availabilityif ([WCSession isSupported]) { WCSession *session = [WCSession defaultSession]; session.delegate = self; [session activateSession];}

6. In applicationDidFinishLaunching of your extension delegate, initialize the watch app for the SDK.[ADBMobile initializeWatch];

7. In your extension delegate, implement the session:didReceiveMessage: and session:didReceiveUserInfo:methods.

syncSettings: is called in the ADBMobile library, which returns a bool that indicates whether the dictionary was meantfor consumption by the ADBMobile library. If it returns NO, the message was not initiated from the Adobe SDK.

- (void) session:(WCSession *)session didReceiveMessage:(NSDictionary<NSString *,id> *)message { // pass message to ADBMobile if (![ADBMobile syncSettings:message]) {


// handle your own custom messages }}

- (void) session:(WCSession *)session didReceiveUserInfo:(NSDictionary<NSString *,id> *)userInfo { // pass userInfo to ADBMobile if (![ADBMobile syncSettings:userInfo]) { // handle your own custom messages }}



• For WatchKit apps, a.RunMode will be set to Extension.

• Because WatchKit apps run on the watch, the apps will correctly report their names in a.AppID.

• No lifecycle call is triggered on WatchOS2 apps.


iOS SDK ReferenceThis reference material helps you use the iOS SDK for Experience Cloud Solutions.

App IDs

The following table describes the different app identifiers that are used by the iOS 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 use this value to filterthe results 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 ID is a unique ID that is assigned to the app instance by Adobe Mobile services for all the associatedmetadata in your system.

AppID in ADBMobileJSON Config

This ID is used to create the unique URLs for acquisition tracking or tracking link, is automaticallyadded to the ADBMobile JSON config file when downloaded from the UI, and can be found in ManageApp Settings under the Acquisition settings for your app.

Visitor Tracking Between an App and Mobile Web

If your app opens mobile web content, you need to ensure that visitors are not identified separately as they move between thenative and mobile web.

Visitor IDs in Apps

The iOS SDK generates a unique visitor ID when an app is installed. This ID is stored in persistent memory on the mobile deviceand is sent with every hit. This ID 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 withindesktop 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.

To use the same visitor ID in the app and mobile web, complete the following instructions to pass the app visitor ID to themobile web in the URL.

Implementing Visitor Tracking Between an App and Mobile Web

1. Add the library to your project and implement lifecycle.

125iOS SDK Reference

2. To append visitor information to the URL that is being used to open the web view, call visitorAppendToURL:NSURL *url = [NSURL URLWithString:@”http://www.mydomain.com/index.php"];NSURL *urlWithVisitorData = [ADBMobile visitorAppendToURL:url];[[UIApplication sharedApplication] openURL:urlWithVisitorData];

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 ID service code on the destination page uses the passed-in MID to track the visitor.

On hits from the mobile web content, verify that the mid parameter is present on each hit, and that this value matches the midthat is being sent by the app code.

Troubleshooting Visitor Tracking

AnswerQuestion

Verify that the Adobe SDK that is bundled in the parentapplication is version 4.12.0 or higher.

I do not see [ADBMobile visitorAppendToURL:].

Verify the following:I do not see Adobe IDs in my URL.

• The URL string that is being used to open the web view wasgenerated by [ADBMobile visitorAppendToURL:].

• The Adobe IDs are encoded.

To verify IDs are appended to the URL that is being opened,look for the adobe_mc query parameter.

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 [ADBMobile visitorAppendToURL:].

• 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 Client Care; be prepared to share a sample applicationand the associated site so that Adobe can validate the implementation.

iOS Device Versions

The following table contains the iOS version string that is sent by many iOS devices.

Important: This list is based on internal tests and online information and might contain inaccuracies or incompleteinformation.

For more information about iOS devices, go to sites such as The iPhone Wiki.


http://theiphonewiki.com/wiki/Models

VersioniPhone

iPhone1,1Original

iPhone1,23G

iPhone2,13GS

iPhone3,14 (GSM) (shipped withfirmware 4.0)

iPhone3,24 (GSM) (shipped withfirmware 6.0)

iPhone3,34 (CDMA)

iPhone4,14S

iPhone5,15 (GSM)

iPhone5,25 (CDMA)

iPhone5,35C (GSM)

iPhone5,45C (Global)

iPhone6,15S (GSM)

iPhone6,25S (Global)

iPhone7,16 Plus

iPhone7,26

iPhone8,26s Plus

iPhone8,4SE (United States)

iPhone9,17 (CDMA)

iPhone9,27 Plus (CDMA)

iPhone9,37 (GSM)

iPhone9,47 Plus (GSM)

VersioniPod Touch

iPod1,11st generation

iPod2,12nd generation

iPod3,13rd generation

iPod4,14th generation



VersioniPad

iPad1,1Original

iPad2,1iPad 2

iPad2,2iPad 2 (GSM)


iPad2,3iPad 2 (CDMA)

iPad2,4iPad 2 (New 16GB)

iPad2,5iPad Mini (WiFi)

iPad2,6iPad Mini (GSM)

iPad2,7iPad Mini, Global version (thesame as the GSM iPad Mini,but includes an additionalcellular radio: CDMA EV-DORev. A and Rev. B (3.5G) )

iPad3,1iPad 3 (WiFi)

iPad3,2iPad 3 (CDMA)

iPad3,3iPad 3 (GSM)

iPad3,4iPad 4 (WiFi)

iPad3,5iPad 4 (GSM)

iPad3,6iPad 4, Global version (thesame as the GSM 4th gen iPad,but includes an additionalcellular radio: CDMA EV-DORev. A and Rev. B (3.5G) )

iPad4,1iPad Air (WiFi)

iPad4,2iPad Air (LTE)

iPad4,3iPad Air (CDMA)

iPad4,4iPad Mini 2 (WiFi)

iPad4,5iPad Mini 2 (LTE)

iPad4,6iPad Mini 2 (China)

iPad4,7iPad Mini 3 (Wi-Fi)

iPad4,8iPad Mini 3 (CDMA)

iPad4,9iPad Mini 3 (GSM)

iPad5,1iPad Mini 4 (Wi-Fi)

iPad5,2iPad Mini 4 (LTE)

iPad5,3iPad Air 2 (Wi-Fi)

iPad5,4iPad Air 2 (LTE)

iPad6,3iPad Pro, 9.7 inches (Wi-Fi)

iPad6,4iPad Pro, 9.7 inches (LTE)



iPad6,11iPad 5, 9.7 inches (Wi-Fi)

iPad6,12iPad Pro 5, 9.7 inches (LTE)


iPad7,1iPad Pro 2, 12.9 inches(Wi-Fi)

iPad7,2iPad Pro 2, 12.9 inches (LTE)




Privacy and General Data Protection RegulationExperience Cloud Mobile SDKs provide General Data Protection Regulation (GDPR)-ready APIs for Controllers that allowusers to retrieve locally stored identities and set opt status flags for data collection and transmission.

Important: GDPR is supported only in Mobile SDK version 4.15 or later.

When Adobe provides software and services to an enterprise, Adobe acts as a data processor for any personal data it processesand stores as part of providing these services. As a data processor, Adobe processes personal data in accordance with yourcompany’s permission and instructions (for example, as set out in your agreement with Adobe).

As a data controller, you can use Adobe Mobile Services SDKs to support GDPR retrieve and delete requests from your mobileapps.

For the Adobe Mobile SDK portions of your mobile apps, you can use the following settings and methods:

• To retrieve data from the SDKs, and send this data to your servers, use the getAllIdentifiersAsync method.

For more information, see Retrieving Stored Identifiers.

• To set your opt status and help you with a GDPR data deletion request, use the following settings:

• privacyDefault• setPrivacyStatus

For more information, see Setting the User's Opt Status.

For more information about GDPR, see GDPR and Your Business.

Retrieving Stored Identifiers

This information helps you retrieve locally stored, Experience Cloud SDK identities from your iOS app and with GDPR dataaccess requests.

For more information about GDPR, see GDPR and Your Business.

Important: The getAllIdentifiersAsync method retrieves identities stored in the Experience Cloud SDKs. You mustcall this method before the user opts-out.

Experience Cloud SDK identities (as applicable) are locally stored and returned in a JSON string, which might contain:

• Company Context - IMS Org IDs• User IDs• Marketing Cloud ID (MCID)• Integration Codes (ADID, Push ID)• Data Source IDs (DPID, DPUUID)• Analytics IDs (AVID, AID, VID, and associated RSIDs)• Target Legacy IDs (TNTID, TNT3rdpartyID)• Audience Manager ID (UUID)

130Privacy and General Data Protection Regulation

https://www.adobe.com/privacy/general-data-protection-regulation.html

https://www.adobe.com/privacy/general-data-protection-regulation.html

Here is an example of the ADBMobile getAllIdentifiersAsync method in iOS:

[ADBMobile getAllIdentifiersAsync:^(NSString * _Nullable content){ NSLog(content) }]

Setting the User's Opt Status

This information helps you with a GDPR data deletion request.

Important: Starting with Experience Cloud iOS SDKs 4.15 , setting the privacy status to unknown holds Audience Managerand Experience Cloud ID hits.

You can control whether Analytics, Target, and Audience Manager activity is allowed on a device by using the following settings:

• privacyDefault in ADBMobile JSON Config.

This setting controls the initial setting that persists until it is changed in code.

• setPrivacyStatus method.

After the privacy setting is changed by using this method, the change is permanent until it is changed again by using thismethod, or when you uninstall 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

ADBMobilePrivacyStatusOptInoptedinOpt in• Analytics: Hits are sent.

• Target: Mbox requests are sent.

• Audience Manager: Signals and ID syncs aresent.

ADBMobilePrivacyStatusOptOutoptedoutOpt out• Analytics: Hits are discarded.

• Target: Mbox requests are not allowed.

• Audience Manager: Signals and ID syncs arenot allowed.

ADBMobilePrivacyStatusUnknownoptunknownUnknown• Analytics: If offline tracking is enabled, hits are

saved until the privacy status changes to opt-in(hits are sent) or opt-out (hits are discarded).

If offline tracking is not enabled, hits arediscarded until the privacy status changes toopt-in.

• Target: Mbox requests are sent.


Value in setPrivacyStatusValue in JSONConfig

DescriptionSetting

• Audience Manager: Signals and ID syncs aresent.

Examples- (IBAction) setPrivacyOptIn { [ADBMobile setPrivacyStatus:ADBMobilePrivacyStatusOptIn];}- (IBAction) setPrivacyOptOut { [ADBMobile setPrivacyStatus:ADBMobilePrivacyStatusOptOut];}- (IBAction) setPrivacyOptUnknown { [ADBMobile setPrivacyStatus:ADBMobilePrivacyStatusUnknown];}


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


133Using Bloodhound to Test Mobile Applications

https://marketing.adobe.com/resources/help/en_US/mobile/bloodhound/

https://marketing.adobe.com/resources/help/en_US/mobile/bloodhound_win_2x/

PhoneGap Plug-inThis plug-in lets you send iOS AppMeasurement calls from your PhoneGap project.

To create a PhoneGap project, see PhoneGap Getting Started with iOS.


• Installing the plug-in using npm:• Manually installing the plug-in• Implement Custom Tracking

Installing the plug-in using npm:

1. Run the following command:cordova plugin add adobe-mobile-services

Manually installing the plug-in

Include the AppMeasurement Library

To include the AppMeasurement:

1. Drag ADBMobile_PhoneGap.h and ADBMobile_PhoneGap.m into the Plugins folder in your Xcode project.

2. Complete the following settings:

1. Select Copy items into destination group's folder (if needed).2. Select the targets where you want to use AppMeasurement code.

3. Drag ADB_Helper.js into the www folder in your project.

4. In the res/xml folder, open config.xml and register an new plugin by adding the following:<feature name="ADBMobile_PhoneGap"> <param name="ios-package" value="ADBMobile_PhoneGap" /></feature>

Add App Permissions

The AppMeasurement library requires the following:

1. Launch the Xcode IDE and open your app.

2. Drag the AdobeMobile folder into your Xcode project and complete the following settings:

1. Select Copy items into destination group's folder (if needed).2. Select Create groups for any added folders.3. Select the targets where you want to use AppMeasurement code and click Finish.

134PhoneGap Plug-in

http://docs.phonegap.com/getting-started/

3. In the Build Phases tab of your project’s target, expand the Link Binary with Libraries section and add the following libraries:

• libsqlite3.dylib• SystemConfiguration.framework


Implement Custom Tracking

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>

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

135PhoneGap Plug-in

• ID service

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>


• Configuration Methods• PII Methods• Tracking Methods• Target Methods• Acquisition Methods• Advertising Identifier• Audience Manager Methods• ID Service Methods


DescriptionMethod

Returns the privacy status for current user.getPrivacyStatus

Here are the available statuses:

• ADB.optedIn, where hits are sent immediately.• ADB.optedOut, where 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. Set to one of the following values:setPrivacyStatus

You can set one of the following statuses:

• ADB.optedIn, where hits are sent immediately.• ADB.optedOut, where 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.

Example:ADB.setPrivacyStatus('ADB.optedIn');

136PhoneGap Plug-in

DescriptionMethod

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 initially launchedand is stored and used from that point forward. This ID is preserved between app upgrades,and is removed when the app is uninstalled.

Tip: If your app upgrades from the Experience Cloud 3.x to 4.x SDK, the previousvisitor ID (custom or automatically generated) is retrieved and stored as the customuser identifier (see the getUserIdentifier row below). This preserves visitordata between upgrades of the SDK.

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

Returns the custom user identifier if a custom identifier has been set, and returns nullif a custom identifier has not been set.

getUserIdentifier

The default value is null.

Example:getUserIdentifier(function (value) { myTempVal = value; }, function () { myTempVal = null; });

Sets the user identifier to identifier.setUserIdentifier

137PhoneGap Plug-in

DescriptionMethod

Example:ADB.setUserIdentifier('testUser');

Sets the device token for push notifications.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. Warning: use caution whenclearing the queue manually as it cannot be reversed.

trackingClearQueue

Example:ADB.trackingClearQueue(function (value) { myTempVal = value; }, function () { myTempVal = null; });

Indicates to the SDK that your next resume from background should not start a newsession, regardless of the value of lifecycle session timeout in your config file.

keepLifecycleSessionAlive

Important: this method is intended to be used for apps that register for notificationswhile in background and should only be called from your code that runs while yourapp is in the background.

138PhoneGap Plug-in

DescriptionMethod

Example:ADB.keepLifecycleSessionAlive();

Indicates to the SDK that lifecycle data should be collected for use across all solutions inthe SDK. For more information, see Lifecycle Metrics.

collectLifecycleData

Example:ADB.collectLifecycleData();

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 a push message click-through.trackPushMessageClickthrough

Syntax:ADB.trackPushMessageClickthrough(userInfo, success, fail);

Example:ADB.trackPushMessageClickthrough({'k1':'v1','k2':'v2','k3':'v3'},function (value) { alert('success'); },function (value) { alert('fail'); });

139PhoneGap Plug-in

DescriptionMethod

Tracks a local notification message click-through.trackLocalNotificationClickThrough

Syntax:ADB.trackLocalNotificationClickThrough(userInfo, success, fail);

Example:ADB.trackLocalNotificationClickThrough({'k1':'v1','k2':'v2','k3':'v3'}, 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 home dashboard, app settings, cart, and so on. These statesare 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 are the things that happen in your app that youwant to measure, include logins, banner taps, feed subscriptions and othermetrics.

trackAction

Syntax:ADB.trackAction(string action[,JSON cData]);

Example:ADB.trackAction("login");

ADB.trackAction("login", {"user":"john","remember":"true"});

Tracks an action that occurred in the background. This suppresses lifecycle events fromfiring in certain scenarios.

trackActionFromBackground

Syntax:ADB.trackActionFromBackground(string action[,JSON cData]);

Example:ADB.trackActionFromBackground("login");

ADB.trackActionFromBackground("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

140PhoneGap Plug-in

DescriptionMethod

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 name action.trackTimedActionStart

If you call this method for an action that has already started, the previous timed actionis overwritten.


Syntax:ADB.trackTimedActionStart(action[,JSON cData]);

Example:ADB.trackTimedActionStart("cartToCheckout");

Pass in cData to update the context data associated with the given action.trackTimedActionUpdate

The cData passed in is appended to the existing data for the given action, and overwritesthe data if the same key is already defined for action.


Syntax:ADB.trackTimedActionUpdate(String action[,JSON cData]);

Example:ADB.trackTimedActionUpdate("cartToCheckout",{'SampleContextDataKey3':'SampleContextDataVal3','SampleContextDataKey4':'SampleContextDataVal4'});

End a timed action.trackTimedActionEnd

Example:ADB.trackTimedActionEnd("cartToCheckout");

141PhoneGap Plug-in

DescriptionMethod

Returns whether or not a timed action is in progress.trackingTimedActionExists

Syntax:ADB.trackingTimedActionExists(function (value) { myTempVal = value; }, function () { myTempVal = null; });

Target Methods

DescriptionMethod

Sends 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'});

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

142PhoneGap Plug-in

DescriptionMethod

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 Target server.targetSessionID

Syntax:ADB.targetSessionID (success, fail);

Example:ADB.targetSessionID(function (value) { alert(value); },function (value) { alert('fail'); });

Gets the value of the PcID cookie 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

143PhoneGap Plug-in

DescriptionMethod

Syntax:ADB.targetThirdPartyID(success, fail);

Example:ADB.targetThirdPartyID(function (value) { alert(value); },function (value) { alert('fail'); });

Acquisition Methods

DescriptionMethod

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 redirectyourself (such as with an SKStoreView).

acquisitionCampaignStartForApp

Syntax:ADB.acquisitionCampaignStartForApp(appId, data, success, fail);

Example:ADB.acquisitionCampaignStartForApp('0652024f-adcd-49f9-9bd7-2552a4564d2f', {'extraDataKey':'extraDataValue'}, success, fail);

Advertising Identifier

In the AppDelegate generated by Cordova, call [ADBMobile setAdvertisingIdentifier:] in theapplication:didFinishLaunchingWithOptions: delegate method.

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

144PhoneGap Plug-in

DescriptionMethod

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

Example:ADB.audienceSignalWithData(function() {}, function() {}, {‘key1’: ’value1’, ‘key2’: ‘value2’});

ADB.audienceSignalWithData({‘key1’: ’value1’, ‘key2’: ‘value2’});

Resets audience manager UUID and purges current visitor profile.audienceReset

Example:ADB.audienceReset();

ID Service Methods

DescriptionMethod

Returns the Experience Cloud ID from the ID service.visitorGetMarketingCloudId

Syntax:ADB.visitorGetMarketingCloudId(success, fail);

145PhoneGap Plug-in

DescriptionMethod

Example:ADB.visitorGetMarketingCloudId(function (value) { mcid = value; }, function () { mcid = null; });

Synchronizes the provided identifiers with the 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

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)

146PhoneGap Plug-in

DescriptionMethod

Example:ADB.visitorGetIDs(function (value) { alert(value); },function (value) { alert('fail'); });

147PhoneGap 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 Experience 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 Experience 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.

148Contact and Legal Information

http://helpx.adobe.com/marketing-cloud.html

https://twitter.com/AdobeExpCare

https://customers.omniture.com/login.php

http://helpx.adobe.com/marketing-cloud/contact-support.html

http://status.adobe.com/

https://my.omniture.com/login/?r=%2Fp%2Fsuite%2Fcurrent%2Findex.html%3Fa%3DIdeasExchange.Redirect%26redirectreason%3Dnotregistered%26referer%3Dhttp%253A%252F%252Fideas.omniture.com%252Ft5%252FAdobe-Idea-Exchange-for-Omniture%252Fidb-p%252FIdeaExchange3

https://my.omniture.com/login/?r=%2Fp%2Fsuite%2Fcurrent%2Findex.html%3Fa%3DIdeasExchange.Redirect%26redirectreason%3Dnotregistered%26referer%3Dhttp%253A%252F%252Fideas.omniture.com%252Ft5%252FAdobe-Idea-Exchange-for-Omniture%252Fidb-p%252FIdeaExchange3

https://marketing.adobe.com/resources/help/en_US/terms.html

http://www.adobe.com/privacy/policy.html

http://www.adobe.com/products/eula/third_party/

iOS SDK 4.x for Marketing Cloud Solutions - Adobe Marketing Cloud iOS SDK 4.x for Experience Cloud...

Documents

Transcript of iOS SDK 4.x for Marketing Cloud Solutions - Adobe Marketing Cloud iOS SDK 4.x for Experience Cloud...