Skip to content

Latest commit

 

History

History
81 lines (52 loc) · 8.31 KB

custom-publisher-integration.md

File metadata and controls

81 lines (52 loc) · 8.31 KB
Raw

UID2 API Documentation > v1 > Integration Guides > Custom Publisher Integration Guide

Overview

This guide covers integration steps for app developers and CTV broadcasters who would like to generate identity tokens utilizing UID2 for the bid stream. This guide focuses on publishers who would like to integrate directly with UID2 to create and manage tokens rather than integrate with UID2-enabled single-sign-on or identity providers.

Integration Steps

The following integration steps outline the lifecycle for a user establishing a UID2 token with a publisher and how the UID2 token integrates with the RTB bid stream.

Custom Publisher Flow

1. Establish Identity

This section focuses on publisher-specific steps 1-d, 1-e, and 1-f illustrated in the above diagram.

Note
The UID2 token must only be generated on the server side after authentication. Security concerns forbid token generation on the browser side.

Step Endpoint/SDK Instruction
d GET /token/generate There are two ways for publishers to establish identity with UID2.
1. Integrate with a UID2-enabled single-sign-on provider.
2. Generate UID2 tokens when a user authenticates using the GET /token/generate endpoint. The request includes a user's normalized email address or the base64-encoded SHA256 hash of the user's normalized email address. Click here to view email normalization rules.
e GET /token/generate The token generation service returns UID2 tokens.
f Place the returned advertising_token and refresh_token in a store tied to a user. You may consider client-side storage like a first-party cookie or server-side storage.

2. Bid Using UID2 Tokens

This section focuses on publisher-specific step 2-a illustrated in the above diagram.

Step Endpoint/SDK Instruction
a The publisher sends the advertising_token from 1 to the SSP for bidding. Send the value as-is.

3. Refresh Tokens

Leverage the refresh endpoints to retrieve the latest version of UID2 tokens. UID2 token refreshes are required to sync a user's UID2 rotation and opt-out status. If a user opts out, using their refresh token will end their token refresh chain.

Step Endpoint/SDK Instruction
a When a user returns to an asset and becomes active again, refresh the identity token before sending it to the SSP.
b GET /token/refresh Send the refresh_token obtained in 1 as a query parameter.
c GET /token/refresh The UID2 service issues a new identity token for users that haven't opted out.
d Place the returned advertising_token and refresh_token in a store tied to a user. You may consider client-side storage like a first-party cookie or server-side storage.

We recommend refreshing active user identity tokens every 5 minutes. There is no need to refresh tokens for inactive users.

4. User Logout

Step Endpoint/SDK Instruction
a The user logs out from a publisher asset.
b Remove the UID2 tokens you have stored for that user. No interaction with the UID2 service is required.

Frequently Asked Questions

Do I need to decrypt tokens?

No, publishers do not need to decrypt tokens.

How will I be notified of user opt-out?

The token refresh process handles user opt-outs. Using their refresh token automatically clears their session and disrupts their refresh_token chain when a user opts out. No manual action is required.

What is the uniqueness and rotation policy for UID2 token?

The UID2 service encrypts tokens using random initialization vectors. The encrypted UID2 is unique for a given user as they browse the internet. At every refresh, the token re-encrypts. This mechanism ensures that untrusted parties cannot track a user's identity.

How can I test my integration?

There are two built-in tools you can use to test your integration.

Test that PII sent and returned tokens match

You can use the GET /token/validate endpoint to check whether the PII you are sending through GET /token/generate is valid.

  1. Send a GET /token/generate request using [email protected] as email, or create a base64-encoded SHA256 hash of [email protected] and send it through as an email hash. Store the advertising_token returned to use in step 2.
  2. Send a GET /token/validate request using the email or email_hash you sent in step 1 and the token as the advertising_token returned in step 1. If the response returns true, the email or email_hash you sent as a request in step 1 match the token you received in the response of step 1. If it returns false, there may be an issue with the way you are sending email addresses or email hashes.

Test refresh token logout workflow

You can use the email address [email protected] to test your token refresh workflow. Using this email for the request always generates an identity response with a refresh_token that results in a logout response.

  1. Send a GET /token/generate request using [email protected] as email, or create a base64-encoded SHA256 hash of [email protected] and send it through as an email hash. Store the refresh_token returned to use in step 2.
  2. Send a GET /token/validate request using the email or email_hash you sent in step 1 and the refresh_token as the refresh_token returned in step 1. The body response should be empty because the [email protected] email always results in a logged out refresh token.