ÃÛ¶¹ÊÓƵ

Use first-party device IDs in Web SDK

The ÃÛ¶¹ÊÓƵ Experience Platform Web SDK assigns ÃÛ¶¹ÊÓƵ Experience Cloud IDs (ECIDs) to website visitors using cookies to track user behavior. To address browser restrictions on cookie lifespans, you can set and manage your own device identifiers, known as first-party device IDs (FPIDs).

Prerequisites prerequisites

Before you start, ensure you are familiar with how identity data works in the Web SDK, including ECIDs and identityMap. See the overview on identity data in the Web SDK for more information.

First-party device ID formatting requirements formatting-requirements

The Edge Network only accepts IDs that comply with the . Device IDs not in UUIDv4 format will be rejected.

Set the FPID cookie using your own server set-cookie-server

When setting a cookie through your own server, you can use various methods to prevent the cookie from being restricted due to browser policies:

Additionally, you should always set the FPID cookie under your domain’s A record.

When to set the cookie when-to-set-cookie

The FPID cookie should ideally be set before making any requests to the Edge Network. However, in scenarios where that is not possible, an ECID is still generated using existing methods and acts as the primary identifier as long as the cookie exists.

Assuming the ECID is eventually impacted by a browser deletion policy, but the FPID is not, the FPID will become the primary identifier on the next visit and will be used to seed the ECID on each subsequent visit.

Setting the expiration for the cookie set-expiration

Setting the expiration of a cookie is something that should be carefully considered as you implement the FPID functionality. When deciding this, you should consider the countries or regions in which your organization operates along with the laws and policies in each one of those regions.

As part of this decision, you may want to adopt a company-wide cookie-setting policy or one that varies for users in each locale where you operate.

Regardless of the setting you choose for the initial expiration of a cookie, you must ensure you include logic that extends the expiration of the cookie each time a new visit to the site occurs.

Impact of cookie flags cookie-flag-impact

There are various cookie flags that impact how cookies are treated across different browsers:

HTTPOnly http-only

Cookies set using the HTTPOnly flag cannot be accessed using client-side scripts. This means that if you set an HTTPOnly flag when setting the FPID, you must use a server-side scripting language to read the cookie value for inclusion in the identityMap.

If you choose to have the Edge Network read the value of the FPID cookie, setting the HTTPOnly flag ensures that the value is not accessible by any client-side scripts but will not have any negative impact on the Edge Network’s ability to read the cookie.

Secure secure

Cookies set with the Secure attribute are only sent to the server with an encrypted request over the HTTPS protocol. Using this flag can help ensure that man-in-the-middle attackers cannot easily access the value of the cookie. When possible, it is always a good idea to set the Secure flag.

SameSite same-site

The SameSite attribute lets servers determine whether cookies are sent with cross-site requests. The attribute provides some protection against cross-site forgery attacks. Three possible values exist: Strict, Lax, and None. Consult your internal team to determine which setting is right for your organization.

If no SameSite attribute is specified, the default setting for some browsers is now SameSite=Lax.

ID hierarchy id-hierarchy

When both an ECID and FPID are present, the ECID is prioritized in identifying the user. This ensures that when an existing ECID is present in the browser cookie store, it remains the primary identifier and existing visitor counts do not risk being affected. For existing users, the FPID will not become the primary identity until the ECID expires or is deleted as a result of a browser policy or manual process.

Identities are prioritized in the following order:

Migrating to first-party device IDs migrating-to-fpid

If you are migrating to first-party device IDs from a previous implementation, it may be difficult to visualize what the transition might look like at a low level.

To help illustrate this process, consider a scenario that involves a customer who has previously visited your site and what impact an FPID migration would have on how that customer is identified in ÃÛ¶¹ÊÓƵ solutions.

Using first-party device IDs (FPIDs) using-fpid

First-party device IDs (FPIDs) track visitors by using first-party cookies. First-party cookies are most effective when they are set using a server that uses a DNS (for IPv4) or (for IPv6), as opposed to a DNS CNAME or JavaScript code.

Once an FPID cookie is set, its value can be fetched and sent to ÃÛ¶¹ÊÓƵ as event data is collected. Collected FPIDs are used to generate ECIDs, which are the primary identifiers in ÃÛ¶¹ÊÓƵ Experience Cloud applications.

You can use FPIDs in two ways:

Method 1: Configure a CNAME for your Web SDK calls and set a First Party ID Cookie in your datastream setting-cookie-datastreams

