Overview

User identification is critical to allow for targeting (audience targeting, retargeting etc.), frequency capping and other features.

Traditionally, user identification across the programmatic ecosystems is done by each player dropping a cookie with a unique user id and then synching this id with all other players in the ecosystem. With third party cookie based user identification being increasingly blocked by browsers, new providers and initiatives have emerged to allow for cookieless and universal user identification. This article explains Equativ's support of these providers. 

Equativ’s extended Ids (eids) support

To embrace the cookieless user identification era, Equativ follows the Extended Identifiers (eids) specification (see IAB OpenRTB 3.0 specification and IAB AdCOM v1.0 specification). Extended Ids are sometimes referred to as "alternative Ids". Equativ supports extended Ids as follows:

• publishers can sign up with a supported user identification provider and send the user Ids in ad calls to Equativ’s system; see list of supported providers below in chapter “Logging”
• Equativ logs the presence of a user Id from a supported provider in the ad call and makes it available in Instant Report Builder (see chapter "Reporting" below) and in the Reporting API
• Equativ forwards all eids received in the ad calls to the DSPs in the bid requests

General guidelines

Equativ recommends to implement these guidelines:

• start contacting and implementing user identification providers as soon as possible - it is free for publishers (see list of  providers below in chapter “Logging” and in the User ID module documentation of prebid.js)
• recommended providers: Criteo, ID5, TTD, Liveramp
• choose user identification providers depending on your individual integration (smart.js, prebid.js etc. - see "Sending extended Ids to Equativ by integration type" below
• in case of managed unified auctions, enable the provider "Criteo" at minimum; Criteo does not require any registration nor integration work
• get back to Equativ in case of questions, concerns, or issues

Sending extended Ids to Equativ by integration type

Sending extended Ids with the POST Ad API

In Equativ's POST Ad API, you can send extended Ids with the eids array in generic POST and OneCall POST requests (more details in chapter "Object: Uid" in POST Ad API integration: parameter reference).  

Sending extended Ids with the GET Ad API

With Equativ's GET Ad API, you can send extended Ids using the eids parameter (both video and display), as specified by the IAB openRTB specs. The extended Id payload must be Base64 encoded. 

Example base64 encoded payload

Payload prior to encoding 

[
  {
    "source": "id5-sync.com",
    "uids": [
      {
        "id": "ID5*OuTYi5CSJCAxVhkyOTVE4QR7XrFKmyfZnIesZg5rCVYntjO9MRRHhwHU0maldIz2J7jlk9FRFsTVCfNhk1G4hCe5Rg7mQt9wcsp4nh_Z-GMnvN0BUBOpSRzyMwa1avyPJ7-OelDPsCncR0O_Ac2eoyfAQqx3KaMsNbKT96iaQBknwpOuk0TbTUJ3KsQNHLo-J8P51wJGoCtECjaJX3_Z6CfE1HbprSuSijc-5NEl4TMnxb4hPR6YYdmxSAeMdO3oJ8hxU8eCcxe74APyqVtZ-SfL0LtBLLwftOm3eDj3dt4nzMAM2G5LPZqpnRp6c8-0J853_LH3uVRK491ygwuonifPuePUSmPxGZNVgqirCXUn0Dybvn9BJOcSWIQxuJR4J9Js5Vj9VzCeyqNvUaeC6ifTvIrn24k2SURApp0cRqUn1Sgnipzeb1Kut-zTQsy-J9Yx7Nl3tTkLt4B2ybSNZyfX-HP5lfWHP9Z51dEWceA",
        "ext": {
          "abTestingControlGroup": false
        }
      }
    ]
  }
]

base64 encoded payload

eids=WwogIHsKICAgICJzb3VyY2UiOiAiaWQ1LXN5bmMuY29tIiwKICAgICJ1aWRzIjogWwogICAgICB7CiAgICAgICAgImlkIjogIklENSpPdVRZaTVDU0pDQXhWaGt5T1RWRTRRUjdYckZLbXlmWm5JZXNaZzVyQ1ZZbnRqTzlNUlJIaHdIVTBtYWxkSXoySjdqbGs5RlJGc1RWQ2ZOaGsxRzRoQ2U1Umc3bVF0OXdjc3A0bmhfWi1HTW52TjBCVUJPcFNSenlNd2ExYXZ5UEo3LU9lbERQc0NuY1IwT19BYzJlb3lmQVFxeDNLYU1zTmJLVDk2aWFRQmtud3BPdWswVGJUVUozS3NRTkhMby1KOFA1MXdKR29DdEVDamFKWDNfWjZDZkUxSGJwclN1U2lqYy01TkVsNFRNbnhiNGhQUjZZWWRteFNBZU1kTzNvSjhoeFU4ZUNjeGU3NEFQeXFWdFotU2ZMMEx0QkxMd2Z0T20zZURqM2R0NG56TUFNMkc1TFBacXBuUnA2YzgtMEo4NTNfTEgzdVZSSzQ5MXlnd3VvbmlmUHVlUFVTbVB4R1pOVmdxaXJDWFVuMER5YnZuOUJKT2NTV0lReHVKUjRKOUpzNVZqOVZ6Q2V5cU52VWFlQzZpZlR2SXJuMjRrMlNVUkFwcDBjUnFVbjFTZ25pcHplYjFLdXQtelRRc3ktSjlZeDdObDN0VGtMdDRCMnliU05aeWZYLUhQNWxmV0hQOVo1MWRFV2NlQSIsCiAgICAgICAgImV4dCI6IHsKICAgICAgICAgICJsaW5rVHlwZSI6IDIsCiAgICAgICAgICAiYWJUZXN0aW5nQ29udHJvbEdyb3VwIjogZmFsc2UKICAgICAgICB9CiAgICAgIH0KICAgIF0KICB9Cl0

Sending extended Ids in web environments (smart.js) – automatic transfer: ID5, Liveramp, Utiq, The Trade Desk 

You can send extended Ids in web environments where Equativ's "smart.js" library is used (more details about the library in Tagging guide: get started. At this time, Equativ supports the automatic transfer of extended Ids from the providers:

• ID5
• Liveramp
• Utiq
• The Trade Desk

For other providers, see section "Sending extended Ids in web environments (smart.js) – manual transfer" below.

To use the automatic transfer, you must:

• call Equativ's smart.js library with your network Id; e. g. if your network Id is 123, then the smart.js library must be called as follows: <script src="//ced.sascdn.com/tag/123/smart.js" async></script>
• ask your contact at Equativ to enable the feature in your network 

ID5 specifics

In ID5, the partnerId representing Equativ is 102. This ID is persistent and cannot be changed. Optionally, you can send partner-supplied data used for linking ID5 IDs across domains, using the pd key (string, optional) in the sas.setup(), for example:  

sas.setup({ 
  networkid: 458,
  async: true,
  modules : {
    id5: {
      pd: 'some string',
    }
  }
});

For more information, see Passing Signals to ID5.

You can also reach out to your Equativ contact to disable the module globally. Alternatively, use the following method for a specific site: window.sas_useID5Module = false.

Liveramp specifics

The Liveramp API requires a publisher-specific placementID to be obtained from your Liveramp account manager.

By default, smart.js uses the Scrape and URL detection mode of the ats.js library (more about how identifiers are retrieved here).

You can customize the automatic transfer of Liveramp Ids with these parameters in the sas.setup() method:

Sample

sas.setup({ 
  networkid: 458,
  async: true,
  modules : {
    liveramp: {
      placementId: <the publisher placement ID>,
      storageType: "localStorage",
      detectionType: "scrapeAndUrl",
      urlParameter: "email",
      cssSelectors: ['input[type=text]', 'input[type=email]']
    }
  }
});

Utiq specifics

The automatic transfer of Utiq IDs works if the publisher is already using the Utiq script on the website. Note that Equativ retrieves and sends only the adtechpass (atid), but not the martechpass (mtid) - more details about the IDs here. The source field for Utiq is: utiq.com.

The Trade Desk specifics

The automatic transfer of The Trade Desk Unified IDs works if the publisher is already using the The Trade Desk script on the website. Equativ supports The Trade Desk's Unified ID 1.0 and Unified ID 2.0. In case of the Unified ID 2.0, the source field is uidapi.com in case of US users and euid.eu in case of European users.   

Sending extended Ids in web environments (smart.js) – manual transfer 

You can send extended Ids in web environments where Equativ's "smart.js" library is used (more details about the library in Tagging guide: get started. This section describes the manual setup of the transfer. For the automatic transfer, see previous section.

In case of the manual transfer, extended Ids are sent using the method sas.setEids(eids), which is available for both Generic POST and OneCall POST requests. 

The structure of the eids must follow the IAB's AdCOM 1.0 specification. Payloads can be base64 encoded (see example below).

The sas.setEids(eids), method must be called before the actual ad request is sent - for more details, get back to the user identification provider.

sas.cmd.push(function () {
  sas.setEids([
    {
      source: "id5-sync.com",
      uids: [
        {
          atype: 1,
          id: "my_ID_from_ID5",
          ext: {
          }
        }
      ]
    },
    {
      source: "criteo.com",
      uids: [
        {
          atype: 1,
          id: "my_ID_from_Criteo",
          ext: {
          }
        }
      ]
    }
  ]);
});
sas.cmd.push(function () {
  sas.call("onecall", {
    siteId: 317777,
    pageId: 1232599,
    formats: [{
        id: 84313,
        tagId: "sas_tag_001"
    }],
    target: 'iid=9448189'
  });
});
</script>

// Call this method as soon as the values are available from the user identification providers
sas.cmd.push(function () {
  sas.setEids([
    {
      source: "id5-sync.com",
      uids: [
        {
          atype: 1,
          id: "my_ID_from_ID5",
          ext: {
          }
        }
      ]
    },
    {
      source: "criteo.com",
      uids: [
        {
          atype: 1,
          id: "my_ID_from_Criteo",
          ext: {
          }
        }
      ]
    }
  ]);
});

// Now the call will include the eids from the providers
sas.cmd.push(function () {
  sas.call("std", {
    siteId: 317777,
    pageId: 1232599,
    formatId: 84313,
    tagId: 'sas_tag_001',
    target: 'iid=9448189'
  });
});

Sending extended Ids with prebid.js

In case of Equativ as a bidder in prebid.js, Equativ's prebid.js adapter automatically looks for eids, if they are provided by the publisher. This requires the implementation of the prebid.js User ID Module (see also chapter "User sync configuration" in Supply inventory with prebid.js header bidding. Upgrading to the latest prebid.js version is recommended.  

Sending extended Ids in unified auction integrations

A unified auction integration consists in a competition of direct campaigns, bids from Equativ's demand partners as well as bids from header bidding - the highest CPM wins the competition. For more information, see Set up and manage unified auction.

The configuration of prebid.js is done client-side:

• implement and configure the User ID Module provided by prebid.js
• retrieve the eid object using the pbjs.getUserIdsAsEids() method from prebid.js
• call sas.setEids() from smart.js with the eid object that was just retrieved from prebid.js (for more details, see chapter "Sending extended Ids in web environments (smart.js)" above

Sending extended Ids in managed unified auction integrations

A managed unified auction integration is similar to a unified auction integration but the administration of prebid.js is done directly in the UI provided by Equativ. The setup in the UI is explained in chapter "User ID configuration" in Set up and manage unified auction. 

Note that the extended Ids are sent to Equativ automatically using the sas.setEids() method (there are no further manual steps required).

Sending extended ids with Equativ's video plugin

Read the according technical documentation (chapter "Extended user identification options") which also provides a sample of the eids JSON configuration.

Sending extended Ids with Equativ's in-app SDKs

Sending extended Ids with Equativ's in-app SDKs (iOS/Android) is not supported. Please read the technical documentation to learn more on how to leverage IDFA, IDFV, UIDs etc.

Sending extended Ids in DMP integrations

Equativ supports one preferred extended Id provider per DMP; please get back to your contact at Equativ and indicate the provider whose extended Ids (alternative Ids) you intend to use.

Logging

Equativ logs the presence of a provider’s user id in the ad request. The table below shows the supported providers with:

• Provider as sent in the source field (see "Sending extended ids with OneCall" above)
• Provider name
• Equativ Id assigned to the provider by Equativ.

Frequency capping based on extended Ids

By default, frequency capping is implemented with a cookie (cookie name: pid) that contains a unique user id to identify the user.

Since third party cookies are increasingly blocked by browsers, Equativ also supports frequency capping based on extended ids. This feature requires activation in your network - please reach out to your contact at Equativ to have it enabled.

Note that only one provider can be enabled per customer network to be used as an alternative to cookie based frequency capping (list of providers below in chapter “Logging”). Once the provider is enabled in your network, Equativ will use this provider's ids to implement frequency capping whenever an ad call does not contain any user id from the pid cookie nor any user id sent through the uid parameter.

Reports

To create a report on extended IDs, go to Reports > Instant Report Builder and use these dimensions:

• Extended Ids - indicates the extended user Ids from user identification providers that were sent in the ad call to Equativ
• Has User Uid - indicates the number of times a Uid was or was not sent in the ad requests to Equativ. Uid is a publisher specific user Id. If a Uid is present in the ad request, it overrides the Pid.
• Has User Pid - indicates the number of times a Pid was or was not sent in the ad requests to Equativ. Pid is a user Id defined by Equativ and stored in an Equativ cookie called “pid”.