SDK for C++ Reference Guide

You can use the SDK for C++ 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++ 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 SDK requires C++ version 11.

GitHub Repository/Binary

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

• SDK for C++.

Release tags are available in the following GitHub location, but you must build your own binaries:

• https://github.com/IABTechLab/uid2-client-cpp11/tags

Initialization

The initialization function configures the parameters necessary for the SDK to authenticate with the UID2 service. It also allows you to configure retry intervals in the event of errors.

Parameter	Description	Recommended Value
endpoint	The endpoint for the UID2 service.	N/A
authKey	The authentication token that belongs to the client. For access to UID2, see Contact Info.	N/A

Interface

The interface allows you to decrypt UID2 advertising tokens and return the corresponding raw UID2.

note

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

If you're a DSP, for bidding, call the interface to decrypt a UID2 advertising token and return the UID2. For details on the bidding logic for handling user opt-outs, see DSP Integration Guide.

The following is the decrypt method in C++:

#include <uid2/uid2client.h>
using namespace uid2;
 
const auto client = UID2ClientFactory::Create(baseUrl, apiKey, secretKey);
client->Refresh(); //Note that Refresh() should be called once after create(), and then once per hour
const auto result = client->Decrypt(adToken);

Response Content

Available information returned through the SDK is outlined in the following table.

Function	Description
GetStatus()	The decryption result status. For a list of possible values and definitions, see Response Statuses.
GetUid()	The raw UID2 for the corresponding UID2 advertising token.
GetEstablished()	The timestamp indicating when a user first established the UID2 with the publisher.

Response Statuses

Value	Description
Success	The UID2 advertising token was decrypted successfully and a raw UID2 was returned.
NotAuthorizedForKey	The requester does not have authorization to decrypt this UID2 advertising token.
NotInitialized	The client library is waiting to be initialized.
InvalidPayload	The incoming UID2 advertising token is not a valid payload.
ExpiredToken	The incoming UID2 advertising 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 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.

For an example of usage, see com.uid2.client.test.IntegrationExamples (runSharingExample method).

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

1. Create an IUID2Client shared pointer:

   const auto client = UID2ClientFactory::Create(baseUrl, apiKey, secretKey);

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

   client->Refresh();

3. Senders:

   1. Call the following:

      EncryptionResult encrypted = client->Encrypt(rawUid);

   2. If encryption succeeded, send the UID2 token to the receiver:

      if (encrypted.IsSuccess()) 
      {
          // send encrypted.GetEncryptedData() to receiver
      }
      else 
      {
          // check encrypted.GetStatus() for the failure reason
      }

4. Receivers:

   1. Call the following:

      DecryptionResult decrypted = client->Decrypt(uidToken);

   2. If decryption succeeded, use the raw UID2:

      if (decrypted.IsSuccess())
      {
         // use decrypted.GetUid() 
      } 
      else 
      {
         // check decrypted.GetStatus() for the failure reason 
      }

FAQs

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