Identity data in the Platform Web SDK

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.

Tracking ECIDs using the 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:

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

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

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.

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

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.

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

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

Each identity object in the identities array contains the following properties:

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. Additionally, 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 return visitor information is retained. After the SDK is deployed with idMigrationEnabled for a period of 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 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.

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.