Declared IDs

How declared IDs work, set up procedures, code examples, and variables.

Declared ID Targeting

Exchange and synchronize user IDs with Audience Manager from devices or browsers that do not use or accept persistent storage mechanisms, such as third-party cookies.

Purpose of Declared ID Targeting

Some browsers, and most mobile devices, do not accept third-party cookies. This makes it difficult to retain information about site visitors or assign persistent IDs. To resolve this issue, Audience Manager uses DIL to let you pass in declared IDs on an event call. Also, a declared ID can act as a universal ID that applies to the same user across all the solutions in the Experience Cloud. The following table describes the ID targeting/matching process:

Process
Description
Event Call
To work, you need DIL and the Adobe Experience Platform Identity Servicecode on the page. DIL gets declared IDs from the setVisitorID function provided by the Adobe Experience Platform Identity Service and passes that on to Audience Manager .
Match ID

Audience Manager attempts to match the client and visitor ID with a corresponding ID in our system. If a matching ID does not exist, Audience Manager creates a new ID and associates it with the client and visitor ID.

Note: The most recent mapping is used if your ID maps to more than one Audience Manager ID.

Return ID
Audience Manager writes its synchronized ID to a first-party cookie (or other addressable storage space) in the client domain or application.
Subsequent Event Calls
Additional event calls read the Audience Manager ID from the client's domain and send that to Audience Manager.

To get started, you need to configure the Experience Cloud ID service and DIL across the pages on your site that you want to use for data collection. See DIL create and Declared ID Variables.

Opt-out Calls

The declared ID process honors site visitor preferences to opt-out of Audience Manager targeting by your website. When Audience Manager receives an opt-out request, the JSON returned by the DCS contains the error code 171, with the message Encountered opt out tag, instead of the Audience Manager user ID.

  • Audience Manager can pass in a declared ID opt-out alongside an Audience Manager UUID in the URL.
  • The declared ID opt-out is stored in the Profile Cache Server (PCS) on a per-partner basis. There is no platform-level opt-out using declared IDs. Additionally, Audience Manager opts the user out from that particular region on the edge (the opt-out does not cross DCS regions).

See Data Privacy for more information about opting-out of data collection.

Declared ID Opt-Out Examples

You can make a declared ID opt-out requests with the d_cid and d_cid_ic key-value pairs. The legacy parameters like d_dpid and d_dpuuid still work, but are considered deprecated. See CID Replaces DPID and DPUUID. In the examples, italics indicates a variable placeholder.

Opt-Outs With CID and CID_IC

For a description and syntax, see URL Variables and Syntax for Declared IDs.

Opt-Out Using
Code Sample
A data provider ID and user ID.
https://domain name/demoptout.jpg?d_cid=123%01987...
An integration code and user ID.
https://domain name/demoptout?d_cid_ic=456%01321...
Multiple d_cid and d_cid_ic key-value pairs.
https://domain name/demoptout?d_cid=123%01987&d_cid_ic=456%01321...

Opt-Outs With DPID, DPUUID, and UUID (Deprecated)

These methods still work but are considered deprecated. This information is provided for legacy purposes and reference. Legacy opt-outs include:

Opt-Out (Deprecated)
Code Sample
d_uuid only
https://domain/demoptout.jpg?d_uuid=AAM ID
Partner level opt-out

https://demoptout.jpg?d_dpuuid= user ID&d_dpid= data provider ID

A partner level opt-out gets stored for the latest mapping of this dpid + dpuuid pair to an AAM UUID. If there is no previously existing mapping, Audience Manager checks whether the request contains an AAM UUID in the cookie, and if it does, uses that for storing the opt-out. Otherwise, Audience Manager generates a new AAM UUID and stores the opt-out under it.

d_dpuuid + d_dpid and explicit d_uuid

https://domain/demoptout.jpg?d_uuid= user ID&d_dpuuid= data provider's user ID&d_dpid=data provider ID

d_uuid always takes precedence. If the dpid + dpuuid combination maps to another AAM UUID, the opt-out is stored under the AAM UUID passed in the request ( d_uuid ).

Variables and Syntax for Declared IDs

The following table lists the key-value pairs that pass in your Audience Manager data provider ID and user IDs or integration codes, if used. Note, italics indicates a variable placeholder. Spaces have been added to make these easier to read.

