Skip to main content

Tokenized Sharing in the Bidstream

UID2 data shared to the bidstream must be in the form of UID2 tokens generated by encrypting directly identifying information (DII) (an email address or phone number) directly into a UID2 token.

Publishers can encrypt the DII into a UID2 token, using one of the implementation options, and then send the UID2 token into the bidstream.

Other sharing participants might also use this form of tokenized sharing. For example, an advertiser might use it for creating a UID2 token for a tracking pixel.

caution

Data in the bidstream can be accessed by unauthorized parties, so it is never acceptable to share raw UID2s in the bidstream. If you're sharing in the bidstream, tokenized sharing is required.

Additional information for publishers is on the following pages:

Audience

Tokenized sharing in the bidstream is applicable to the following audiences:

Implementation Options for Senders

The following approaches are available for encrypting the DII directly into a UID2 token for sending in the bidstream.

Integration OptionToken Generated Client-Side or Server-Side?Integration Guide
Prebid.jsClient-SideUID2 Client-Side Integration Guide for Prebid.js
Prebid.jsServer-SideUID2 Server-Side Integration Guide for Prebid.js
JavaScript SDKClient-SideClient-Side Integration Guide for JavaScript
JavaScript SDKServer-SideServer-Side Integration Guide for JavaScript
Java SDKServer-SideUID2 SDK for Java Reference Guide
Python SDKServer-SideUID2 SDK for Python Reference Guide
UID2 API (token generate and refresh)Server-SideUID2 Endpoints Summary: UID2 Tokens

These options support generating UID2 tokens from email addresses or phone numbers and also refreshing the tokens regularly. Other SDKs do not support token generate and token refresh at this time.

Decryption Options for Receivers

The following approaches are available for decrypting UID2 tokens.

ScenarioLink to Doc
Tokenized sharing from raw UID2s with SDKImplementing Sharing Encryption/Decryption with an SDK
Tokenized sharing from raw UID2s with SnowflakeImplementing Sharing Encryption/Decryption Using Snowflake
Tokenized sharing in the bidstream from DIIDSP Integration Guide
Tokenized sharing in tracking pixels from DIIWorkflow: Tokenized Sharing in Tracking Pixels
Tokenized sharing in creative pixels from raw UID2sWorkflow: Tokenized Sharing in Creative Pixels

Account Setup in the UID2 Portal

For sharing in the bidstream, the sender does not need a UID2 Portal account. We automatically set up any publisher to share with all DSPs. However, if you are a publisher and want to limit your sharing scope, you can request a UID2 Portal account and set up sharing permissions. For example, you might want to share with a limited audience of one or more sharing partners for security or other reasons.

All sharing receivers must set up an account in the UID2 Portal.

The sender only needs to set up sharing permission once for each receiver or participant type. However, if you want to add new sharing permissions or change existing ones, you'll need to go back to adjust your settings.

For details, see UID2 Portal: Overview and follow the links for each task.

Workflow: Tokenized Sharing in the Bidstream

The workflow for generating UID2 tokens from DII, via the API or the specified server-side SDKs, consists of the following steps:

  1. Set up integration with UID2:

  2. The publisher completes the following steps to create and send the UID2 tokens:

    1. Generates a UID2 token from an email or phone number.
    2. Puts the UID2 token into the bidstream.
  3. The DSP completes the following steps:

    1. Receives the UID2 tokens.
    2. Decrypts the UID2 tokens into raw UID2s.
    3. Checks that the UID2s are not opted out. For details, see Honor User Opt-Outs. If they are not opted out, uses the raw UID2s for bidding.

The following diagram illustrates the UID2 sharing workflow for publishers.

UID2 Sharing Permission Integration Workflow for publishers

Token Example for Publishers in the Bidstream

Publishers convert the input email address or phone number directly to a UID2 token for use in the bidstream, as shown in the following example.

Input ExampleProcess/UserResult
user@example.comConvert normalized email/phone number to UID2 token:
POST /token/generate endpoint
NOTE: If you're using an SDK, the SDK manages token generation.
KlKKKfE66A7xBnL/DsT1UV/Q+V/r3xwKL89Wp7hpNllxmNkPaF8vdzenDvfoatn6sSXbFf5DfW9wwbdDwMnnOVpPxojkb8KYSGUte/FLSHtg4CLKMX52UPRV7H9UbWYvXgXC4PaVrGp/Jl5zaxPIDbAW0chULHxS+3zQCiiwHbIHshM+oJ==

Information for Sharing Receivers

To be able to decrypt a UID2 token into a raw UID2, you must be an authorized sharer and have the sender's cryptographic keys.

By default, for publishers sending UID2 tokens to the bidstream, the publisher's cryptographic keys are shared with all authorized DSPs. However, if a publisher has set up specific sharing relationships, you'll only receive that publisher's cryptographic keys if the publisher has created a sharing relationship with you.

For details, see Receiving UID2 Tokens from Another Sharing Participant.

It's important to set up a regular cadence for refreshing cryptographic keys, and to decrypt UID2 tokens promptly.

For details, see the following sections in UID2 Sharing: Best Practices: