UID2 (Unified ID 2.0)

  • Enable Prebid and UID2 in the UI
  • Configure the modules params
  • Add Email Hashing
  • Cookie Refresh for New ID Events
  • Review the UID2 Implementation
  • Server Side vs. Client Side
  • Gotchas
💡
HTL can add the UID2 module in the pbjs object and pass the cookie name for the publisher to use. HTL cannot extract or manage ID information, only provide the necessary tools for publishers to do so. HTL BID does not call, load or manage the UID2 SDK or the __uid2 calls (__uid2.init and __uid2.disconnect()). Visit the Prebid Unified ID (UID2) Prebid documentation or the GitHub repo.

Enable Prebid and UID2 in the UI

Both Prebid and the UID2 modules need to be enabled

image
image
image

Configure the modules params

  • Cookie Name: The cookie will be used to store the ID values the publisher extracts.
  • Subscription ID: You should receive your Id during account setup
  • Server Public Key: You should receive your Id during account setup
💡
Leave the cookie field empty if you don’t want to use the uid2ServerCookie param.
💡
We suggest using client side integration since its much easier to setup and maintain.

To use client side integration simply leave the cookie name field blank and only fill in the Subscription ID and the Server Public Key

image

Add Email Hashing

For suggested steps on how to hash an email, follow steps 1 through 4 here: Email-ashing-for-identity-partners Depending on the version of htlbid client being used on page, you need to use a different function to load the Hashed Email into identity partner modules:

  • For htlbid client v2, use setFirstPartyData() function.
  • For htlbid client v3, use setUserData() function.

Cookie Refresh for New ID Events

💡
Cookie refresh needs to be done for the UID2 module after there is an event that can generate a new ID (eg. user logs in). This will generate the IDs for new users.

Order of events for the UID2 cookie refresh:

  1. 1. ID generation event (eg. user login)
  2. 2. Publisher creates the cookie using the name configured in HTL BID (eg. uid2_identity)
  3. 3. Publisher fires the UID2 cookie refresh function to generate and store the new ID. It can either refresh all ID modules or only the UID2 module See: https://docs.prebid.org/dev-docs/publisher-api-reference/refreshUserIds.html 
    4. // Refresh all
pbjs.refreshUserIds();

// Refresh specific modules
pbjs.refreshUserIds({ submoduleNames: ['uid2'] });

Review the UID2 Implementation

Use pbjs.getConfig('userSync.userIds'); in the console to see the ID modules and corresponding params in pbjs. The params should match what you have configured in CW UI

image
image

Server Side vs. Client Side

The UID2 implementation has two different parts:

  1. UID2 Prebid module to receive the ID/token
  2. ID/token generation

Part 1, adding the UID2 module to the Prebid configuration, is managed by HTL BID. This happens directly in the browser, on the client side. The UID2 module is added and a param for the cookie is created for the publisher to store the ID info (if applicable). When available, the Prebid UID2 module will automatically pass the ID from the cookie to the bid stream.

Part 2, generating the ID/token, can be done several ways according to The Trade Desk. When the UID2 integration uses the Prebid UID2 Module (instead of the JS SDK integration) and the publisher wants to handle the ID/token server-side, the only call on server needed is to refresh the token whenever there are login events. Besides this, all other calls are handled on the client side by the Prebid UID2 module directly.

There is a server-side only integration TTD does not recommend for integrations, as it requires additional management of refresh calls.

Gotchas

Parsing errors can happen if the cookie is stored with the incorrect top-level object/wrapper names. The top-level must be the keys advertising_token and identity_expires.

Using structures like {response: {advertising_token ...}} instead of {advertising_token ...} directly as the top-level will fail.

Incorrect:

image

Correct:

image