The Adobe Experience Platform Web SDK leverages Adobe Experience Cloud IDs (ECIDs) to track visitor behavior. Using ECIDs, you can ensure that each device has a unique identifier that can persist across multiple sessions, tying all the hits that occur during and across web sessions to a specific device.
This document provides an overview of how to manage ECIDs using the Platform Web SDK.
The Platform Web SDK assigns and tracks ECIDs through the use of cookies, with multiple available methods for configuring how these cookies are generated.
When a new user arrives on your website, Adobe Experience Cloud Identity Service attempts to set a device identification cookie for that user. For first-time visitors, an ECID is generated and returned in the first response from the Adobe Experience Platform Edge Network. For repeat visitors, the ECID is retrieved from the kndctr_{YOUR-ORG-ID}_AdobeOrg_identity
cookie and added to the payload by the Edge Network.
Once the cookie containing the ECID has been set, each subsequent request generated by the Web SDK will include an encoded ECID in the kndctr_{YOUR-ORG-ID}_AdobeOrg_identity
cookie.
When using cookies for device identification, you have two options to interact with the Edge Network:
adobedc.net
. This method is referred to as third-party data collection.adobedc.net
. This method is referred to as first-party data collection.As explained in the sections below, the data collection method that you choose to use has a direct impact on cookie lifetime across browsers.
Third-party data collection involves sending data directly to the Edge Network domain adobedc.net
.
In recent years, web browsers have becoming increasingly restrictive in their handling of cookies set by third parties. Some browsers block third-party cookies by default. If you use third-party cookies to identify site visitors, the lifetime of those cookies is almost always shorter than what would be otherwise available using first-party cookies instead. In some cases, a third-party cookie will expire in as little as seven days.
Additionally, when third-party data collection is used, some ad blockers restrict traffic to Adobe data collection endpoints altogether.
First-party data collection involves setting cookies through a CNAME on your own domain that points to adobedc.net
.
While browsers have long treated cookies set by CNAME endpoints in a similar manner to those set by site-owned endpoints, recent changes implemented by browsers have created a distinction in how CNAME cookies are handled. While there are no browsers that currently block first-party CNAME cookies by default, some browsers restrict the lifetime of cookies set using a CNAME to just seven days.
Regardless of whether you choose first-party or third-party data collection, the length of time a cookie can persist has a direct impact on visitor counts in Adobe Analytics and Customer Journey Analytics. Additionally, end users may experience inconsistent personalization experiences when Adobe Target or Offer Decisioning is used on the site.
For example, consider a situation where you have created a personalization experience that will promote any item to the home page if a user has viewed it three times over the last seven days.
If an end user visits three times in a week and then does not return to the site for seven days, that use could be considered a new user when they return to the site because their cookies may have been deleted by a browser policy (depending on the browser they were using when they visited the site). If this occurs, your Analytics tool will treat the visitor as a new user even though they visited the site just a little over seven days ago. Additionally, any effort to personalize the experience for the user will begin again.
To account for the effects of cookie lifespans as outlined above, you can opt to set and manage your own device identifiers instead. See the guide on first-party device IDs for more information.
To retrieve the unique ECID for the current visitor, use the getIdentity
command. For first-time visitors who don’t have an ECID yet, this command generates a new ECID. getIdentity
also returns the region ID for the visitor.
This method is typically used with custom solutions that require reading the Experience Cloud ID or need a location hint for Adobe Audience Manager. It is not used by a standard implementation.
alloy("getIdentity")
.then(function(result) {
// The command succeeded.
console.log("ECID:", result.identity.ECID);
console.log("RegionId:", result.edge.regionId);
})
.catch(function(error) {
// The command failed.
// "error" will be an error object with additional information.
});
identityMap
Using an XDM identityMap
field, you can identify a device/user using multiple identities, set their authentication state, and decide which identifier is considered the primary one. If no identifier has been set as primary
, the primary defaults to be the ECID
.
identityMap
fields are updated using the sentEvent
command.
alloy("sendEvent", {
xdm: {
"identityMap": {
"ID_NAMESPACE": [ // Notice how each namespace can contain multiple identifiers.
{
"id": "1234",
"authenticatedState": "ambiguous",
"primary": true
}
]
}
}
});
Each property within identityMap
represents identities belonging to a particular identity namespace. The property name should be the identity namespace symbol, which you can find listed in the Adobe Experience Platform user interface under “Identities”. The property value should be an array of identities pertaining to that identity namespace.
The namespace ID passed in the identityMap
is case sensitive. Make sure to use the correct namespace ID to avoid incomplete data collection.
Each identity object in the identities array contains the following properties:
Property | Data type | Description |
---|---|---|
id |
String | (Required) The ID that you want to set for the given namespace. |
authenticationState |
String | (Required) The authentication state of the ID. Possible values are ambiguous , authenticated , and loggedOut . |
primary |
Boolean | Determines whether this identity should be used as a primary fragment in the profile. By default, the ECID is set as the primary identifier for the user. If omitted, this value defaults to false . |
Using the identityMap
field to identify devices or users leads to the same result as using the setCustomerIDs
method from the ID Service API. See the ID Service API documentation for more details.
When migrating from using Visitor API, you can also migrate existing AMCV cookies. To enable ECID migration, set the idMigrationEnabled
parameter in the configuration. ID migration enables the following use cases:
idMigrationEnabled
for a period of time so that most of the visitor cookies are migrated, the setting can be turned off.When XDM formatted data is sent into Audience Manager this data will need to be converted into signals when migrating. Your traits will need to be updated to reflect the new keys that XDM provides. This process is made easier by using the BAAAM tool that Audience Manager has created.
If you currently have event forwarding enabled and are using appmeasurement.js
and visitor.js
, you can keep the event-forwarding feature enabled and this won’t cause any issues. On the back end, Adobe fetches any AAM segments and adds them to the call to Analytics. If the call to Analytics contains those segments, Analytics won’t call Audience Manager to forward any data, so there isn’t any double data collection. There is also no need for Location Hint when using the Web SDK because the same segmentation endpoints are called in the backend.