Documentation Experience Platform Web SDK Guide

Identity data in Web SDK

Last update: February 4, 2025

Topics:
Web SDK

CREATED FOR:

Developer

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 and CORE IDs using the Web SDK.

Tracking ECIDs using Web SDK

The 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, the 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 Experience Platform Edge Network.
For returning visitors, the ECID is retrieved from the kndctr_{YOUR-ORG-ID}_AdobeOrg_identity cookie and added to the request 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 ways of interacting with the Edge Network:

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

Tracking CORE IDs using Web SDK

When using Google Chrome with third-party cookies enabled and there is no kndctr_{YOUR-ORG-ID}_AdobeOrg_identity cookie set, the first Edge Network request goes through a demdex.net domain, which sets a demdex cookie. This cookie contains a CORE ID. This is a unique user ID, different from the ECID.

Depending on your implementation, you might want to access the CORE ID.

First-party data collection

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.

Third-party data collection

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

In recent years, web browsers have become 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 using third-party data collection, some ad blockers restrict traffic to Adobe data collection endpoints altogether.

Effects of cookie lifespans on Adobe Experience Cloud applications

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 happens, 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 (FPIDs)

To account for the effects of cookie lifespans as outlined above, you can choose to set and manage your own device identifiers instead. See the guide on first-party device IDs for more information.

Retrieve the ECID and region for the current user

Depending on your use case, there are two ways in which you can access the ECID:

Retrieve the ECID through Data Prep for Data Collection: This is the recommended method that you should use.
Retrieve the ECID through the getIdentity() command: Only use this method when you require the ECID information on the client-side.

Retrieve the ECID through Data Prep for Data Collection

Use Data Prep for Data Collection to map the ECID to an XDM field. This is the recommended way to access the ECID.

To do this, set the source field to the following path:

xdm.identityMap.ECID[0].id

Then, set the target field to an XDM path where the field is of type string.

Retrieve the ECID through the `getIdentity()` command

IMPORTANT

You should only retrieve the ECID through the getIdentity() command if you require the ECID on the client side. If you only want to map the ECID to an XDM field, use Data Prep for Data Collection instead.

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.

NOTE

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.
  });

Retrieve the CORE ID for the current user

To retrieve the CORE ID for a user, you can use the getIdentity() command, as shown below.

alloy("getIdentity",{
  "namespaces": ["CORE"]
});

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
        }
      ]
    }
  }
});

NOTE

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.

IMPORTANT

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.

authenticatedState

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.

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.

recommendation-more-help