Skip to main content

UID2 SDK for C# / .NET Reference Guide

You can use the UID2 SDK for C# / .NET on the server side to facilitate the following:

  • Encrypting raw UID2s to create UID2 tokens for sharing.
  • Decrypting UID2 tokens to access the raw UID2s.

Functionality

This SDK simplifies integration with UID2 for any DSPs or UID2 sharers who are using C# / .NET for their server-side coding. The following table shows the functions it supports.

Encrypt Raw UID2 to UID2 TokenDecrypt UID2 TokenGenerate UID2 Token from DIIRefresh UID2 Token
SupportedSupportedNot supportedNot supported

API Permissions

To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the Account Setup page.

You'll be granted permission to use specific functions offered by the SDK, and given credentials for that access. Bear in mind that there might be functions in the SDK that you don't have permission to use.

For details, see API Permissions.

Version

This documentation is for the UID2 .NET SDK version 5.6.0 and above. The SDK is built for .NET Standard 2.0.

GitHub Repository/Binary

This SDK is in the following open-source GitHub repository:

The binary is published in this location:

Initialization

DSPs should create an instance of the BidstreamClient class. Sharers should create an instance of the SharingClient class.

You will need to provide the values necessary for the SDK to authenticate with the UID2 service.

ParameterDescription
endpointThe endpoint for the UID2 service. See Environments.
authKeyThe API key. See UID2 Credentials.
secretKeyThe client secret. See UID2 Credentials.

Interface

The BidstreamClient class allows you to decrypt UID2 tokens into raw UID2s.

For details on the bidding logic for handling user opt-outs, see DSP Integration Guide.

The SharingClient class allows you to encrypt raw UID2s into UID2 tokens and decrypt UID2 tokens into raw UID2s.

note

When you use an SDK, you do not need to store or manage decryption keys.

Encryption Response Content

When encrypting with the SharingClient, the SDK returns the following information:

PropertyDescription
StatusThe encryption result status. For a list of possible values and definitions, see Encryption Response Statuses.
EncryptedDataThe encrypted UID2 token.

Encryption Response Statuses

ValueDescription
SuccessThe raw UID2 was successfully encrypted and a UID2 token was returned.
NotAuthorizedForKeyThe requester does not have authorization to use the encryption key.
NotAuthorizedForMasterKeyThe requester does not have authorization to use the master key.
NotInitializedThe client library is waiting to be initialized.
KeysNotSyncedThe client has failed to synchronize keys from the UID2 service.
KeyInactiveThe encryption key is not active.
EncryptionFailureA generic encryption failure occurred.

Decryption Response Content

Whether decrypting with the BidstreamClient or the SharingClient, the SDK returns the following information:

PropertyDescription
StatusThe decryption result status. For a list of possible values and definitions, see Decryption Response Statuses.
UidThe raw UID2 for the corresponding UID2 token.
EstablishedThe timestamp indicating when a user first established the UID2 with the publisher.

Decryption Response Statuses

ValueDescription
SuccessThe UID2 token was decrypted successfully and a raw UID2 was returned.
NotAuthorizedForKeyThe requester does not have authorization to decrypt this UID2 token.
NotInitializedThe client library is waiting to be initialized.
InvalidPayloadThe incoming UID2 token is not a valid payload.
ExpiredTokenThe incoming UID2 token has expired.
KeysNotSyncedThe client has failed to synchronize keys from the UID2 service.
VersionNotSupportedThe client library does not support the version of the encrypted token.

Usage for DSPs

The following instructions provide an example of how you can decode bid stream tokens using the UID2 SDK for .NET as a DSP.

  1. Create a BidstreamClient:
var client = new BidstreamClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY);
  1. Refresh once at startup, and then periodically (recommended refresh interval is hourly):
client.Refresh();
  1. Decrypt a token into a raw UID2. Pass the token, and the domain name of the site where the bid originated from. The domain name must be all lower case, without spaces and without subdomain. For example, for Subdomain.DOMAIN.com , pass domain.com instead:
var decrypted = client.DecryptTokenIntoRawUid(uidToken, domain);
// If decryption succeeded, use the raw UID2.
if (decrypted.Success)
{
// Use decrypted.Uid.
}
else
{
// Check decrypted.Status for the failure reason.
}

For a full example, see the ExampleBidStreamClient method in SampleApp/Program.cs.

Usage for UID2 Sharers

A UID2 sharer is any participant that wants to share UID2s with another participant. Raw UID2s must be encrypted into UID2 tokens before sending them to another participant.

warning

The UID2 token generated during this process is for sharing only—you cannot use it in the bid stream. There is a different workflow for generating tokens for the bid stream: see Sharing in the Bid Stream.

The following instructions provide an example of how you can implement sharing using the UID2 SDK for C# / .NET, either as a sender or a receiver.

  1. Create a SharingClient:
var client = new SharingClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY);
  1. Refresh once at startup, and then periodically (recommended refresh interval is hourly):
client.Refresh();
  1. If you are a sender, call EncryptRawUidIntoToken:
var encrypted = client.EncryptRawUidIntoToken(rawUid);
// If encryption succeeded, send the UID2 token to the receiver.
if (encrypted.Success)
{
// Send encrypted.EncryptedData to receiver.
}
else
{
// Check encrypted.Status for the failure reason.
}

If you are a receiver, call DecryptTokenIntoRawUid:

var decrypted = client.DecryptTokenIntoRawUid(uidToken);
// If decryption succeeded, use the raw UID2.
if (decrypted.Success)
{
// Use decrypted.Uid.
}
else
{
// Check decrypted.Status for the failure reason.
}

For a full example, see the ExampleSharingClient method in SampleApp/Program.cs.

FAQs

For a list of frequently asked questions for DSPs, see FAQs for DSPs.