Identity API reference
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 IDTS
- 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:
scheme://authority/path?query=param#fragment
In this example, the Adobe visitor data is appended as:
scheme://authority/path?query=param&adobe_mc=TS%3Dtimestamp%7CMCMID%3Decid%7CMCORGID%3Decorgid%40AdobeOrg#fragment
Similarly, URLs without a query component:
scheme://authority/path#fragment
The Adobe visitor data is appended as:
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.adobe_mc = TS=XXXXXX|MCMID=XXXXXX|MCAID=XXXXXX|[email protected]
If your application uses more complicated URLs, such as Angular URLs, you should use getUrlVariables.
Android
iOS (AEP 3.x)
iOS (ACP 2.x)
React Native
Flutter
Cordova
Unity
Xamarin
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
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
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);
}
});
Syntax
static func appendTo(url: URL?, completion: @escaping (URL?, Error?) -> Void)
- url 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.
- completion is invoked after the updated URL is available or Error if an unexpected exception occurs or the request times out. The returned
Error
contains the AEPError code of the specific error.
Example
Identity.appendTo(url: URL(string: "https://example.com")) { appendedURL, error in
if let error = error {
// handle error
} else {
// handle the appended url here
if let appendedURL = appendedURL {
// APIs which update the UI must be called from main thread
DispatchQueue.main.async {
self.webView.load(URLRequest(url: appendedURL!))
}
} else {
// handle error, nil appendedURL
}
}
})
Syntax
+ (void) appendToUrl: (NSURL * _Nullable baseUrl) completion: ^(NSURL * _Nullable urlWithVisitorData, NSError * _Nullable error) completion;
Example
NSURL* url = [NSURL URLWithString:@"https://example.com"];
[AEPMobileIdentity appendToUrl:url completion:^(NSURL * _Nullable urlWithVisitorData, NSError * _Nullable error) {
if (error) {
// handle error here
} else {
// handle the appended url here
if (urlWithVisitorData) {
// APIs which update the UI must be called from main thread
dispatch_async(dispatch_get_main_queue(), ^{
[[self webView] loadRequest:[NSURLRequest requestWithURL:urlWithVisitorData]];
}
} else {
// handle error, nil urlWithVisitorData
}
}
}];
Method
appendToUrl:withCompletionHandler
was added in ACPCore version 2.5.0 and ACPIdentity version 2.2.0.Syntax
static func append(to: URL?, withCallback: ((URL?) -> Void)?)
static func append(to: URL?, withCompletionHandler: ((URL?, Error?)-> Void)?)
Example
ACPIdentity.append(to:URL(string: "https://example.com"), withCallback: {(appendedURL) in
// handle the appended url here
if let appendedURL = appendedURL {
// APIs which update the UI must be called from main thread
DispatchQueue.main.async {
self.webView.load(URLRequest(url: appendedURL!))
}
} else {
// handle error, nil appendedURL
}
});
ACPIdentity.append(to: URL(string: "https://example.com"), withCompletionHandler: { (appendedURL, error) in
if let error = error {
// handle error
} else {
// handle the appended url here
if let appendedURL = appendedURL {
// APIs which update the UI must be called from main thread
DispatchQueue.main.async {
self.webView.load(URLRequest(url: appendedURL!))
}
} else {
// handle error, nil appendedURL
}
}
})
Syntax
+ (void) appendToUrl: (nullable NSURL*) baseUrl withCallback: (nullable void (^) (NSURL* __nullable urlWithVisitorData)) callback;
+ (void) appendToUrl: (nullable NSURL*) baseUrl withCompletionHandler: (nullable void (^) (NSURL* __nullable urlWithVersionData, NSError* __nullable error)) completionHandler;
- 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.
- completionHandler is invoked with urlWithVersionData after the updated URL is available or error if an unexpected exception occurs or the request times out. The returned
NSError
contains the ACPError code of the specific error. The default timeout of 500ms.
Example
NSURL* url = [[NSURL alloc] initWithString:@"https://example.com"];
[ACPIdentity appendToUrl:url withCallback:^(NSURL * _Nullable urlWithVisitorData) {
// handle the appended url here
if (urlWithVisitorData) {
// APIs which update the UI must be called from main thread
dispatch_async(dispatch_get_main_queue(), ^{
[[self webView] loadRequest:[NSURLRequest requestWithURL:urlWithVisitorData]];
}
} else {
// handle error, nil urlWithVisitorData
}
}];
[ACPIdentity appendToUrl:url withCompletionHandler:^(NSURL * _Nullable urlWithVersionData, NSError * _Nullable error) {
if (error) {
// handle error here
} else {
// handle the appended url here
if (urlWithVisitorData) {
// APIs which update the UI must be called from main thread
dispatch_async(dispatch_get_main_queue(), ^{
[[self webView] loadRequest:[NSURLRequest requestWithURL:urlWithVisitorData]];
}
} else {
// handle error, nil urlWithVisitorData
}
}
}];
Syntax
appendVisitorInfoForURL(baseURL?: String): Promise<?string>;
- 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.
Example
ACPIdentity.appendVisitorInfoForURL("https://example.com").then(urlWithVistorData => console.log("AdobeExperenceSDK: Url with Visitor Data = " + urlWithVisitorData));
Syntax
Future<String> appendToUrl (String url);
- url 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.
Example
String result = "";
try {
result = await FlutterACPIdentity.appendToUrl("https://example.com");
} on PlatformException {
log("Failed to append URL");
}
Syntax
ACPIdentity.appendVisitorInfoForUrl = function(url, success, fail);
- url (String) 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.
- success is a callback containing the provided URL with the visitor information appended if the
appendVisitorInfoForUrl
API executed without any errors. - fail is a callback containing error information if the
appendVisitorInfoForUrl
API was executed with errors.
Example
ACPIdentity.appendVisitorInfoForUrl("https://example.com", function(handleCallback) {
console.log("AdobeExperenceSDK: Url with Visitor Data = " + handleCallback);
}, function(handleError) {
console.log("AdobeExperenceSDK: Failed to append URL : " + handleError);
});
Syntax
public static void AppendToUrl(string url, AdobeIdentityAppendToUrlCallback callback)
- url (String) 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 a callback containing the provided URL with the visitor information appended if the
AppendToUrl
API executed without any errors.
Example
[MonoPInvokeCallback(typeof(AdobeIdentityAppendToUrlCallback))]
public static void HandleAdobeIdentityAppendToUrlCallback(string url)
{
print("Url is : " + url);
}
ACPIdentity.AppendToUrl("https://www.adobe.com", HandleAdobeIdentityAppendToUrlCallback);
iOS Syntax
public unsafe static void AppendToUrl (NSUrl baseUrl, Action<NSUrl> callback);
- baseUrl (NSUrl) 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 a callback containing the provided URL with the visitor information appended if the
AppendToUrl
API executed without any errors.
Android Syntax
public unsafe static void AppendVisitorInfoForURL (string baseURL, IAdobeCallback callback);
- baseURL (string) 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 a callback containing the provided URL with the visitor information appended if the
AppendVisitorInfoForURL
API executed without any errors.
iOS Example
ACPIdentity.AppendToUrl(url, callback => {
Console.WriteLine("Appended url: " + callback);
});
Android Example
ACPIdentity.AppendVisitorInfoForURL("https://example.com", new StringCallback());
class StringCallback : Java.Lang.Object, IAdobeCallback
{
public void Call(Java.Lang.Object stringContent)
{
if (stringContent != null)
{
Console.WriteLine("Appended url: " + stringContent);
}
else
{
Console.WriteLine("null content in string callback");
}
}
}
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:
Android
iOS (AEP 3.x)
iOS (ACP 2.x)
React Native
Flutter
Cordova
Unity
Xamarin
Syntax
ACPIdentity.extensionVersion = function(success, fail);
- success is a callback containing the ACPIdentity extension version if the
extensionVersion
API executed without any errors. - fail is a callback containing error information if the
appendVisitorInfoForUrl
API was executed with errors.
Example
ACPIdentity.extensionVersion(function (handleCallback) {
console.log("AdobeExperienceSDK: ACPIdentity version: " + handleCallback)
}, function (handleError) {
console.log("AdobeExperenceSDK: failed to get extension version : " + handleError)
});
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.
Android
iOS (AEP 3.x)
iOS (ACP 2.x)
React Native
Flutter
Cordova
Unity
Xamarin
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
public static void getExperienceCloudId(final AdobeCallback<String> callback);
- callback is invoked after the ECID is available.
Example
Identity.getExperienceCloudId(new AdobeCallback<String>() {
@Override
public void call(String id) {
//Handle the ID returned here
}
});
Syntax
@objc(getExperienceCloudId:)
static func getExperienceCloudId(completion: @escaping (String?, Error?) -> Void)
- completion is invoked with String after the ECID is available, or Error if an unexpected error occurs or the request times out. The returned
Error
contains the AEPError code of the specific error.
Example
Identity.getExperienceCloudId { ecid, error in
if let error = error {
// handle error here
} else {
// handle the retrieved ID here
}
}
Syntax
+ (void) getExperienceCloudId: ^(NSString * _Nullable ecid, NSError * _Nullable error) completion;
Example
[AEPMobileIdentity getExperienceCloudId:^(NSString * _Nullable ecid, NSError *error) {
if (error) {
// handle error here
} else {
// handle the retrieved ID here
}
}];
Method
getExperienceCloudIdWithCompletionHandler
was added in ACPCore version 2.5.0 and ACPIdentity version 2.2.0.Syntax
static func getExperienceCloudId(_ callback: @escaping (String?) -> Void)
static func getExperienceCloudId(completionHandler: @escaping (String?, Error?) -> Void)
- callback is invoked after the ECID is available.
- completionHandler is invoked with experienceCloudId after the ECID is available, or error if an unexpected error occurs or the request times out. The returned
NSError
contains the ACPError code of the specific error. The default timeout of 500ms.
Sample
ACPIdentity.getExperienceCloudId { (retrievedCloudId) in
// handle the retrieved ID here
}
ACPIdentity.getExperienceCloudId { (retrievedCloudId, error) in
if let error = error {
// handle error here
} else {
// handle the retrieved ID here
}
}
Syntax
+ (void) getExperienceCloudId: (nonnull void (^) (NSString* __nullable experienceCloudId)) callback;
+ (void) getExperienceCloudIdWithCompletionHandler: (nonnull void (^) (NSString* __nullable experienceCloudId, NSError* __nullable error)) completionHandler;
Example
[ACPIdentity getExperienceCloudId:^(NSString * _Nullable retrievedCloudId) {
// handle the retrieved ID here
}];
[ACPIdentity getExperienceCloudIdWithCompletionHandler:^(NSString * _Nullable experienceCloudId, NSError * _Nullable error) {
if (error) {
// handle error here
} else {
// handle the retrieved ID here
}
}];
Syntax
ACPIdentity.getExperienceCloudId(success, fail);
- success is a callback containing the ECID if the
getExperienceCloudId
API executed without any errors. - fail is a callback containing error information if the
getExperienceCloudId
API was executed with errors.
Example
ACPIdentity.getExperienceCloudId(function (handleCallback) {
console.log("AdobeExperienceSDK: experienceCloudId: " + handleCallback)
}, function (handleError) {
console.log("AdobeExperenceSDK: Failed to retrieve experienceCloudId : " + handleError);
});
Syntax
public static void GetExperienceCloudId(AdobeGetExperienceCloudIdCallback callback)
- callback is a callback containing the ECID if the
GetExperienceCloudId
API executed without any errors.
Example
[MonoPInvokeCallback(typeof(AdobeGetExperienceCloudIdCallback))]
public static void HandleAdobeGetExperienceCloudIdCallback(string cloudId)
{
print("ECID is : " + cloudId);
}
ACPIdentity.GetExperienceCloudId(HandleAdobeGetExperienceCloudIdCallback);
iOS Syntax
public unsafe static void GetExperienceCloudId (Action<NSString> callback);
- callback is a callback containing the ECID if the
getExperienceCloudId
API executed without any errors.
Android Syntax
public unsafe static void GetExperienceCloudId (IAdobeCallback callback);
- callback is a callback containing the ECID if the
getExperienceCloudId
API executed without any errors.
iOS Example
ACPIdentity.GetExperienceCloudId(callback => {
Console.WriteLine("Experience Cloud Id: " + callback);
});
Android Example
ACPIdentity.GetExperienceCloudId(new StringCallback());
class StringCallback : Java.Lang.Object, IAdobeCallback
{
public void Call(Java.Lang.Object stringContent)
{
if (stringContent != null)
{
Console.WriteLine("Experience Cloud Id: " + stringContent);
}
else
{
Console.WriteLine("null content in string callback");
}
}
}
This API returns all customer identifiers that were previously synced with the Adobe Experience Cloud Identity Service.
Android
iOS (AEP 3.x)
iOS (ACP 2.x)
React Native
Flutter
Cordova
Unity
Xamarin
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
public static void getIdentifiers(final AdobeCallback<List<VisitorID>> callback);
- callback is invoked after the customer identifiers are available.
Example
Identity.getIdentifiers(new AdobeCallback<List<VisitorID>>() {
@Override
public void call(List<VisitorID> idList) {
//Process the IDs here
}
});
Syntax
@objc(getIdentifiers:)
static func getIdentifiers(completion: @escaping ([Identifiable]?, Error?) -> Void)
- completion is invoked with a list of Identifiable objects after the customer identifiers are available, or Error if an unexpected error occurs or the request times out. The returned
Error
contains the AEPError code of the specific error.
Example
Identity.getIdentifiers { identifiers, error in
if let error = error {
// handle error here
} else {
// handle the retrieved identifiers here
}
}
Syntax
+ (void) getIdentifiers: ^(NSArray<id<AEPIdentifiables>> * _Nullable identifiers, NSError * _Nullable error) completion;
Example
[[AEPMobileIdentity getIdentifiers:^(NSArray<id<AEPIdentifiable>> * _Nullable identifiers, NSError *error) {
if (error) {
// handle error here
} else {
// handle the retrieved identifiers here
}
}];
Method
getIdentifiersWithCompletionHandler
was added in ACPCore version 2.5.0 and ACPIdentity version 2.2.0.Syntax
static func getIdentifiers(_ callback: @escaping ([ACPMobileVisitorId]?) -> Void)
static func getIdentifiersWithCompletionHandler(_ completionHandler: @escaping ([ACPMobileVisitorId]?, Error?) -> Void)
- callback is invoked after the customer identifiers are available.
- completionHandler is invoked with visitorIDs after the customer identifiers are available, or error if an unexpected error occurs or the request times out. The returned
NSError
contains the ACPError code of the specific error. The default timeout of 500ms.
Example
ACPIdentity.getIdentifiers { (retrievedVisitorIds) in
// handle the retrieved identifiers here
}
ACPIdentity.getIdentifiersWithCompletionHandler { (retrievedVisitorIds, error) in
if let error = error {
// handle error here
} else {
// handle the retrieved identifiers here
}
}
Syntax
+ (void) getIdentifiers: (nonnull void (^) (NSArray<ADBMobileVisitorId*>* __nullable visitorIDs)) callback;
+ (void) getIdentifiersWithCompletionHandler: (nonnull void (^) (NSArray<ACPMobileVisitorId*>* __nullable visitorIDs, NSError* __nullable error)) completionHandler;
Example
[ACPIdentity getIdentifiers:^(NSArray<ACPMobileVisitorId *> * _Nullable retrievedVisitorIds) {
// handle the retrieved identifiers here
}];
[ACPIdentity getIdentifiersWithCompletionHandler:^(NSArray<ACPMobileVisitorId *> * _Nullable visitorIDs, NSError * _Nullable error) {
if (error) {
// handle error here
} else {
// handle the retrieved identifiers here
}
}];