To set an FPID cookie from your own domain, you need to configure your own CNAME (Canonical Name) for your Web SDK calls, and then enable the First Party ID Cookie functionality in your datastream configuration.

Step 1. Configure a CNAME for your Web SDK deployment domain

A CNAME record in your DNS allows you to create an alias from one domain name to another. This can help make third-party services appear as if they are part of your own domain, thus making their cookies look like first-party cookies.

Example

Let’s consider you want to implement Web SDK on your website mywebsite.com. The Web SDK sends data to the Edge Network to the edge.adobedc.net domain.

When first-party data collection is enabled using a CNAME, all cookies for your domain will be sent on requests made to the data collection endpoint.

To use this functionality, you need to set the FPID cookie at the top level of your domain instead of a specific subdomain. If you set it on a subdomain, the cookie value will not be sent to the Edge Network and the FPID solution will not work as intended.

Step 2. Enable First Party ID Cookie functionality for your datastream

After you have configured your CNAME, you must enable First Party ID Cookie option for your datastream. This setting tells the Edge Network to refer to a specified cookie when looking up a first-party device ID, instead of looking up this value in the identity map.

See the datastream configuration documentation to learn how to set up your datastream.

See the documentation on first-party cookies for more details on how they work with ÃÛ¶¹ÊÓƵ Experience Cloud.

When enabling this setting, you must provide the name of the cookie where the FPID is expected to be stored.

Method 2: Use FPIDs in identityMap identityMap

As an alternative to storing the FPID in your own cookie, you can send the FPID to the Edge Network through the identity map.

Below is an example of how you would set an FPID in the identityMap:

{
  "identityMap": {
    "FPID": [
      {
        "id": "123e4567-e89b-42d3-9456-426614174000",
        "authenticatedState": "ambiguous",
        "primary": true
      }
    ]
  }
}

As with other identity types, you can include the FPID with other identities within identityMap. The following is an example of the FPID included with an authenticated CRM ID:

{
  "identityMap": {
    "FPID": [
      {
        "id": "123e4567-e89b-42d3-9456-426614174000",
        "authenticatedState": "ambiguous",
        "primary": false
      }
    ],
    "EMAIL": [
      {
        "id": "email@mail.com",
        "authenticatedState": "authenticated",
        "primary": true
      }
    ]
  }
}

If the FPID is contained in a cookie being read by the Edge Network when first-party data collection is enabled, you should capture only the authenticated CRM ID:

{
  "identityMap": {
    "EMAIL": [
      {
        "id": "email@mail.com",
        "authenticatedState": "authenticated",
        "primary": true
      }
    ]
  }
}

The following identityMap would result in an error response from the Edge Network since it is missing the primary indicator for the FPID. At last one of the IDs present in identityMap must be marked as primary.

{
  "identityMap": {
    "FPID": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "authenticatedState": "ambiguous"
      }
    ],
    "EMAIL": [
      {
        "id": "email@mail.com",
        "authenticatedState": "authenticated"
      }
    ]
  }
}

The error response returned by the Edge Network in this case would be similar to the following:

{
    "type": "https://ns.adobe.com/aep/errors/EXEG-0306-400",
    "status": 400,
    "title": "No primary identity set in request (event)",
    "detail": "No primary identity found in the input event. Update the request accordingly to your schema and try again.",
    "report": {
        "requestId": "{REQUEST_ID}",
        "configId": "{CONFIG_ID}",
        "orgId": "{ORG_ID}"
    }
}

FAQ faq

The following is a list of answers to frequently asked questions about first-party device IDs.

How is seeding an ID different from simply generating an ID?

The concept of seeding is unique in that the FPID passed to ÃÛ¶¹ÊÓƵ Experience Cloud is converted to an ECID using a deterministic algorithm. Each time the same FPID is sent to the Edge Network, the same ECID is seeded from the FPID.

When should the first-party device ID be generated?

To reduce potential visitor inflation, the FPID should be generated before making your first request using the Web SDK. However, if you are unable to do this, an ECID will still be generated for that user and will be used as the primary identifier. The FPID that was generated will not become the primary identifier until the ECID is no longer present.

Which data collection methods support first-party device IDs?

Currently only Web SDK supports first-party device IDs.

Are first-party device IDs stored on any Platform or Experience Cloud solutions?

Once the FPID has been used to seed an ECID, it is dropped from the identityMap and replaced with the ECID that has been generated. The FPID is not stored in any ÃÛ¶¹ÊÓƵ Experience Platform or Experience Cloud solutions.