Publisher Integration Guide, Server-Only
This guide is for publishers who want to generate UID2 tokens (advertising tokens) for the RTB bid stream, while integrating directly with UID2 rather than UID2-enabled single-sign-on or identity providers.
The guide outlines the basic steps that you need to consider if you're building an integration without using a client-side or server-side SDK. For example, you need to decide how to do the following:
- Implement user login and logout
- Manage UID2 identity information and use it for targeted advertising
- Refresh UID2 tokens
- Deal with missing identities
- Manage user opt-outs
See also FAQs.
The following are the options available for publishers to integrate with UID2:
- Server-only integration, with UID2 SDK for Java or UID2 SDK for Python on the server.
- Server-only integration, with custom server code.
This guide provides information for the last two options.
There is also an example application that demonstrates the workflow. See Sample Application.
The following diagram outlines the steps required for a user to establish a UID2 token with a publisher and how the UID2 token integrates with the RTB bid stream.
If you're using a server-side SDK, the SDK takes care of all the steps that mention endpoints: for example, step 1-d, the publisher sends the user's DII to the token generation service.
The following sections provide additional details for each step in the diagram:
Establish Identity: User Login
After authentication in step 1-c, which includes getting the user's consent and allows the publisher to validate the user's email address or phone number, the publisher can send a request to generate a UID2 token, on the server side. The following table details the token generation steps.
|1-d||POST /token/generate||There are two ways for publishers to establish identity with UID2:|
- Integrate with a UID2-enabled single-sign-on provider.
- Use the POST /token/generate endpoint to generate a UID2 token using the normalized email address or phone number of the user.
|1-e||POST /token/generate||Return a UID2 token generated from the user's hashed or unhashed email address or phone number, plus associated values such as the refresh token.|
|1-f||N/A||Place the returned |
Bid Using a UID2 Token
Consider how you want to manage UID2 identity information and use it for targeted advertising; for example, to pass the returned UID2 token to SSPs.
|2-a||N/A||Send the |
NOTE: For an example of what a UID2 token might look like in the bid stream, when it's sent from an SSP to a DSP, see What does a UID2 token look like in the bid stream?
Refresh a UID2 Token
POST /token/refresh endpoint to make sure you always have a valid and up-to-date UID2 token. The UID2 token must be refreshed to sync with the UID2 rotation. In addition, the token refresh process checks the user's opt-out status, and if the user has opted out, no new token is sent. This ends the token refresh chain, and you must not use that UID2 token again.
|3-a||N/A||When a user returns to an asset and becomes active again, refresh the UID2 token before sending it to the SSP.|
|3-b||POST /token/refresh||Send the |
|3-c||POST /token/refresh||The UID2 service issues a new identity token for users that haven't opted out.|
|3-d||N/A||Place the values returned by the |
Clear Identity: User Logout
If the user logs out, do not use the UID2 token.
|4-a||N/A||The user logs out from a publisher asset.|
|4-b||N/A||Remove the UID2 token you've stored for that user. No interaction with the UID2 service is required.|
A sample application is available for server-only integration. See:
- Server-Only UID2 Integration Example (sample application)
- Server-Only UID2 Integration Example (readme)
For a list of frequently asked questions for the publisher audience, see FAQs for Publishers.