Skip to main content

DSP Direct Integration Instructions

This document provides instructions for DSPs who want to integrate with UID2 but who are using a programming language not supported by an existing UID2 SDK.

For a list of all SDKs, see SDKs: Summary.

Overview​

DSPs must be able to decrypt UID2 tokens to raw UID2s and verify the token validity, so that they can use the decrypted tokens for targeted advertising and bidding purposes. To do this, a DSP must do the following:

An example implementation, in the UID2 SDK for C# / .NET, is the BidstreamClient class: see BidstreamClient.cs.

This document refers to additional code sections from the C# / .NET SDK as examples.

Retrieve/Refresh Encryption Keys​

To retrieve or refresh the encryption keys, so that you can decrypt UID2 tokens into raw UID2s, you'll need to write code to do the following:

  • Encrypt the request.
  • Call the endpoint.
  • Decrypt the response.
  • Parse the response.

You'll call the following API endpoint:

/v2/key/bidstream

Refresh the keys once at startup, and then periodically (recommended refresh interval is hourly).

The UID2 SDK for C# / .NET uses a Refresh function. For details, see BidstreamClient.cs, line 26.

For an implementation example that shows encrypting the request and decrypting the response, see Encryption and Decryption Code Examples.

The decrypted API response is in JSON format, and includes site_data, the list of domains or app names that are allowed for the site.

To see how all the fields are parsed, refer to the UID2 SDK for C# / .NET parse function: see KeyParser.cs, lines 41-74.

After decrypting the token into a raw UID2, if the token was generated on the client side, you must use the information in site_data to verify that a specific domain or app name is on the list of names allowed for it. For details, see Verify the Domain or App Name.

Decrypt UID2 Tokens into Raw UID2s​

When you have current keys, you'll be able to decrypt a UID2 token into a raw UID2. You also need to check several conditions to make sure that the token is eligible for use in the bidstream.

You'll need to complete the following steps:

  1. Decrypt the token.

  2. Make sure token lifetime and expiration values are valid.

  3. Verify that the domain or app name is valid.

The UID2 SDK for C# / .NET uses a DecryptTokenIntoRawUid function to perform these steps: see BidstreamClient.cs, line 15.

Decrypt the Token​

Use the master key and site key to decrypt the token. For a code example, refer to the Decrypt function: see UID2Encryption.cs, line 29. This function decrypts UID2 tokens into raw UID2s as part of the UID2 SDK for C# / .NET.

Make Sure Token Lifetime and Expiration Are Valid​

For use in the bidstream, a token must be valid and current. You must do two things:

  • Make sure that the token hasn't expired.
  • Check that the token lifetime is a valid value.

For an example of code that makes sure the token hasn't expired, see UID2Encryption.cs, line 196.

To make sure that the token lifetime has a valid value, check these two conditions:

  • The lifetime of the token must not exceed the max_bidstream_lifetime_seconds value from the /v2/key/bidstream response.
  • The time until token generation value must not exceed the allow_clock_skew_seconds value.

For an example of how this is done, review the code for the DoesTokenHaveValidLifetimeImpl function: see UID2Encryption.cs, line 237.

Calculating Token Lifetime​

The calculation to make sure that the token lifetime is valid for bidstream use is as follows:

lifetime = token expiry - token generated

time until token generation = token generated - current time

The token includes a Token Generated field, which is updated if the token is refreshed, so we use this to calculate the token lifetime.

For Tokens Generated on the Client Side: Verify the Domain or App Name​

For tokens generated on the client side, after decrypting the token, you must verify that the domain name or app name is valid. To do this, make sure the domainOrAppName value is included in the domain_names list of the site ID, within the site_data section of the response from the /v2/key/bidstream API endpoint.

For an example of code that does this, refer to the IsDomainOrAppNameAllowedForSite function in UID2Encryption.cs, line 245.

For more information about client-side UID2 integration, refer to one of these integration guides:

Honor User Opt-Out After Token Decryption​

After decrypting the token, you must check the resulting raw UID2 against your opt-out records. If it appears in your opt-out records, you must honor the user's opt-out preference, including by not using the UID2 for bidding.

For more information, refer to Honor User Opt-Outs in the DSP Integration Guide.