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 Token	Decrypt UID2 Token	Generate UID2 Token from DII	Refresh UID2 Token
Supported	Supported	Not supported	Not 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:

• UID2 SDK for .NET

The binary is published in this location:

• https://www.nuget.org/packages/UID2.Client

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.

Parameter	Description
endpoint	The endpoint for the UID2 service. See Environments.
authKey	The API key. See UID2 Credentials.
secretKey	The 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:

Property	Description
Status	The encryption result status. For a list of possible values and definitions, see Encryption Response Statuses.
EncryptedData	The encrypted UID2 token.

Encryption Response Statuses

Value	Description
Success	The raw UID2 was successfully encrypted and a UID2 token was returned.
NotAuthorizedForKey	The requester does not have authorization to use the encryption key.
NotAuthorizedForMasterKey	The requester does not have authorization to use the master key.
NotInitialized	The client library is waiting to be initialized.
KeysNotSynced	The client has failed to synchronize keys from the UID2 service.
KeyInactive	The encryption key is not active.
EncryptionFailure	A generic encryption failure occurred.

Decryption Response Content

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

Property	Description
Status	The decryption result status. For a list of possible values and definitions, see Decryption Response Statuses.
Uid	The raw UID2 for the corresponding UID2 token.
Established	The timestamp indicating when a user first established the UID2 with the publisher.

Decryption Response Statuses

Value	Description
Success	The UID2 token was decrypted successfully and a raw UID2 was returned.
NotAuthorizedForKey	The requester does not have authorization to decrypt this UID2 token.
NotInitialized	The client library is waiting to be initialized.
InvalidPayload	The incoming UID2 token is not a valid payload.
ExpiredToken	The incoming UID2 token has expired.
KeysNotSynced	The client has failed to synchronize keys from the UID2 service.
VersionNotSupported	The 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);

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

client.Refresh();

3. 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.

important

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 Tokenized 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);

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

client.Refresh();

3. 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.