Edit in GitHubLog an issue

Identity API reference

appendToURL / appendVisitorInfoForURL

This API appends Adobe visitor information to the query component of the specified URL.

If the provided URL is null or empty, it is returned as is. Otherwise, the following information is added to the query component of the specified URL and is returned in the callback function:

  • The adobe_mc attribute is a URL encoded list that contains:
    • MCMID - Experience Cloud ID (ECID)
    • MCORGID - Experience Cloud Org ID
    • MCAID - Analytics Tracking ID (AID), if available from the Analytics extension
    • TS - A timestamp taken when this request was made
  • The optional adobe_aa_vid attribute is the URL-encoded Analytics Custom Visitor ID (VID), if previously set in the Analytics extension.

This API is designed to handle the following URL formats:

Copied to your clipboard
scheme://authority/path?query=param#fragment

In this example, the Adobe visitor data is appended as:

Copied to your clipboard
scheme://authority/path?query=param&adobe_mc=TS%3Dtimestamp%7CMCMID%3Decid%7CMCORGID%3Decorgid%40AdobeOrg#fragment

Similarly, URLs without a query component:

Copied to your clipboard
scheme://authority/path#fragment

The Adobe visitor data is appended as:

Copied to your clipboard
scheme://authority/path?adobe_mc=TS%3Dtimestamp%7CMCMID%3Decid%7CMCORGID%3Decorgid%40AdobeOrg#fragment

In these examples the adobe_mc parameters are separated by "|" (pipe) and are encoded.

Copied to your clipboard
adobe_mc = TS=XXXXXX|MCMID=XXXXXX|MCAID=XXXXXX|MCORGID=XXXXXX@AdobeOrg

If your application uses more complicated URLs, such as Angular URLs, you should use getUrlVariables.

Java

This API can be called with AdobeCallback or AdobeCallbackWithError for retrieving the attributes from the Mobile SDK. When AdobeCallbackWithError is provided, this API uses a default timeout of 500ms. If the operation times out or an unexpected error occurs, the fail method is called with the appropriate AdobeError.

Syntax

Copied to your clipboard
public static void appendVisitorInfoForURL(final String baseURL, final AdobeCallback<String> callback);
  • baseUrl is the URL to which the visitor information needs to be appended. If the visitor information is nil or empty, the URL is returned as is.
  • callback is invoked after the updated URL is available.

Example

Copied to your clipboard
Identity.appendVisitorInfoForURL("https://example.com", new AdobeCallback<String>() {
@Override
public void call(String urlWithAdobeVisitorInfo) {
//handle the new URL here
//For example, open the URL on the device browser
//
Intent i = new Intent(Intent.ACTION_VIEW);
i.setData(Uri.parse(urlWithAdobeVisitorInfo));
startActivity(i);
}
});

extensionVersion

The extensionVersion() API returns the version of the Identity extension that is registered with the Mobile Core extension.

To get the version of the Identity extension, use the following code sample:

Java

Copied to your clipboard
String identityExtensionVersion = Identity.extensionVersion();

getExperienceCloudId

This API retrieves the Adobe Experience Cloud ID (ECID) that was generated when the app was initially launched and is stored in the Adobe Experience Cloud Identity Service.

This ID is preserved between app upgrades, is saved and restored during the standard application backup process, and is removed at uninstall.

Java

This API can be called with AdobeCallback or AdobeCallbackWithError for retrieving the ECID from the Mobile SDK. When AdobeCallbackWithError is provided, this API uses a default timeout of 500ms. If the operation times out or an unexpected error occurs, the fail method is called with the appropriate AdobeError.

Syntax

Copied to your clipboard
public static void getExperienceCloudId(final AdobeCallback<String> callback);
  • callback is invoked after the ECID is available.

Example

Copied to your clipboard
Identity.getExperienceCloudId(new AdobeCallback<String>() {
@Override
public void call(String id) {
//Handle the ID returned here
}
});

getIdentifiers

This API returns all customer identifiers that were previously synced with the Adobe Experience Cloud Identity Service.

Java

This API can be called with AdobeCallback or AdobeCallbackWithError for retrieving the custom identifiers from the Mobile SDK. When AdobeCallbackWithError is provided, this API uses a default timeout of 500ms. If the operation times out or an unexpected error occurs, the fail method is called with the appropriate AdobeError.

Syntax

Copied to your clipboard
public static void getIdentifiers(final AdobeCallback<List<VisitorID>> callback);
  • callback is invoked after the customer identifiers are available.

Example