In each key-value pair:

  • The = symbol separates the key from its related values.
  • The non-printing ASCII character %01 separates the values.
Variable
Description
d_cid =data provider ID %01user ID
Contains a data provider ID and an associated unique user ID in a single key-value pair. d_cid replaces d_dpid and d_dpuuid , which are considered deprecated, but still supported. See CID Replaces DPID and DPUUID.
d_cid_ic =integration code %01user ID
Contains an integration code and an associated unique user ID in a single key-value pair. d_cid_ic replaces d_dpid and d_dpuuid , which are deprecated, but still supported. See CID Replaces DPID and DPUUID.

Sample Event Calls

Given these key-value pairs and their required syntax, you would make event calls as shown below.

Event Call Includes
Code Sample
A data provider ID and user ID.
https://domain name/event?d_cid=123%01987...
An integration code and user ID.
https://domain name/event?d_cid_ic=456%01321...
Multiple d_cid and d_cid_ic key-value pairs.
https://domain name/event?d_cid=123%01987&d_cid_ic=456%01321...

Declared ID Variables

Describes the configuration variables used to pass declared IDs through DIL to Audience Manager.

DIL uses the Adobe Experience Platform Identity Service to Pass Declared IDs

When used with the Adobe Experience Platform Identity Service, you no longer need to pass in declared IDs with the deprecated dpid and dpuuid variables. Instead, the current versions of DIL rely on the visitorService function to get the declared IDs from the setCustomerIDs function in the Adobe Experience Platform Identity Service. For more information, see Customer IDs and Authentication States. You would call visitorService in DIL.create as shown below.

var vDil = DIL.create({
  partner:"partner name",
  visitorService:{
    namespace:"INSERT-MCORG-ID-HERE"
  }
});

In the namespace key-value pair, MCORG is your Experience Cloud Organization ID. If you don’t have this ID, you can find it in the Administration section of the Experience Cloud dashboard. You need administrator permissions to view this dashboard. See Administration: Core Services.

Deprecated Functions

With the latest versions of DIL (6.2+), you don’t need to use these key-value pairs to pass in declared IDs. That’s because DIL now relies on the visitorService function shown in the code sample above. This function gets declared IDs from the Adobe Experience Platform Identity Service. However, we’re referencing these variables here for historical and legacy purposes. See the code below for an example of how to configure DIL.create to get a declared ID from the Visitor ID Service.
The following table describes the legacy variables used by the declaredId object:

Name
Type
Description
dpid
String
Data partner ID assigned by Audience Manager.
dpuuid
String
The data provider's unique ID for the user.

DPID and DPUUID

Audience Manager compares and matches the combined DPID and DPUUID to a corresponding user ID in our system. If an ID does not exist, Audience Manager creates a new user ID and synchronizes it to the DPID/DPUUID combination. Once Audience Manager matches or creates a user ID (the UUID) it returns that ID in the JSON response to the cookie in the client’s domain (first-party cookie) or other local storage.

Call this function when you’re using DIL v6.1 or earlier. However, this function has been deprecated in favor of the new version that gets declared IDs from the Adobe Experience Platform Identity Service.

DIL.create({
    partner : "partner name",
    declaredId : {
       dpuuid : dpuuid,
       DPID : dpid
    }
 });
NOTE
You need to programmatically develop the code that supplies the ID values for the d_dpuuid and d_dpid keys.

Pass In IDs After DIL Instantiates

NOTE
If you make an API call with a different declaredID combination, the new combination will be used for that call only. Further regular event calls will use the original DIL.create declaredID combination.
DIL.getDil('partner name').api.signals({...}).declaredId({
  dpuuid : dpuuid
  dpid : dpid
}).submit();

Request/Response Examples

The request sends a data provider and user ID to Audience Manager:

https://my_domain.net/event?d_rtbd=json&d_cb=myCallback&key=val&d_dpuuid=1234&d_dpid=5678

The response returns the Audience Manager ID (e.g., UUID) which is written to a first-party cookie in the page domain.

myCallback({
...
   "uuid":"abc123"
})

Do Not Target and Opt-Out Calls

The declared ID process honors site visitor preferences to opt-out of Audience Manager targeting by your website. When Audience Manager receives an opt-out request, the DCS returns an empty JSON object instead of the Audience Manager user ID.

de293fbf-b489-49b0-8daa-51ed303af695