Information

Title	Extended User Identification

URL Name	Extended-User-Identification

Details

Article Body

Overview

User identification across the inventory chain from Supply to Demand 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.
Since third party cookie based user identification is 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 Holistic+, 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 the Ad API - reference article).

Warning
The source key (see eids[].source here) of extended Ids must always correspond to a known identifier on Equativ's side (see list in chapter "Logging" below).

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 the Tagging guide). 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
You can customize the automatic transfer of ID5 Ids with these parameters in the sas.setup() method:

Key_____________	Type___	Default value	Description
partnerId	STRING	102	the ID5 partner Id; the Id assigned to Equativ is 102
pd	STRING		optional; partner-supplied data used for linking ID5 Ids across domains; more details here

Sample

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

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:

Key________________	Type____	Default value___	Description
placementId	NUMBER		mandatory; the publisher-specific placement Id to be obtained from your Liveramp account manager
storageType	STRING	"localStorage"	optional; the storage type
detectionType	STRING	"scrapeAndUrl"	optional; the mode to detect a valid identifier
urlParameter	STRING	"email"	optional; a URL parameter to be checked by the library, e. g. in case of "email", if the user lands on example.com/alerts?email=user@liveramp.com, the library will check the value in the email URL parameter
cssSelectors	STRING	['input[type=text]', 'input[type=email]']	optional; CSS selectors where to detect valid identifiers; e. g. in case of ['input[type=text]','input[type=email]'], the library will automatically detect valid identifiers entered into input fields of type text or email

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 the Tagging guide). 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.

Extended Ids are not supported for AMP inventory!

Example OneCall POST

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>

Example Generic POST

// 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 Header Bidding with Prebid.js - client-side integration). Upgrading to the latest prebid.js version is recommended.

Sending extended Ids in Holistic+ integrations

A Holistic+ 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.

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 Holistic+ integrations

A Managed Holistic+ integration is similar to Holistic+ integrations (see previous chapter) but the administration of prebid.js is done directly in the Managed Holistic+ UI provided by Equativ. The setup in the UI is explained in chapter "User ID configuration" in the Managed Holistic+ article.
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; more details about DMP integration in Audience data — API integration — v2.

Logging

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

the provider as sent in the source field (see "Sending extended ids with OneCall" above)
the provider name
the Id Equativ assigns to the provider

Provider (source field)	Provider name	Equativ Id
Unknown	Unknown	0
adserver.org	Unified ID	2
pubcid.org	PubCommon	3
liveramp.com	Identity Link	4
id5-sync.com	ID5	5
criteo.com	Criteo	6
digitru.st	Digitrust	7
netid.de	netID	8
sharedid.org	Shared Id	9
britepool.com	BritePool	10
quantcast.com	Quantcast	11
intentiq.com	IntentIQ	12
neustar.biz	Neustar Fabrick	13
audigent.com	Halo ID	14
zeotap.com	Zeotap IDplus	15
idx.lat	Retargetly IDx	16
liveintent.com	LiveIntent	17
crwdcntrl.net	Lotame Panorama	18
merkleinc.com	Merkle ID	19
parrable.com	Parrable ID	20
admixer.net	Admixer ID	21
nextroll.com	Nextroll ID	22
novatiq.com	Snowflake ID	23
tapad.com	Tapad ID	24
verizonmedia.com	Verizon Media ConnectID	25
mediawallahscript.com	OpenLink ID	26
deepintent.com	Deepintent	27
hcn.health	DMD	28
amxrtb.com	AMX	29
uidapi.com	Unified ID 2.0	30
akamai.com	Akamai DAP	31
justtag.com	Just ID	32
navegg.com	Navegg ID	33
trustpid.com	Trustpid	34
first-id.fr	First ID	35
anonymised.io	Anonymised	36
adquery.io	Adquery	37
trust.id	SCID	38
euid.eu	EUID	39
smartadserver.com	Equativ	40
utiq.com	Utiq	41
hemsha256	HEMs encoded in Sha256	42
ip	IP address	43
33across.com	Lexicon ID (33Across)	44
esp.criteo.com	Criteo - OB	45

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 (more details about frequency capping here).

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 (more details about the uid parameter here).

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

Notes

Extended User Identification