Publisher Integration Guide, Server-Side
This guide is for publishers who want to integrate with UID2 to generate UID2 tokens (advertising tokens) for the RTB bidstream, with all integration activity on the server side.
The following options are available for publishers to integrate with UID2 on the server side:
- SDK for Java (see Usage for Publishers section).
- SDK for Python (see Usage for Publishers section).
- Custom server code to generate and refresh the UID2 token by calling the POST /token/generate and POST /token/refresh endpoints.
There is also a sample implementation that demonstrates the workflow. See Sample Implementation.
For a complete summary of publisher integration options, see Publisher Integrations.
To facilitate the process of establishing client identity using UID2 and retrieving UID2 tokens, consider using the SDK for JavaScript. For details, see Client-Server Integration Guide for JavaScript.
Introduction
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 opportunities to capture email or phone number: for example, promotional exchanges, sign-ups and subscriptions, or marketing form fills.
- Manage UID2 identity information and use it for targeted advertising
- Refresh UID2 tokens
- Deal with missing identities
- Manage user opt-outs
See also FAQs.
Integration Steps
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 bidstream.
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: capture user data
- Bid using a UID2 token
- Refresh a UID2 token
- Clear Identity: user logout
Establish Identity: Capture User Data
After authentication in step 1-c, which 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.
Rather than calling this endpoint directly, you could use one of the SDKs to manage it for you. For a summary of options, see SDKs: Summary.
| Step | Endpoint | Description |
|---|---|---|
| 1-d | POST /token/generate | Establish identity with UID2 by using 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 advertising_token and refresh_token in a store tied to a user. You might consider client-side storage, such as a first-party cookie, or server-side storage. |
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.
| Step | Endpoint | Description |
|---|---|---|
| 2-a | N/A | Send the advertising_token from step 1-e to the SSP for bidding. Send the value as is. |
For an example of what a UID2 token might look like in the bidstream, when it's sent from an SSP to a DSP, see What does a UID2 token look like in the bidstream?.
Refresh a UID2 Token
Use the 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.
For details about the UID2 opt-out workflow and how users can opt out, see User Opt-Out.
| Step | Endpoint | Description |
|---|---|---|
| 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 refresh_token obtained in step 1-e as a query parameter. |
| 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 POST /token/refresh endpoint, advertising_token and refresh_token, so that they are linked to the user. You might consider client-side storage, such as a first-party cookie, or server-side storage. |
Refresh tokens starting from the refresh_from timestamp, which is part of the identity returned by the POST /token/generate or POST /token/refresh endpoints.
Clear Identity: User Logout
If the user logs out, do not use the UID2 token.
| Step | Endpoint | Description |
|---|---|---|
| 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. |
Sample Implementation
A sample implementation is available for server-side integration. See:
- Server-Side UID2 Integration Example (sample implementation)
- Server-Side UID2 Integration Example (readme)
FAQs
For a list of frequently asked questions for the publisher audience, see FAQs for Publishers.