Skip to content

integration-ctv-guide.md

Latest commit

 

History

History
143 lines (90 loc) · 8.61 KB

integration-ctv-guide.md

File metadata and controls

143 lines (90 loc) · 8.61 KB
title CTV Integration Guide
sidebar_label CTV
pagination_label CTV Integration Guide
description Summary of options for UID2 mobile integration.
hide_table_of_contents false
sidebar_position 4
displayed_sidebar docs

import Link from '@docusaurus/Link'; import SnptIntegratingWithSSO from '../snippets/_snpt-integrating-with-sso.mdx'; import SnptPreparingEmailsAndPhoneNumbers from '../snippets/_snpt-preparing-emails-and-phone-numbers.mdx'; import SnptPrivateOperatorOption from '../snippets/_snpt-private-operator-option.mdx';

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 or regenerate the UID2 token frequently to ensure the token stays current.

    For details, see Keeping the Token Current and Recommended Token Refresh Frequency.

  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)

Preparing DII for Processing

Private Operator Option

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:

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:

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.