Mobile Core API reference

Application reference (Android only)

When building Android applications, the android.app.Application reference must be passed to the Mobile SDK, which allows the Mobile SDK to access the android.app.Context and monitor the lifecycle of the Android application.

{% hint style="warning" %} Android applications must call MobileCore.setApplication() before calling any other Mobile SDK API. {% endhint %}

Set Application

You can use this API to pass the Android Application instance to the SDK.

{% tabs %} {% tab title="Android" %} Java

setApplication

Syntax

public static void setApplication(final Application app)

Example

public class CoreApp extends Application {

   @Override
   public void onCreate() {
      super.onCreate();
      MobileCore.setApplication(this);
      MobileCore.start(null);
   }
}

{% endtab %} {% endtabs %}

Get Application

You can use this API to get the previously set Android Application instance, and this instance is mainly provided for the third-party extensions.

{% tabs %} {% tab title="Android" %} Java

getApplication

{% hint style="warning" %} MobileCore.getApplication might return null if the Application object was destroyed or if MobileCore.setApplication was not previously called. {% endhint %}

Syntax

public static Application getApplication()

Example

Application app = MobileCore.getApplication();
if (app != null) {
    ...
}

{% endtab %} {% endtabs %}

Track app actions

Actions are events that occur in your app. You can use this API to track and measure an action. Each action has one or more corresponding metrics that are incremented 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.

{% hint style="warning" %} 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. {% endhint %}

{% hint style="info" %} If you installed and configured the Analytics extension, this method sends an Analytics action tracking hit with the optional context data that you provide. {% endhint %}

{% tabs %} {% tab title="Android" %} Java

trackAction

Syntax

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

action contains the name of the action to track.
contextData contains the context data to attach on this hit.

Example

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

{% endtab %}

{% tab title="iOS" %} Objective-C

trackAction

Syntax

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

action contains the name of the action to track.
contextData contains the context data to attach on this hit.

Example

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

Swift

trackAction

Syntax

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

action contains the name of the action to track.
contextData contains the context data to attach on this hit.

Example

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

{% endtab %}

{% tab title="React Native" %}

JavaScript

trackAction

Syntax

trackAction(action?: String, contextData?: { string: string });

action contains the name of the action to track.
contextData contains the context data to attach on this hit.

Example

ACPCore.trackAction("action name", {"key": "value"});

{% endtab %}

{% tab title="Flutter" %}

Dart

trackAction

Syntax

Future<void> trackAction (String action, {Map<String, String> contextData});

action contains the name of the action to track.
contextData contains the context data to attach on this hit.

Example

FlutterACPCore.trackAction("action name",  data: {"key": "value"});

{% endtab %}

{% tab title="Cordova" %}

Cordova

trackAction

Syntax

ACPCore.trackAction = function(action, contextData, success, fail);

action contains the name of the action to track.
contextData contains the context data to attach on this hit.
success callback is invoked when trackAction executes successfully.
fail callback is invoked when trackAction fails.

Example

ACPCore.trackAction("cordovaAction", {"cordovaKey":"cordovaValue"}, successCallback, errorCallback);

{% endtab %}

{% tab title="Unity" %}

C#

trackAction

Syntax

public static void TrackAction(string name, Dictionary<string, string> contextDataDict)

name contains the name of the action to track.
contextDataDict contains the context data to attach on this hit.

Example

var contextData = new Dictionary<string, string>();
contextData.Add("key", "value");
ACPCore.TrackAction("action", contextData);

{% endtab %} {% endtabs %}

Track app states and views

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 API can be called. This method sends an Analytics state tracking hit with optional context data.

{% hint style="info" %} If you installed and configured the Analytics extension, this API increments page views and an Analytics state tracking hit with the optional context data that you provide. {% endhint %}

{% tabs %} {% tab title="Android" %} 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)

state contains the name of the state to track.
contextData contains the context data to attach on this hit.

Example

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

{% endtab %}

{% tab title="iOS" %} Objective-C

trackState

Syntax

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

state contains the name of the state to track.
contextData contains the context data to attach on this hit.

Example

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

Swift

trackState

Syntax

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

state contains the name of the state to track.
contextData contains the context data to attach on this hit.

Example

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

{% endtab %}

{% tab title="React Native" %}

JavaScript

trackState

Syntax

trackState(state?: String, contextData?: { string: string });

state contains the name of the state to track.
contextData contains the context data to attach on this hit.

Example

ACPCore.trackState("state name", {"key": "value"});

