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.
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.
The following are the options available for publishers to integrate with UID2:
- Client UID2 SDK for JavaScript (see UID2 SDK for JavaScript Reference Guide), with UID2 SDK for Java on the server.
- Client UID2 SDK for JavaScript (see UID2 SDK for JavaScript Reference Guide), with custom server code.
- 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.
TIP: To facilitate the process of establishing client identity using UID2 and retrieving UID2 tokens, consider using the UID2 SDK for JavaScript. For details, see Server-Side Integration Guide for JavaScript.
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 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: 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 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.
Step | Endpoint | Description |
---|---|---|
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 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. |
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
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.
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. |
TIP: 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 Application
A sample application is available for server-only integration. See:
- Server-Only UID2 Integration Example (sample application)
- Server-Only UID2 Integration Example (readme)
FAQs
For a list of frequently asked questions for the publisher audience, see FAQs for Publishers.