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

• 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 JavaScript Standard Integration Guide.

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:

1. Establish identity: user login
2. Bid using a UID2 token
3. Refresh a UID2 token
4. Clear Identity: user logout

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.

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.