SDK for C# / .NET reference guide

You can use the SDK for C# / .NET on the server side to encrypt raw UID2s to create UID2 tokens for sharing, and to decrypt UID2 tokens to access the raw UID2.

Overview

The functions outlined here define the information that you'll need to configure or can retrieve from the library. The parameters and property names defined below are pseudocode. Actual parameters and property names vary by language but will be similar to the information outlined here.

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 for Sharing	Decrypt UID2 Token to Raw UID2	Generate UID2 Token from DII	Refresh UID2 Token	Map DII to Raw UID2s	Monitor Rotated Salt Buckets
✅	✅	—	—	—	—

UID2 account setup

To integrate with UID2, you'll need to have a UID2 account. If you haven't yet created an account, first follow the steps described on the Account setup page.

API permissions

When initial account setup is complete, if you're a publisher, advertiser, or data provider, you'll receive instructions and a link to access the UID2 Portal, where you can:

• Generate credentials for your account.
• Optionally, configure other values, such as setting up information about team members.

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.

If you're a DSP, we'll send credentials to you.

Version

The library uses .NET Standard 2.1. unit tests. The sample app uses .NET 5.0.

GitHub repository/binary

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

• 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 bidstream tokens using the 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 then do one of the following:
   • If the bid request originated from a publisher's website, pass the domain name. The domain name must be all lower case, without spaces and without subdomain. For example, for Subdomain.DOMAIN.com, pass domain.com instead.
   • If the bid request originated from a mobile app, pass the app name.
   • Otherwise, pass null.

var decrypted = client.DecryptTokenIntoRawUid(uidToken, domainOrAppName);
// 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 sharing participant is a company that takes part in sharing, either as a sender or a receiver, to share UID2s with another participant.

Advertisers and data providers can use this SDK to share UID2s with other authorized UID2 sharing participants (tokenized sharing). They can encrypt raw UID2s into UID2 tokens and then send them to another participant for sharing in pixels (see Tokenized sharing in pixels). If you are not sending data in pixels, you can take part in UID2 sharing as long as you follow the requirements laid out in Security requirements for UID2 sharing.

important

The UID2 token generated during this process is for sharing only—you cannot use it in the bidstream. There is a different workflow for generating tokens for the bidstream: see Tokenized sharing in the bidstream.

The following instructions provide an example of how you can implement sharing using the 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.