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.
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:
- Sender: Publisher. Account Setup in the UID2 Portal is optional.
- Receiver: DSP. See Information for Sharing Receivers.
Implementation Options for Senders
The following approaches are available for encrypting the DII directly into a UID2 token for sending in the bidstream.
| Integration Option | Token Generated Client-Side or Server-Side? | Integration Guide |
|---|---|---|
| Prebid.js | Client-Side | UID2 Client-Side Integration Guide for Prebid.js |
| Prebid.js | Server-Side | UID2 Client-Server Integration Guide for Prebid.js |
| JavaScript SDK | Client-Side | Client-Side Integration Guide for JavaScript |
| JavaScript SDK | Server-Side | Client-Server Integration Guide for JavaScript |
| Java SDK | Server-Side | SDK for Java Reference Guide |
| Python SDK | Server-Side | SDK for Python Reference Guide |
| UID2 API (token generate and refresh) | Server-Side | UID2 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.
For a complete SDK summary, see SDK Functionality. For a complete summary of integration approaches for publishers, see Publisher Integrations.
Decryption Options for Receivers
The following approaches are available for decrypting UID2 tokens.
| Scenario | Link to Doc |
|---|---|
| Tokenized sharing from raw UID2s with SDK | Implementing Sharing Encryption/Decryption with an SDK |
| Tokenized sharing from raw UID2s with Snowflake | Implementing Sharing Encryption/Decryption Using Snowflake |
| Tokenized sharing in the bidstream from DII | DSP Integration Guide |
| Tokenized sharing in tracking pixels from DII | Workflow: Tokenized Sharing in Tracking Pixels |
| Tokenized sharing in creative pixels from raw UID2s | Workflow: 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:
-
Set up integration with UID2:
-
Publisher: Use one of the integration options listed in Implementation Options for Senders.
Optional to restrict which DSPs can decrypt your UID2 tokens: Set up sharing permissions in the UID2 Portal. See Account Setup in the UID2 Portal.
-
DSP: Use one of the integration options listed in Decryption Options for Receivers.
-
-
The publisher completes the following steps to create and send the UID2 tokens:
- Generates a UID2 token from an email or phone number.
- Puts the UID2 token into the bidstream.
-
The DSP completes the following steps:
- Receives the UID2 tokens.
- Decrypts the UID2 tokens into raw UID2s.
- 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.
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 Example | Process/User | Result |
|---|---|---|
| user@example.com | Convert 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: