UID2 (Unified ID 2.0)

💡
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

Configure the Cookie Name

Keep the pre-populated default cookie name (uid2_identity) or edit it to a different name. The cookie param name used is uid2ServerCookie which is supported by Prebid 7 and 8 (uid2Cookie is only supported by Prebid 8 so HTL BID will not update to it yet for compatibility with previous versions).

The cookie will be used to store the ID values the publisher extracts.

💡
Leave the cookie field empty if you don’t want to use the uid2ServerCookie param. For example, if you want to use __uid2_advertising_token instead, leave the UI field empty and store the token in a different param.
image

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 uid2ServerCookie name should match the name entered in the HTL BID UI

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