Initialize the SDK and set up tracking

Configure SDK with the Launch Environment ID

To initialize the SDK, you need to first configure the SDK with an Environment ID from Launch.

To find your Environment ID, in Launch, go to the Environments tab and click on the icon that corresponds to the environment that you are setting up.

Android
Objective-C
Swift
React Native

Adobe Experience Platform SDK for Android supports Android 4.0 (API 14) or later.

Ensure app permissions

The SDK requires standard network connection permissions in your manifest to send data, collect cellular provider, and record offline tracking calls.

To add these permissions, add the following lines to your AndroidManifest.xml file, which is located in the application project directory:

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

Java

  1. In the app, create MainActivity.java .

  2. Add MobileCore.configureWithAppID("PASTE_ENVIRONMENT_ID_HERE");

Adobe Experience Platform SDK for iOS supports iOS 10 or later.

Objective-C

In Xcode, find your didFinishLaunchingWithOptions in AppDelegate.h and add:

[ACPCore configureWithAppId:@"PASTE_ENVIRONMENT_ID_HERE"];

Adobe Experience Platform SDK for iOS supports iOS 10 or later.

Swift

In Xcode, find your didFinishLaunchingWithOptions in AppDelegate.swift and add:

ACPCore.configure(withAppId: "PASTE_ENVIRONMENT_ID_HERE")

Initializing the SDK

It is recommended to initialize the SDK in your native code inside your AppDelegate and MainApplication in iOS and Android respectively, however you can still initialize the SDK in Javascript.

iOS

// Import the SDK
#import <RCTACPCore/ACPCore.h>
#import <RCTACPCore/ACPLifecycle.h>
#import <RCTACPCore/ACPIdentity.h>
#import <RCTACPCore/ACPSignal.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//...
[ACPCore configureWithAppId:@"yourAppId"];
[ACPCore setWrapperType:ACPMobileWrapperTypeReactNative];
[ACPIdentity registerExtension];
[ACPLifecycle registerExtension];
[ACPSignal registerExtension];
[ACPCore start:nil];
}

Android

@Override
public void onCreate() {
//...
MobileCore.setApplication(this);
MobileCore.configureWithAppID("yourAppId");
MobileCore.setWrapperType(WrapperType.REACT_NATIVE);
try {
Identity.registerExtension();
Lifecycle.registerExtension();
Signal.registerExtension();
} catch (Exception e) {
// handle exception
}
MobileCore.start(null);
}

Javascript

import {ACPCore, ACPLifecycle, ACPIdentity, ACPSignal, ACPMobileLogLevel} from '@adobe/react-native-acpcore';
initSDK() {
ACPCore.setLogLevel(ACPMobileLogLevel.VERBOSE);
ACPCore.configureWithAppId("yourAppId");
ACPLifecycle.registerExtension();
ACPIdentity.registerExtension();
ACPSignal.registerExtension();
ACPCore.start();
}

Developing extensions and using Launch Integration? The environment ID should be prefixed with staging/. For example, staging/launch-EN58bc2c40c3b14d688b768fe79a623519-development

Enable debug logging

Debug logging is optional and helps you ensure that the SDK is working as intended. Below is a table that explains the levels of logging available and when they may be used:

Log Level

Description

Error

This log level provides the details about unrecoverable errors that occurred during SDK implementation.

Warning

In addition to the detail from Error log level, Warning provides error information during SDK integration. This log level might indicate that a request has been made to the SDK, but the SDK might be unable to perform the requested task. For example, this log level might be used when catching an unexpected, but recoverable, exception and printing its message.

Debug

In addition to detail from the Warning log level, Debug also provides high-level information about how the SDK processes network requests/responses data.

Verbose

In addition to detail from the Debug level, Verbose provides detailed, low-level information about how SDK processes database interactions and SDK events.

To enable debug logging:

Android
Objective-C
Swift
React Native
MobileCore.setLogLevel(LoggingMode.DEBUG);
// MobileCore.setLogLevel(LoggingMode.VERBOSE);
// MobileCore.setLogLevel(LoggingMode.WARNING);
// MobileCore.setLogLevel(LoggingMode.ERROR);
[ACPCore setLogLevel:ACPMobileLogLevelDebug];
// [ACPCore setLogLevel:ACPMobileLogLevelVerbose];
// [ACPCore setLogLevel:ACPMobileLogLevelWarning];
// [ACPCore setLogLevel:ACPMobileLogLevelError];
ACPCore.setLogLevel(ACPMobileLogLevel.debug)
// ACPCore.setLogLevel(ACPMobileLogLevel.verbose)
// ACPCore.setLogLevel(ACPMobileLogLevel.warning)
// ACPCore.setLogLevel(ACPMobileLogLevel.error)

