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 the existing 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:
- Retrieve a set of encryption keys
- Decrypt UID2 tokens into raw UID2s
- Periodically re-retrieve the latest set of encryption keys
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:
The UID2 SDK for C# / .NET uses a DecryptTokenIntoRawUid
function to perform these steps: see BidstreamClient.cs, line 15.
Check the Token Version
There are different UID2 token versions in current use, and later processing steps are a little different depending on whether the token version is v2 or a later version.
You can check the token version using the first few bytes of the token.
To review detailed logic, see UID2Encryption.cs, lines 36-50.