Copied to your clipboard
Identity.getIdentifiers(new AdobeCallback<List<VisitorID>>() {
@Override
public void call(List<VisitorID> idList) {
//Process the IDs here
}
});

getUrlVariables

This API gets the Adobe Experience Cloud Identity Service variables in URL query parameter form, and these variables will be consumed by the hybrid app. This method returns an appropriately formed string that contains the Experience Cloud Identity Service URL variables. There will be no leading (&) or (?) punctuation because the caller is responsible for placing the variables in their resulting URL in the correct location.

If an error occurs while retrieving the URL string, the callback handler will be called with a null value. Otherwise, the following information is added to the string that is returned in the callback:

  • The adobe_mc attribute is an URL encoded list that contains:
    • MCMID - Experience Cloud ID (ECID)
    • MCORGID - Experience Cloud Org ID
    • MCAID - Analytics Tracking ID (AID), if available from the Analytics extension
    • TS - A timestamp taken when this request was made
  • The optional adobe_aa_vid attribute is the URL-encoded Analytics Custom Visitor ID (VID), if previously set in the Analytics extension.

Java

This method was added in Core version 1.4.0 and Identity version 1.1.0.

This API can be called with AdobeCallback or AdobeCallbackWithError for retrieving the attributes from the Mobile SDK. When AdobeCallbackWithError is provided, this API uses a default timeout of 500ms. If the operation times out or an unexpected error occurs, the fail method is called with the appropriate AdobeError.

Syntax

Copied to your clipboard
public static void getUrlVariables(final AdobeCallback<String> callback);
  • callback has an NSString value that contains the visitor identifiers as a query string after the service request is complete.

Example

Copied to your clipboard
Identity.getUrlVariables(new AdobeCallback<String>() {
@Override
public void call(String stringWithAdobeVisitorInfo) {
//handle the URL query parameter string here
//For example, open the URL on the device browser
//
Intent i = new Intent(Intent.ACTION_VIEW);
i.setData(Uri.parse("https://example.com?" + urlWithAdobeVisitorInfo));
startActivity(i);
}
});

registerExtension

The registerExtension() API registers the Identity extension with the Mobile Core extension. This API allows the extension to send and receive events to and from the Mobile SDK.

Java

After calling the setApplication() method in the onCreate() method, register the extension. If the registration was not successful, an InvalidInitException is thrown.

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

setAdvertisingIdentifier

The advertising ID is preserved between app upgrades, is saved and restored during the standard application backup process, available via the Signals extension, and is removed at uninstall.

Java

Syntax

Copied to your clipboard
public static void setAdvertisingIdentifier(final String advertisingIdentifier);
  • advertisingIdentifier is a string that provides developers with a simple, standard system to track the Ads through their apps.

Example

This is just an implementation example. For more information about advertising identifiers and how to handle them correctly in your mobile application, see Google Play Services documentation about AdvertisingIdClient.

This example requires Google Play Services to be configured in your mobile application. For instructions on how to import the Google Mobile Ads SDK and how to configure your ApplicationManifest.xml file, see Google Mobile Ads SDK setup.

Copied to your clipboard
...
@Override
public void onResume() {
super.onResume();
...
new Thread(new Runnable() {
@Override
public void run() {
String advertisingIdentifier = null;
try {
AdvertisingIdClient.Info adInfo = AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());
if (adInfo != null) {
if (!adInfo.isLimitAdTrackingEnabled()) {
advertisingIdentifier = adInfo.getId();
} else {
MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "Limit Ad Tracking is enabled by the user, cannot process the advertising identifier");
}
}
} catch (IOException e) {
// Unrecoverable error connecting to Google Play services (e.g.,
// the old version of the service doesn't support getting AdvertisingId).
MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "IOException while retrieving the advertising identifier " + e.getLocalizedMessage());
} catch (GooglePlayServicesNotAvailableException e) {
// Google Play services is not available entirely.
MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "GooglePlayServicesNotAvailableException while retrieving the advertising identifier " + e.getLocalizedMessage());
} catch (GooglePlayServicesRepairableException e) {
// Google Play services is not installed, up-to-date, or enabled.
MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "GooglePlayServicesRepairableException while retrieving the advertising identifier " + e.getLocalizedMessage());
}
MobileCore.setAdvertisingIdentifier(advertisingIdentifier);
}
}).start();
}

setPushIdentifier

This API sets the device token for push notifications in the SDK. If the current SDK privacy status is optedout, the push identifier is not set.

Java

Syntax

