Skip to main content

Publisher Integration Guide, Server-Only

This guide is for publishers who want to generate UID2 tokens (advertising tokens) for the RTB bidstream, 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:

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 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.

Publisher Flow

The following sections provide additional details for each step in the diagram:

  1. Establish identity: capture user data
  2. Bid using a UID2 token
  3. Refresh a UID2 token
  4. 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.

StepEndpointDescription
1-dPOST /token/generateThere 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-ePOST /token/generateReturn 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-fN/APlace 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.

StepEndpointDescription
2-aN/ASend 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 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.

StepEndpointDescription
3-aN/AWhen a user returns to an asset and becomes active again, refresh the UID2 token before sending it to the SSP.
3-bPOST /token/refreshSend the refresh_token obtained in step 1-e as a query parameter.
3-cPOST /token/refreshThe UID2 service issues a new identity token for users that haven't opted out.
3-dN/APlace 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.

StepEndpointDescription
4-aN/AThe user logs out from a publisher asset.
4-bN/ARemove 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:

FAQs

For a list of frequently asked questions for the publisher audience, see FAQs for Publishers.