Enable and control the log level of the SDK

import {ACPMobileLogLevel} from '@adobe/react-native-acpcore';
ACPCore.setLogLevel(ACPMobileLogLevel.VERBOSE);
const ERROR = "ACP_LOG_LEVEL_ERROR";
const WARNING = "ACP_LOG_LEVEL_WARNING";
const DEBUG = "ACP_LOG_LEVEL_DEBUG";
const VERBOSE = "ACP_LOG_LEVEL_VERBOSE";

Registering Extensions and Starting Core

Other than the Mobile Core extension, all Experience Platform extensions provide a registerExtension API, which registers the extension with Core. After you register the extension, you can dispatch and listen for events. You are required to register each of your extensions before making API calls and failing to do so will lead to undefined behavior.

After you register all of your extensions, call the start API in Core. This step is required to boot up the SDK for event processing.

The following code snippets demonstrate how to initialize the SDK when using the Identity, Signal, Lifecycle, and Analytics extensions:

Android
Objective-C
Swift
React Native
try {
Identity.registerExtension();
Lifecycle.registerExtension();
Signal.registerExtension();
Analytics.registerExtension();
} catch (Exception e) {
//Log the exception
}
}
[ACPIdentity registerExtension];
[ACPLifecycle registerExtension];
[ACPSignal registerExtension];
[ACPAnalytics registerExtension];
[ACPCore start:nil];
ACPIdentity.registerExtension()
ACPLifecycle.registerExtension()
ACPSignal.registerExtension()
ACPAnalytics.registerExtension()
ACPCore.start(nil)

JavaScript

import {ACPCore, ACPLifecycle, ACPIdentity, ACPSignal, ACPMobileLogLevel} from '@adobe/react-native-acpcore';
initSDK() {
ACPCore.setLogLevel(ACPMobileLogLevel.VERBOSE);
ACPCore.configureWithAppId("PASTE_ENVIRONMENT_ID_HERE");
ACPLifecycle.registerExtension();
ACPIdentity.registerExtension();
ACPSignal.registerExtension();
ACPCore.start();
}

Enable the Experience Cloud Identity service

Formerly known as Marketing Cloud ID (MCID), the Experience Cloud ID (ECID) service provides a cross-channel notion of identity across Experience Cloud solutions and is a prerequisite for most implementations.

To confirm that you have the correct Experience Cloud Org ID in the Mobile Core settings page, see Get the SDK.

Android
iOS
React Native

Import the Identity framework to your project:

Java

import com.adobe.marketing.mobile.*;

Register the framework with Mobile Core:

public class MobileApp extends Application {
@Override
public void onCreate(){
super.onCreate();
MobileCore.setApplication(this);
try {
Identity.registerExtension();
} catch (Exception e) {
//Log the exception
}
}
}

Add the Identity framework to your project:

Objective-C

#import "ACPIdentity.h"

Swift

import ACPCore

Register the Identity framework with Mobile Core

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[ACPIdentity registerExtension];
// Override point for customization after application launch.
return YES;
}

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
ACPIdentity.registerExtension()
return true
}

JavaScript

Import the Identity extension

import {ACPIdentity} from '@adobe/react-native-acpcore';

Get the extension version (optional)

ACPIdentity.extensionVersion().then(version => console.log("AdobeExperienceSDK: ACPIdentity version: " + version));

Register the extension with Core

ACPIdentity.registerExtension();

After a successful configuration, the Experience Cloud ID is generated and included on every network hit that is sent to Adobe. Other automatically generated and custom are also sent with each hit.

Enable lifecycle metrics

This section shows you how to collect lifecycle metrics. To view, and report on this data in those respective solutions, you need to set up Analytics or other Experience Cloud solution extensions.

Lifecycle metrics contain valuable, out-of-the-box information about your app user. These metrics contain information on the app user's lifecycle such as device information, install or upgrade information, session start and pause times, and so on. You can also set additional lifecycle metrics.

Android
iOS
React Native

Java

Import the Lifecycle framework:

import com.adobe.marketing.mobile.*;

Register the framework with Mobile Core:

public class TargetApp extends Application {
@Override
public void onCreate() {
super.onCreate();
MobileCore.setApplication(this);
try {
Lifecycle.registerExtension();
} catch (Exception e) {
//Log the exception
}
}
}