Copied to your clipboard
public static void setPushIdentifier(final String pushIdentifier);
  • pushIdentifier is a string that contains the device token for push notifications.

Example

Copied to your clipboard
//Retrieve the token from either GCM or FCM, and pass it to the SDK
MobileCore.setPushIdentifier(token);

syncIdentifier

The syncIdentifier() and syncIdentifiers() APIs update the specified customer IDs with the Adobe Experience Cloud Identity Service.

These APIs synchronize the provided customer identifier type key and value with the authentication state to the Experience Cloud Identity Service. If the specified customer ID type exists in the service, this ID type is updated with the new ID and the authentication state. Otherwise, a new customer ID is added.

Starting with ACPIdentity v2.1.3 (iOS) and Identity v1.1.2 (Android) if the new identifier value is null or empty, this ID type is removed from the local storage, Identity shared state and not synced with the Experience Cloud Identity Service.

These IDs are preserved between app upgrades, are saved and restored during the standard application backup process, and are removed at uninstall.

If the current SDK privacy status is MobilePrivacyStatus.OPT_OUT, calling this method results in no operations being performed.

This API updates or appends the provided customer identifier type key and value with the given authentication state to the Experience Cloud Identity Service. If the specified customer ID type exists in the service, the ID is updated with the new ID and authentication state. Otherwise a new customer ID is added.

Java

Syntax

Copied to your clipboard
public static void syncIdentifier(final String identifierType,
final String identifier,
final VisitorID.AuthenticationState authenticationState);
  • identifierType (String) contains the identifier type, and this parameter should not be null or empty. The allowed characters are [A-Za-z0-9_.]
  • identifier (String) contains the identifier value, and this parameter should not be null or empty.
  • authenticationState (AuthenticationState) indicates the authentication state of the user and contains one of the VisitorID.AuthenticationState values.

Example

Copied to your clipboard
Identity.syncIdentifier("idType",
"idValue",
VisitorID.AuthenticationState.AUTHENTICATED);

syncIdentifiers

This API is an overloaded version, which does not include the parameter for the authentication state and it assumes a default value of VisitorID.AuthenticationState.UNKNOWN.

Java

Syntax

Copied to your clipboard
public static void syncIdentifiers(final Map<String, String> identifiers);
  • identifiers is a map that contains the identifiers with the Identifier type as the key, and the string identifier as the value. In each identifier pair, if the identifier type contains a null or an empty string, the identifier is ignored by the Identity extension.

Example

Copied to your clipboard
Map<String, String> identifiers = new HashMap<String, String>();
identifiers.put("idType1", "idValue1");
identifiers.put("idType2", "idValue2");
identifiers.put("idType3", "idValue3");
Identity.syncIdentifiers(identifiers);

syncIdentifiers (overloaded)

The function of this API is the same as the syncIdentifier API. This API passes a list of identifiers, and each identifier contains an identifier type as the key and an identifier as the value. In each identifier pair, if the identifier type contains a null or an empty string, the identifier is ignored by the Identity extension.

Starting with ACPIdentity v2.1.3 (iOS) and Identity v1.1.2 (Android) if the new identifier value is null or empty, this ID type is removed from the local storage, Identity shared state and not synced with the Adobe Experience Cloud Identity Service.

Java

Syntax

Copied to your clipboard
public static void syncIdentifiers(final Map<String, String> identifiers, final VisitorID.AuthenticationState authState)
  • identifiers is a map that contains IDs with the identifier type as the key, and the string identifier as the value.
  • authState indicates the authentication state for the user, which contains one of the following VisitorID.AuthenticationState values.

Example

Copied to your clipboard
Map<String, String> identifiers = new HashMap<String, String>();
identifiers.put("idType1", "idValue1");
identifiers.put("idType2", "idValue2");
identifiers.put("idType3", "idValue3");
Identity.syncIdentifiers(identifiers, VisitorID.AuthenticationState.AUTHENTICATED);

Public classes

AuthenticationState

This class is used to indicate the authentication state for the current VisitorID.

Copied to your clipboard
public enum AuthenticationState {
UNKNOWN,
AUTHENTICATED,
LOGGED_OUT;
}

VisitorID

This class is an identifier to be used with the Adobe Experience Cloud Identity Service.

Copied to your clipboard
public class VisitorID {
//Constructor
public VisitorID(String idOrigin, String idType, String id, VisitorID.AuthenticationState authenticationState);
public VisitorID.AuthenticationState getAuthenticationState();
public final String getId();
public final String getIdOrigin();
public final String getIdType();
}
Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2024 Adobe. All rights reserved.