CTV Integration Guide

If you're a Connected TV (CTV) publisher, there are several ways that you can integrate with UID2 to generate and refresh identity tokens to be passed into the RTB bidstream in the context of your CTV apps.

Key Integration Steps

At a high level, to integrate with UID2, you'll implement these three key steps:

1. Generate the UID2 token.
2. Refresh the UID2 token as needed.
3. Pass the UID2 token into the bidstream.

To determine how you'll implement these steps, choose from the CTV Integration Options.

Integrating with Single Sign-On (SSO)

If you integrate with one or more SSO providers to offer SSO login, you might be able to retrieve the logged-in user's email address from the SSO provider to generate UID2 tokens.

For details, see Publisher Integration with SSO Providers.

Private Operator Option

If you're a publisher and want to keep your first-party data within your corporate network, you might choose to deploy a Private Operator. In this scenario, you choose to host a private instance exclusively for your own use.

For additional information, review these resources:

• The UID2 Operator
• UID2 Private Operator Integration Overview

note

The UID2 Private Operator solutions do not support client-side generation of the UID2 token. If you want a client-side implementation, you must use a Public Operator solution.

Complete UID2 Account Setup and Configure Account

To integrate with UID2, you'll need to have a UID2 account. If you haven't yet created an account, first follow the steps described on the Account Setup page.

When initial account setup is complete, you'll receive instructions and a link to access the UID2 Portal, where you can create your credentials for the production environment and configure additional values, if needed. For details, see Getting Started with the UID2 Portal.

The specific values you set up will depend on which of the CTV integration options you choose:

• For a client-server or server-side implementation, you'll need to set up these values, in the UID2 Portal on the API Keys page:

  • API key, also called a client key

  • Client secret, a value known only to the participant and the UID2 service

    important

    It's very important that you keep these values secure. For details, see Security of API Key and Client Secret.

• For a client-side implementation, you'll need to set up these values, in the UID2 Portal on the Client-Side Integration page:
  • Subscription ID and Public Key: See Adding and Managing Key Pairs
  • A list of domain names for any sites on which you'll be using this SDK: See Adding and Managing Root-Level Domains
  • Mobile App IDs (any that apply): See Adding and Managing Mobile App IDs

CTV Integration Options

You can decide on the integration option that's best for you based on where you want to generate and refresh the UID2 token. There are three options, as shown in the following table.

Option	Details
Client-Side Integration	The token is generated and refreshed on the client side.
Server-Side Integration	The token is generated and refreshed on the server side.
Client-Server Integration	The token is generated on the server side and refreshed on the client side.

Client-Side Integration for CTV Apps

The client-side option is for publishers who want to manage the UID2 token entirely on the client side:

• The token is generated on the client side, in the CTV app.
• The token is refreshed as needed on the client side, from within the CTV app.

This setup requires that all code changes are done within the CTV app.

To implement using this approach, follow the instructions in the UID2 Client-Side Integration Guide for Mobile.

The following table shows supported operating systems, with links to applicable documentation resources.

Operating System	Integration Guide	Link to SDK Guide
Apple tvOS	UID2 Client-Side Integration Guide for Mobile	SDK for iOS Reference Guide
Android TV	UID2 Client-Side Integration Guide for Mobile	SDK for Android Reference Guide

Server-Side Integration for CTV Apps

The server-side option is for publishers who want to manage the UID2 token entirely on the server side:

• The token is generated on the server side.
• The token is refreshed as needed on the server side.

This setup requires that most of the code changes are done on the server side, with minimal changes in the CTV app.

Another advantage of this approach is that if you're dealing with multiple platforms (Web / CTV / mobile), doing everything on the server side can reduce platform-specific efforts.

To implement using this approach, follow the instructions in Publisher Integration Guide, Server-Side.

If your server-side code is in Java or Python, you can use one of the UID2 SDKs to make the HTTP requests to UID2, instead of writing your own source code. For details, refer to one of the following SDK guides:

• SDK for Java Reference Guide: Usage for Publishers
• SDK for Python Reference Guide: Usage for Publishers

Client-Server Integration for CTV Apps

This option is for publishers who want to manage the UID2 tokens with a client-server approach:

• The token is generated on the server side.
• The token is refreshed as needed on the client side, from within the CTV app.

To implement using this approach, follow the instructions in the UID2 Client-Server Integration Guide for Mobile.

The following table shows supported operating systems, with links to applicable documentation resources.

Operating System	Integration Guide	Link to SDK Guide
Apple tvOS	UID2 Client-Server Integration Guide for Mobile	SDK for iOS Reference Guide
Android TV	UID2 Client-Server Integration Guide for Mobile	SDK for Android Reference Guide

Best Practices

The following points are best practices for CTV integrations:

• Rotate tokens in advance

  CTV ad activity is tied to traffic spikes during ad breaks; generating or refreshing UID2 tokens during these times is not ideal. We recommend that you generate or refresh tokens before these busy times.

  If the token was refreshed before its expiration date, you can use either the new or the old token for a while, until the old token expires. The TTL (time to live) timestamp is part of the response body returned by the UID2 Operator when the token is generated or refreshed.

• Rotate tokens only when needed

  The UID2 token is tied to a user's HEM or phone, not to the viewing session or app session. As long as you have a valid UID2 token for the user, there is no need to generate a new token for each new viewing session or app session. For example, if the user leaves your app and then opens the app again, there is no need to generate a new UID2 token if the existing one is still fresh.

• Use the same token for multiple ad slots within a pod

  As long as the UID2 token is valid throughout the pod duration, you can use it for any ad slot within the pod.

Ideally, if you follow these guidelines, there is no need to generate a new UID2 token during an ad break.