With the onResume function, start Lifecycle data collection:

@Override
public void onResume() {
MobileCore.setApplication(getApplication());
MobileCore.lifecycleStart(null);
}

Setting the application is only necessary on activities that are entry points for your application. However, setting the application on each Activity has no negative impact and ensures that the SDK always has the necessary reference to your application. We recommend that you call setApplicationin each of your activities.

You can use the onPause function to pause the lifecycle data collection:

To ensure accurate session and crash reporting, this call must be added to every activity.

@Override
public void onPause() {
MobileCore.lifecyclePause();
}

Objective-C

Import the Lifecycle framework:

#import "ACPLifecycle.h"

Register the framework with Mobile Core by adding the following in your app's didFinishLaunchingWithOptions:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[ACPLifecycle registerExtension];
// Override point for customization after application launch.
return YES;
}

Start Lifecycle data collection by adding lifecycleStart to your app'sdidFinishLaunchingWithOptions

// Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[ACPLifecycle registerExtension];
[ACPCore start:^{
[ACPCore lifecycleStart:nil];
}];
return YES;
}

Pause Lifecycle data collection when your app has entered the background:

// Objective-C
- (void) applicationDidEnterBackground:(UIApplication *)application {
[ACPCore lifecyclePause];
}

Swift

In swift, ACPCore includes ACPLifecycle :

import ACPCore

Register the framework with Mobile Core by adding the following in your app's didFinishLaunchingWithOptions:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
ACPLifecycle.registerExtension();
// Override point for customization after application launch.
return true;
}

Start Lifecycle data collection by adding lifecycleStart to your app'sdidFinishLaunchingWithOptions

// Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
ACPCore.start {
ACPCore.lifecycleStart(nil);
}
return true
}

Pause Lifecycle data collection when your app has entered the background:

// Swift
func applicationDidEnterBackground(_ application: UIApplication) {
ACPCore.lifecyclePause()
}

JavaScript

Import the Lifecycle extension

import {ACPLifecycle} from '@adobe/react-native-acpcore';

Getting the extension version (optional)

ACPLifecycle.extensionVersion().then(version => console.log("AdobeExperienceSDK: ACPLifecycle version: " + version));

Registering the extension with Core

ACPLifecycle.registerExtension();

Starting a lifecycle event

ACPCore.lifecycleStart({"lifecycleStart": "myData"});

Pausing a lifecycle event

ACPCore.lifecyclePause();

For more information, see Lifecycle Metrics.

Track screens and user actions

You can use the following screen and action tracking APIs to measure your user's engagement with your app.

Actions are events that occur in your app. Use this API to track and measure an action, where each action has one or more corresponding metrics that increment each time the event occurs. For example, you might call this API for each new subscription each time an article is viewed, or each time a level is completed.

This section shows you how to start tracking app screens and user actions. To view and report on this data in those respective solutions, set up Analytics or other Experience Cloud solution extensions.

Track user actions

You must call this API when an event that you want to track occurs. In addition to the action name, you can send additional context data with each track action call.

Android
Objective-C
Swift
React Native

Java

trackAction

Syntax

public static void trackAction(final String action, final Map<String, String> contextData)

Example

Map<String, String> additionalContextData = new HashMap<String, String>();
additionalContextData.put("customKey", "value");
MobileCore.trackAction("loginClicked", additionalContextData);

trackAction

Syntax

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

Example

[ACPCore trackAction:@"action name" data:@{@"key":@"value"}];

trackAction

Syntax

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

Example

ACPCore.trackAction("action name", data: ["key": "value"])

JavaScript

ACPCore.trackAction("action", {"mytest": "action"});

Track app states and screens

States represent screens or views in your app. Each time a new state is displayed in your application, for example, when a user navigates from the home page to the news feed, this method might be called. This method also sends an Analytics state tracking hit with optional context data.

Android
Objective-C
Swift
React Native

Java

In Android, trackState is typically called each time a new activity is loaded.

trackState

Syntax

public static void trackState(final String state, final Map<String, String> contextData)

Example

Map<String, String> additionalContextData = new HashMap<String, String>();
additionalContextData.put("customKey", "value");
MobileCore.trackState("homePage", additionalContextData);

trackState

Syntax

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

Example

[ACPCore trackState:@"state name" data:@{@"key":@"value"}];

trackState

Syntax

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

Example

ACPCore.trackState("state name", data: ["key": "value"])

JavaScript

ACPCore.trackState("state", {"mytest": "state"});

For more information, see Mobile Core API Reference.