{% endtab %}

{% tab title="Flutter" %}

Dart

trackState

Syntax

Future<void> trackState (String state, {Map<String, String> contextData});

state contains the name of the state to track.
contextData contains the context data to attach on this hit.

Example

FlutterACPCore.trackState("state name",  data: {"key1: "value"})

{% endtab %}

{% tab title="Cordova" %}

Cordova

trackState

Syntax

ACPCore.trackState = function(state, contextData, success, fail);

state contains the name of the state to track.
contextData contains the context data to attach on this hit.
success callback is invoked when trackState executes successfully.
fail callback is invoked when trackState fails.

Example

ACPCore.trackState("cordovaState", {"cordovaKey":"cordovaValue"}, successCallback, errorCallback);

{% endtab %}

{% tab title="Unity" %}

C#

trackState

Syntax

public static void TrackState(string name, Dictionary<string, string> contextDataDict)

name contains the name of the state to track.
contextDataDict contains the context data to attach on this hit.

Example

var dict = new Dictionary<string, string>();
dict.Add("key", "value");
ACPCore.TrackState("state", dict);

{% endtab %} {% endtabs %}

Collect PII

This API allows the SDK to collect sensitive or personally identifiable information (PII) data.

{% hint style="warning" %} Although this API enables the collection of sensitive data, no data is sent to any Adobe or third-party endpoints. To send the data to an endpoint, use a postback of the PII type. {% endhint %}

{% tabs %} {% tab title="Android" %} Java

collectPii

Syntax

public static void collectPII(final Map<String, String> piiData);

Example

Map<String, String> data = new HashMap<String, String>();
data.put("firstname", "customer");
//The rule to trigger a PII needs to be setup for this call
//to result in a network send
MobileCore.collectPII(data);

{% endtab %}

{% tab title="iOS" %} Objective-C

collectPii

Syntax

+ (void) collectPii: (nonnull NSDictionary<NSString*, NSString*>*) data;

Example

[ACPCore collectPii:data:@{@"key1" : "@value1",
                           @"key2" : "@value2"
                           }];

Swift

collectPii

Syntax

ACPCore.collectPii(data: [String : String])

{% endtab %}

{% tab title="React Native" %}

JavaScript

ACPCore.collectPii({"myPii": "data"});

{% endtab %} {% endtabs %}

Collect launch information

You can provide the user information to the SDK from various launch points in your application.

{% hint style="info" %} If the Analytics extension is enabled in your SDK, collecting this launch data results in an Analytics request being sent. Other extensions in the SDK might use the collected data, for example, as a rule condition for an In-App Message. {% endhint %}

{% tabs %} {% tab title="Android" %} Coming soon {% endtab %}

{% tab title="iOS" %} Objective-C

This method should be called to support the following use cases:

Tracking Deep Link click-throughs
- From application:didFinishLaunchingWithOptions
- Extract userInfo from UIApplicationLaunchOptionsURLKey
Tracking Push Message click-through
- From application:didReceiveRemoteNotification:fetchCompletionHandler:

collectLaunchInfo

Syntax

+ (void) collectLaunchInfo: (nonnull NSDictionary*) userInfo;

Example

 [ACPCore collectLaunchInfo:launchOptions];

Swift

This method should be called to support the following use cases:

Tracking Deep Link click-throughs
- From application(_:didFinishLaunchingWithOptions:)
- Extract userInfo from url: UIApplication.LaunchOptionsKey
Tracking Push Message click-through
- From application(_:didReceiveRemoteNotification:fetchCompletionHandler:)

collectLaunchInfo

Syntax

+ (void) collectLaunchInfo: (nonnull NSDictionary*) userInfo;

Example

ACPCore.collectLaunchInfo(userInfo)

{% endtab %} {% endtabs %}

Set Icons for local notification (Android only)

You can set the small and large icons that will be used for notifications that are created by the SDK. The small icon appears in the status bar and is the secondary image that is displayed when the user sees the complete notification in the notification center. The large icon is the primary image that is displayed when the user sees the complete notification in the notification center.

{% hint style="warning" %} Those APIs are only available in Android. {% endhint %}

{% tabs %} {% tab title="Android" %}

Java

setSmallIconResourceID

Syntax

public static void setSmallIconResourceID(int resourceID)

Example

 MobileCore.setSmallIconResourceID(R.mipmap.ic_launcher_round);

setLargeIconResourceID

Syntax

public static void setLargeIconResourceID(int resourceID)

Example

 MobileCore.setLargeIconResourceID(R.mipmap.ic_launcher_round);

{% endtab %} {% endtabs %}

Logging

The logging APIs allow log messages to be tagged and filtered with the Mobile SDK log messages and allow application developers to filter the logged messages based on the current logging mode.

Application developers can use the setLogLevel API to filter the log messages that are coming from the Mobile SDK. When debugging, use LoggingMode.VERBOSE (Android) / ACPMobileLogLevelVerbose (iOS) to enable all the logging messages that are coming from the Mobile SDK and partner extensions. In a production application, we recommend that you use a less verbose logging mode, for example LoggingMode.ERROR (Android) / ACPMobileLogLevelError (iOS).

By default, the Mobile SDK logging mode is set to LoggingMode.ERROR (Android) / ACPMobileLogLevelError (iOS).

As a Mobile SDK extension developer, you should use the MobileCore (Android) / ACPCore (iOS) log API to include extension log messages with Mobile SDK core log messages.

From least to most verbose, here is the order of the mobile SDK logging modes:

ERROR
WARNING
DEBUG
VERBOSE

{% hint style="info" %}

In Android, the Mobile SDK uses the android.util.Log class to print the messages.
In iOS, the Mobile SDK uses the NSLog for logging the message to Apple System Log facility. {% endhint %}

{% tabs %} {% tab title="Android" %} Java

setLogLevel

Syntax

public static void setLogLevel(LoggingMode mode)

Example

import com.adobe.marketing.mobile.LoggingMode;
import com.adobe.marketing.mobile.MobileCore;
...

MobileCore.setLogLevel(LoggingMode.VERBOSE);

{% endtab %}

{% tab title="iOS" %} Objective C

setLogLevel

Syntax

+ (void) setLogLevel: (ACPMobileLogLevel) logLevel;

Example

#import "ACPCore.h"
...

[ACPCore setLogLevel: ACPMobileLogLevelVerbose];

Swift

setLogLevel

Syntax

+ (void) setLogLevel: (ACPMobileLogLevel) logLevel;

Example

import ACPCore
...

ACPCore.setLogLevel(ACPMobileLogLevel.verbose);

{% endtab %}

{% tab title="React Native" %}

JavaScript

setLogLevel

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

ACPCore.setLogLevel(ACPMobileLogLevel.VERBOSE);

{% endtab %}

{% tab title="Flutter" %}

Dart

setLogLevel

import 'package:flutter_acpcore/src/acpmobile_logging_level.dart';

FlutterACPCore.setLogLevel(ACPLoggingLevel.VERBOSE);

{% endtab %}

{% tab title="Cordova" %}

Cordova

setLogLevel

From least to most verbose, here is the order of the mobile SDK logging modes for the Cordova version of the ACPCore extension:

ACPCore.ACPMobileLogLevelError
ACPCore.ACPMobileLogLevelWarning
ACPCore.ACPMobileLogLevelDebug
ACPCore.ACPMobileLogLevelVerbose

Syntax

ACPCore.setLogLevel = function(logLevel, success, fail);

Example

ACPCore.setLogLevel(ACPCore.ACPMobileLogLevelVerbose, successCallback, errorCallback);

{% endtab %}

{% tab title="Unity" %}

C#

setLogLevel

From least to most verbose, here is the order of the mobile SDK logging modes for the Unity version of the ACPCore extension:

ACPCore.ACPMobileLogLevel.ERROR
ACPCore.ACPMobileLogLevel.WARNING
ACPCore.ACPMobileLogLevel.DEBUG
ACPCore.ACPMobileLogLevel.VERBOSE

Syntax

public static void SetLogLevel(ACPMobileLogLevel logLevel)

Example

ACPCore.SetLogLevel(ACPCore.ACPMobileLogLevel.ERROR);

{% endtab %} {% endtabs %}

{% tabs %} {% tab title="Android" %} Java

getLogLevel

Syntax

public static LoggingMode getLogLevel()

Example

LoggingMode mode = MobileCore.getLogLevel();

{% endtab %}

{% tab title="iOS" %} Objective-C

getLogLevel

Syntax

+ (ACPMobileLogLevel) logLevel;

Example

var logLevel:ACPMobileLogLevel = [ACPCore logLevel];

Swift

getLogLevel

Syntax

+ (ACPMobileLogLevel) logLevel;

Example

let logLevel:ACPMobileLogLevel = ACPCore.logLevel();

{% endtab %}

{% tab title="React Native" %}

JavaScript

getLogLevel

ACPCore.getLogLevel().then(level => console.log("AdobeExperienceSDK: Log Level = " + level));

{% endtab %}

{% tab title="Unity" %}

C#

getLogLevel

ACPCore.ACPMobileLogLevel logLevel = ACPCore.GetLogLevel();

{% endtab %} {% endtabs %}

{% tabs %} {% tab title="Android" %} Java

The MobileCore logging APIs use the android.util.Log APIs to log messages to Android. Based on the LoggingMode that is passed to MobileCore.log(), the following Android method is called:

LoggingMode.VERBOSE uses android.util.Log.v
LoggingMode.DEBUG uses android.util.Log.d
LoggingMode.WARNING uses android.util.Log.w
LoggingMode.ERROR uses android.util.Log.e

All log messages from the Adobe Experience SDK to Android use the same log tag of AdobeExperienceSDK. For example, if logging an error message is using MobileCore.log(), the call to android.util.Log.e looks like Log.e("AdobeExperienceSDK", tag + " - " + message).

log

Syntax

public static void log(final LoggingMode mode, final String tag, final String message)

Example

MobileCore.log(LoggingMode.DEBUG, "MyClassName", "Provided data was null");

Output Example

D/AdobeExperienceSDK: MyClassName - Provided data was null

{% endtab %}

{% tab title="iOS" %} Objective-C

The log messages from the Adobe Experience SDK are printed to the Apple System Log facility and use a common format that contains the tag AdobeExperienceSDK. For example, if logging an error message using ACPCore.log(), the printed output looks like [AdobeExperienceSDK ERROR <tag>]: message.

log

Syntax

+ (void) log: (ACPMobileLogLevel) logLevel tag: (nonnull NSString*) tag message: (nonnull NSString*) message;

Example

[ACPCore log: ACPMobileLogLevelDebug, tag:@"MyClassName", message:@"Provided data was nil"];

Output Example

[AdobeExperienceSDK DEBUG <MyClassName>]: Provided data was nil

Swift

log

Syntax

+ (void) log: (ACPMobileLogLevel) logLevel tag: (nonnull NSString*) tag message: (nonnull NSString*) message;

Example

ACPCore.log(ACPMobileLogLevel.debug, tag: "MyClassName", message: "Provided data was nil");

Output Example

[AdobeExperienceSDK DEBUG <MyClassName>]: Provided data was nil

{% endtab %}

{% tab title="React Native" %}

JavaScript

The log messages from the Adobe Experience SDK are printed to the Log facility and use a common format that contains the tag ACPMobileLogLevel. For example, if logging an error message using ACPCore.log(), the printed output looks like

ACPCore.log(ACPMobileLogLevel.ERROR, "React Native Tag", "React Native Message");

Note: ACPMobileLogLevel contains the following getters:

const ERROR = "ACP_LOG_LEVEL_ERROR";
const WARNING = "ACP_LOG_LEVEL_WARNING";
const DEBUG = "ACP_LOG_LEVEL_DEBUG";
const VERBOSE = "ACP_LOG_LEVEL_VERBOSE";

{% endtab %} {% endtabs %}

Handle open URL action

The Mobile SDK allows you to add a callback function that is triggered before the open url action occurs. If the callback function returns Yes, the SDK does not complete the open url action. If the callback function returns No, the SDK completes the open url action.

{% tabs %} {% tab title="iOS" %} Objective C

registerURLHandler

Syntax

+ (void) registerURLHandler: (nonnull BOOL (^) (NSString* __nullable url)) callback;

Example

[ACPCore registerURLHandler:^BOOL(NSString * _Nullable url) {
    ...
}];

{% endtab %} {% endtabs %}

Set App Group (iOS only)

You can use this API to set the app group used to share user defaults and files among the containing app and the extension apps.

Note: This API must be called in AppDidFinishLaunching and before any other interactions with the Adobe Experience SDK have happened. Only the first call to this function will have any effect.

{% tabs %} {% tab title="iOS" %} Objective-C

setAppGroup

Objective-C

setAppGroup

Syntax

+ (void) setAppGroup: (nullable NSString*) appGroup;

Example

[ACPCore setAppGroup:@"app-group-id"];

Swift

setAppGroup

Syntax

+ (void) setAppGroup: (nullable NSString*) appGroup;

Example

ACPCore.setAppGroup("app-group-id")

{% endtab %} {% endtabs %}

Public Classes

{% tabs %} {% tab title="Android" %}

Android

AdobeCallback

This class provides the interface to receive results when the async APIs perform the requested action.

public interface AdobeCallback<T> {    
    void call(final T value);
}

AdobeCallbackWithError

This class provides the interface to receive results or an error when the async APIs perform the requested action. When using this class, if the request cannot be completed within the default timeout or an unexpected error occurs, the request is aborted and the fail method is called with the corresponding AdobeError.

public interface AdobeCallbackWithError<T> extends AdobeCallback<T> {
    void fail(final AdobeError error);
}

AdobeError

Errors which may be passed to an AdobeCallbackWithError:

UNEXPECTED_ERROR - An unexpected error occurred.
CALLBACK_TIMEOUT - The timeout was met.
CALLBACK_NULL - The provided callback function is null.
EXTENSION_NOT_INITIALIZED - The extension is not initialized.

Example

MobileCore.getPrivacyStatus(new AdobeCallbackWithError<MobilePrivacyStatus>() {
  @Override
  public void fail(final AdobeError error) {
    if (error == AdobeError.UNEXPECTED_ERROR) {
      // handle unexpected error
    } else if (error == AdobeError.CALLBACK_TIMEOUT) {
      // handle timeout error
    } else if (error == AdobeError.CALLBACK_NULL) {
      // handle null callback error
    } else if (error == AdobeError.EXTENSION_NOT_INITIALIZED) {
      // handle extension not initialized error
    }
  }

  @Override
  public void call(final MobilePrivacyStatus value) {
    // use MobilePrivacyStatus value
  }
});

{% endtab %}

{% tab title="iOS" %}

iOS

ACPError

Errors which may be passed to a completion handler callback from any API which uses one:

ACPErrorUnexpected - An unexpected error occurred.
ACPErrorCallbackTimeout - The timeout was met.
ACPErrorCallbackNil - The provided callback function is nil.
ACPErrorExtensionNotInitialized - The extension is not initialized.

Examples

Objective C

[ACPCore getPrivacyStatusWithCompletionHandler:^(ACPMobilePrivacyStatus status, NSError * _Nullable error) {
  if (error) {
    if (error.code == ACPErrorCallbackTimeout) {
      // handle timeout error
    } else if (error.code == ACPErrorCallbackNil) {
      // handle nil callback error
    } else if (error.code == ACPErrorExtensionNotInitialized) {
      // handle extension not initialized error
    } else if (error.code == ACPErrorUnexpected) {
      // handle unexpected error
    }
  } else {
    // use privacy status
  }
}];

Swift

ACPCore.getPrivacyStatus { (privacyStatus, error) in
  if let error = error {
    let callbackError: NSError = (error as NSError)
    if (callbackError.code == ACPError.callbackTimeout.rawValue) {
      // handle timeout error
    } else if (callbackError.code == ACPError.callbackNil.rawValue) {
      // handle nil callback error
    } else if (callbackError.code == ACPError.extensionNotInitialized.rawValue) {
      // handle extension not initialized error
    } else if (callbackError.code == ACPError.unexpected.rawValue) {
      // handle unexpected error
    }
  } else {
    // use privacyStatus
  }
}

{% endtab %} {% endtabs %}

Additional Information

What is context data?

Files

mobile-core-api-reference.md

Latest commit

History

mobile-core-api-reference.md

File metadata and controls

Mobile Core API reference

Application reference (Android only)

Set Application

setApplication

Get Application

getApplication

Track app actions

trackAction

trackAction

trackAction

JavaScript

trackAction

Dart

trackAction

Cordova

trackAction

C#

trackAction

Track app states and views

trackState

trackState

trackState

JavaScript

trackState

Dart

trackState

Cordova

trackState

C#

trackState

Collect PII

collectPii

collectPii

collectPii

JavaScript

Collect launch information

collectLaunchInfo

collectLaunchInfo

Set Icons for local notification (Android only)

Java

setSmallIconResourceID

setLargeIconResourceID

Logging

setLogLevel

setLogLevel

setLogLevel

JavaScript

setLogLevel

Dart

setLogLevel

Cordova

setLogLevel

C#

setLogLevel

getLogLevel

getLogLevel

getLogLevel

JavaScript

getLogLevel

C#

getLogLevel

log

log

log

JavaScript

Handle open URL action

registerURLHandler

Set App Group (iOS only)

setAppGroup

setAppGroup

setAppGroup

Public Classes

Android

iOS