Identity data in Web SDK

The Adobe Experience Platform Web SDK uses 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.

Tracking ECIDs using the SDK

The Platform Web SDK assigns and tracks ECIDs by using 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 includes 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:

  1. Send data directly to the Edge Network domain This method is referred to as third-party data collection.
  2. Create a CNAME on your own domain that points to 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 third-party

Third-party data collection involves sending data directly to the Edge Network domain

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. Sometimes, a third-party cookie expires in as little as seven days.

Also, when third-party data collection is used, some ad blockers restrict traffic to Adobe data collection endpoints altogether.

First-party data collection first-party

First-party data collection involves setting cookies through a CNAME on your own domain that points to

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. Also, end users may experience inconsistent personalization experiences when Adobe Target or Offer Decisioning are used on the site.

For example, consider a situation where you have created a personalization experience that promotes 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 user 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 treats the visitor as a new user even though they visited the site just a little over seven days ago. Also, any effort to personalize the experience for the user begins again.

First-party device IDs

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.

Retrieving the ECID and region for the current user

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.
  .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.

Using 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": "authenticated",
          "primary": true
Adobe recommends sending namespaces which represent a person, such as CRMID, as the primary identity.

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:

Data type
(Required) The ID that you want to set for the given namespace.
(Required) The authentication state of the ID. Possible values are ambiguous, authenticated, and loggedOut.
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.

Migrating from Visitor API to ECID

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:

  • When some pages of a domain are using Visitor API and other pages are using this SDK. To support this case, the SDK reads existing AMCV cookies and writes a new cookie with the existing ECID. Also, the SDK writes AMCV cookies so that if the ECID is obtained first on a page instrumented with the SDK, subsequent pages that are instrumented with Visitor API have the same ECID.
  • When Adobe Experience Platform Web SDK is set up on a page that also has Visitor API. To support this case, if the AMCV cookie is not set, the SDK looks for Visitor API on the page and calls it to get the ECID.
  • When the entire site is using Adobe Experience Platform Web SDK and does not have Visitor API, it is useful to migrate the ECIDs so that the returned visitor information is retained. After the SDK is deployed with idMigrationEnabled for a time so that most of the visitor cookies are migrated, the setting can be turned off.

Updating traits for migration

When XDM-formatted data is sent into Audience Manager this data must be converted into signals when migrating. Your traits must 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.

Use in event forwarding

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.