TTD：UID2 usage guide

Overview

This article mainly introduces related concepts of UID2: for example, how to use it, and how developers should set UID2 correctly while using or integrating with TradPlus products.

What is UID2

Unified ID 2.0 (UID2) leverages encrypted email and phone number data to provide a privacy-conscious, secure, and accurate identity standard for the entire digital advertising ecosystem.(source：https://unifiedid.com/docs/intro)

UID2, like cookies, IDFA, and GAID, is a pseudonymous ID used to identify users and maintain the normal operation of programmatic advertising. However, UID2 has specific cross-platform tracking properties. When a user logs in via email or mobile phone and authorizes tracking, the UID2 Operator generates an encrypted, secure "pseudonymous universal ID" based on this. As long as the user browses other web pages or apps with the same email or mobile phone number, all websites, apps, and platforms that support UID2 can track the user's activity by detecting the presence of the same UID2 token.

The Trade Desk (TTD) is committed to promoting UID2 to become the new standard in the industry, as an alternative solution to cookies, to enable targeted advertising while maintaining user privacy. (source：https://iabtechlab.com/blog/the-impact-of-the-trade-desk-contributing-uid-2-0-for-industry-development/)

Image Source:the Trade Desk

How UID2 is different

Privacy-conscious: Data is processed through several layers of hashing, and tokens are encrypted, to prevent re-identification, with a rotating salt value adding extra security.
Interoperable: UID2 integrates with other deterministic and personally identifiable information-based identifiers, extending its utility when consumers log in across the open internet — including on Connected TV.
Portable: Since UID2 has been adopted by many leading ad tech providers and platforms, it’s easy for participants to use the identity strategies that work best for them, with the partners they choose.
Omnichannel: Authentication is increasing across traditional digital, mobile apps, and especially Connected TV — enabling cross-device and cross-channel identity strategies without cookies.

How developers use UID2

The figure below shows the process of how developers add UID2 to the bidding request through an SSP.

A user visits a publisher website, mobile app, or CTV app.
The publisher provides transparency around its data practices and asks the user to provide an email address or phone number.
Once the user has provided an email address or phone number, the publisher sends it to the UID2 Operator via an SDK or direct API integration.
A publisher can authorize an SSO provider or identity provider to pass DII on their behalf.
The UID2 Operator:

Takes the email or phone number.
Performs the salt, hash, and encryption process.
Returns the UID2 token.

The publisher stores the UID2 token to share with SSPs during real-time bidding.

Server-side: The publisher stores the token in a mapping table, DMP, data lake, or other server-side application.
Client-side: The publisher stores the token in a client-side app or in the user’s browser as a first-party cookie.

The publisher retrieves the UID2 token from storage.
The publisher sends the UID2 token to the SSP.
The SSP puts the bid request, with the UID2 token, into the bidstream.

Image Source: IABTechLab/uid2docs

UID2 Token application and usage process

How to apply for UID2 Token

Click "Request access" on the UID2 official website to submit information application, address https://unifiedid.com/request-access .

If you need help, you can contact TradPlus AM.

UID2 Client-Side Integration with the TradPlus SDK

If you have user phone/phoneHash/email/emailHash access in your app, follow these instructions so that UID2 tokens can be generated within the TradPlus SDK.

Please follow the TradPlus SDK integration documentation to integrate the ad source, and use the following process to quickly generate and use UID2 tokens for ad monetization.

Special statement: To facilitate developers downloading and using the TTD UID2 SDK, TradPlus only provides download instructions. This does not mean that TradPlus assumes any responsibility for the data collection and processing activities of the TTD UID2 SDK. Developers should choose whether to download and use the TTD UID2 SDK. If developers choose to use the TTD UID2 SDK, they should work with TTD to strictly comply with applicable data protection laws and fulfill obligations such as obtaining end-user consent and cross-border data transmission reporting and certification.

Android

Minimum target Android version: 4.4+ / API 19+ (SDK) 5.0+ / API 21+ (Dev-App)

TradPlus version: V12.3.0.1+

1.Gradle

Get the uid2_adapter aar from download address and add it to the project

implementation 'com.uid2:uid2-android-sdk:1.4.0'
implementation files("libs/uid2_adapter_v1.0.0.aar")

ProGuard Configuration

-keep class com.data.uid2.adapter.** {*;}
-keep interface com.data.uid2.adapter.TTDUID2Manager$ResultCallback{*;}

2.API Description：

Called before initializing TP SDK
You can set one or more of phone, phoneHash, email, emailHash.
Format requirements:
- Email: Follow Email Address Normalization (removing period is only for gmail.com)
- Mobile phone number: Follow Phone Number Normalization
For specific format requirements, please refer to the document https://unifiedid.com/docs/getting-started/gs-normalization-encoding
If the format does not meet the requirements, UID2 will crash internally. The developer must pass in parameters that meet the requirements.
When considering which value to provide, prioritize by phone > phoneHash > email > emailHash
subscriptionId and publicKey are required fields, obtained from the UID2 account back end.
- A set of subscriptionId and publicKey for Integration Testing Environment is different to a set for Production Environment as described in https://unifiedid.com/docs/getting-started/gs-environments

ttd_server_url is optional, used to modify the UID2 server address

Test:
- Set ttd_test to "true" to enable test mode
- Package name: com.data.uid2
- The default test UID2 service address is https://operator-integ.uidapi.com (integration testing environment)
- The test returns Success result

3.Code Sample

Map<String, String> mLocalExtras = new HashMap<>();
// Only for test
String ttdEmail = "janesaoirse@gmail.com";
String ttdEmailHash = "ku4mBX7Z3qJTXWyLFB1INzkyR2WZGW4ANSJUiW21iI8=";
String ttdPhone = "+12345678901";
String ttdPhoneHash =  "10e6f0b47054a83359477dcb35231db6de5c69fb1816e1a6b98e192de9e5b9ee"

mLocalExtras.put("ttd_email", ttdEmail);
mLocalExtras.put("ttd_email_hash", ttdEmailHash);
mLocalExtras.put("ttd_phone", ttdPhone);
mLocalExtras.put("ttd_phone_hash", ttdPhoneHash);
//mLocalExtras.put("ttd_server_url", "Modify UID2 server address");

// Only for test
mLocalExtras.put("ttd_test", "true");
String subscriptionId = "toPh8vgJgt";
String publicKey = "UID2-X-I-MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKAbPfOz7u25g1fL6riU7p2eeqhjmpALPeYoyjvZmZ1xM2NM8UeOmDZmCIBnKyRZ97pz5bMCjrs38WM22O7LJuw==";

TTDUID2Manager.getInstance().startUID2(this,
    subscriptionId,
    publicKey,
    mLocalExtras,
    new TTDUID2Manager.ResultCallback() {
        @Override
        public void result(String result) {

        }
});

iOS

1.Access requirements and methods

System requirements: iOS version 13.0+, Swift version 5.0+

TradPlus version: 12.0.0+

Get TTDUID2Adatper.framwork from download address and add it to the project.

Integrate UID2SDK through pod

pod 'UID2','1.2.4'

2.API Description：

It is recommended to call before initializing TradPlusSDK
You can set one or more of phone, phoneHash, email, emailHash. The phone/phoneHash/email/emailHash passed in has format requirements, and random passing may cause it to not work properly. Please refer to the UID2 official documentation: https://unifiedid.com/docs/getting-started/gs-normalization-encoding.
To consider which value to provide, use this priority: phone > phoneHash > email > emailHash.
subscriptionID and serverPublicKey are required fields, obtained from the UID2 account back end.
- A set of subscriptionId and publicKey for the integration testing environment is different to a set for the production environment, as described in https://unifiedid.com/docs/getting-started/gs-environments.
appName is an optional field. By default, the current app package name will be obtained.
customURLString is optional and is used to modify the UID2 server address.
isTestMode is set to true to start the test environment.
When the test environment is turned on, the default customURLString is: https://operator-integ.uidapi.com

3.Code Sample

//OC
#import <TTDUID2Adatper/TTDUID2Adatper.h>

[TTDUID2ManagerAdatper sharedInstance].email = @"abc@abc.com";
//[TTDUID2ManagerAdatper sharedInstance].emailHash = @"";
//[TTDUID2ManagerAdatper sharedInstance].phone = @"";
//[TTDUID2ManagerAdatper sharedInstance].phoneHash = @"";
[TTDUID2ManagerAdatper sharedInstance].subscriptionID = @"toPh8vgJgt";
[TTDUID2ManagerAdatper sharedInstance].serverPublicKey = @"UID2-X-I-MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKAbPfOz7u25g1fL6riU7p2eeqhjmpALPeYoyjvZmZ1xM2NM8UeOmDZmCIBnKyRZ97pz5bMCjrs38WM22O7LJuw==";
//[TTDUID2ManagerAdatper sharedInstance].appName="";
//[TTDUID2ManagerAdatper sharedInstance].isTestMode = YES;
//[TTDUID2ManagerAdatper sharedInstance].customURLString = @"";
[[TTDUID2ManagerAdatper sharedInstance] startWithCallback:^(NSError * _Nonnull error) {
    MSLogInfo(@"error %@",error);
}];

//Swift
import TTDUID2Adatper

TTDUID2ManagerAdatper.sharedInstance().email = "abc@abc.com";
//TTDUID2ManagerAdatper.sharedInstance().emailHash = "";
//TTDUID2ManagerAdatper.sharedInstance().phone = "";
//TTDUID2ManagerAdatper.sharedInstance().phoneHash = "";
TTDUID2ManagerAdatper.sharedInstance().subscriptionID = "toPh8vgJgt";
TTDUID2ManagerAdatper.sharedInstance().serverPublicKey = "UID2-X-I-MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKAbPfOz7u25g1fL6riU7p2eeqhjmpALPeYoyjvZmZ1xM2NM8UeOmDZmCIBnKyRZ97pz5bMCjrs38WM22O7LJuw==";
//TTDUID2ManagerAdatper.sharedInstance().appName="";
//TTDUID2ManagerAdatper.sharedInstance().isTestMode = true;
//TTDUID2ManagerAdatper.sharedInstance().customURLString = "";
TTDUID2ManagerAdatper.sharedInstance().start { error in
    if(error == nil)
    {
        print(TTDUID2ManagerAdatper.sharedInstance().getToken());
    }
};

Unity

1.Access requirements and methods

TradPlus Unity Plugin version requirement: 1.2.3+

Android

Gradle introduction

Get uid2_adapter aar through download address and add it to the project

implementation 'com.uid2:uid2-android-sdk:1.4.0'
implementation files("libs/uid2_adapter_v1.0.0.aar")

ProGuard Configuration

-keep class com.data.uid2.adapter.** {*;}
-keep interface com.data.uid2.adapter.TTDUID2Manager$ResultCallback{*;}

Get TTDUID2Adatper.framwork from download address and add it to the Assets directory of the Unity project

Integrate UID2SDK through pod

pod 'UID2','1.2.4'

2. Call and parameter description

It is recommended to call before initializing the TradPlus SDK.
You can set one or more of phone, phoneHash, email, emailHash.
The phone/phoneHash/email/emailHash passed in has format requirements, and random passing may cause it to not work properly. Please refer to the official UID2 documentation: https://unifiedid.com/docs/getting-started/gs-normalization-encoding.
To consider which value to provide, use this priority: phone > phoneHash > email > emailHash.
subscriptionID and serverPublicKey are required fields, obtained from the UID2 account backend
- A set of subscriptionId and publicKey for Integration Testing Environment is different to a set for Production Environment as described on https://unifiedid.com/docs/getting-started/gs-environments
appName is an optional field, and the current app package name will be obtained by default (only supported by iOS).
customURLString is optional and is used to modify the UID2 server address.
isTestMode is set to true to start the test environment.
When the test environment is enabled, the default customURLString is: https://operator-integ.uidapi.com

3.Code Sample

TTDUID2Extra extra = new TTDUID2Extra();
extra.email = "abc@abc.com";
//extra.emailHash = "";
//extra.phone = "";
//extra.emailHash = "";
extra.subscriptionID = "toPh8vgJgt";
extra.serverPublicKey = "UID2-X-I-MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKAbPfOz7u25g1fL6riU7p2eeqhjmpALPeYoyjvZmZ1xM2NM8UeOmDZmCIBnKyRZ97pz5bMCjrs38WM22O7LJuw==";
//extra.appName = "";
//extra.isTestMode = true;
//extra.customURLString = "";
TradplusAds.Instance().startUID2(extra);

 TradplusAds.Instance().OnUID2StartFinish += OnUID2StartFinish;
 
void OnUID2StartFinish(string errrorMsg)
{
    if(errrorMsg == null)
    {
        Configure.Instance().ShowLog("OnUID2StartFinish");
    }
    else
    {
        Configure.Instance().ShowLog("OnUID2StartFinish ------ errrorMsg:" + errrorMsg);
    }
}

TradplusAds.Instance().OnUID2StartFinish -= OnUID2StartFinish;

Flutter

1. Access requirements and methods

TradPlus Flutter version requirements: 1.1.6+

Android

Gradle introduction

Get uid2_adapter aar through download address and add it to the project

implementation 'com.uid2:uid2-android-sdk:1.4.0'
implementation files("libs/uid2_adapter_v1.0.0.aar")

ProGuard Configuration

-keep class com.data.uid2.adapter.** {*;}
-keep interface com.data.uid2.adapter.TTDUID2Manager$ResultCallback{*;}

Get TTDUID2Adatper.framwork from download address and add it to the Assets directory of the Unity project

Integrate UID2SDK through pod

pod 'UID2','1.2.4'

2. Call and parameter description

It is recommended to call before initializing TradPlus SDK.
You can set one or more of phone, phoneHash, email, emailHash. The phone/phoneHash/email/emailHash passed in has format requirements, and random passing may cause it to not work properly. Please refer to the official UID2 documentation: https://unifiedid.com/docs/getting-started/gs-normalization-encoding.
To consider which value to provide, use this priority: phone > phoneHash > email > emailHash.
subscriptionID and serverPublicKey are required fields, obtained from the UID2 account back end.
- A set of subscriptionId and publicKey for Integration Testing Environment is different to a set for Production Environment as described on https://unifiedid.com/docs/getting-started/gs-environments
appName is an optional field, and the current app package name will be obtained by default (only supported by iOS).
customURLString is optional and is used to modify the UID2 server address.
isTestMode is set to true to start the test environment.
When the test environment is enabled, the default customURLString is: https://operator-integ.uidapi.com

3.Code Sample

static TTDUID2Listener? uid2Listener;

Map? extraMap = ttdUID2Manager.createUID2ExtraMap(
      email: "abc@abc.com",
 //     emailHash："",
 //     phone："",
 //     phoneHash："",
      subscriptionID:"toPh8vgJgt",
      serverPublicKey:"UID2-X-I-MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKAbPfOz7u25g1fL6riU7p2eeqhjmpALPeYoyjvZmZ1xM2NM8UeOmDZmCIBnKyRZ97pz5bMCjrs38WM22O7LJuw==",
 //     appName："",
 //    isTestMode: true,
 //     customURLString:""
  );

  uid2Listener = TTDUID2Listener(startFinish:(error){
    if(error != null)
    {
		// Android returns Success to indicate success. There will be no null return. 
		// iOS returns null to indicate success
      TPAdConfiguration.showLog('UID2 startFinish :  error = $error');
    }
    else
    {
      TPAdConfiguration.showLog('UID2 startFinish');
    }
 });
 ttdUID2Manager.setInitListener(uid2Listener!);
 if(extraMap != null)
 {
   ttdUID2Manager.start(extraMap);
 }

Integration Using Server-Side UID2 Token Generation

Follow this instruction if one of the following applies to you:

You have followed the UID2 Server-Side Publisher Integration Guide and are generating (and refreshing) UID2 tokens on the server side.
You have followed the UID2 Client-Server Integration Guide for Mobile and are generating UID2 tokens on the server side and refreshing the tokens within your app using UID2 mobile SDKs. These instructions show you how to use (or transfer) the UID2 token into the TradPlus SDK.

Important prerequisite: Please ensure that you have obtained the UID2 Token from the official TTD channel.

If you have successfully obtained the UID2 Token from the official TTD channel, please follow the TradPlus SDK docking document for ad source integration, and use the following code for development settings

Android

Attention: Android 1.0.1 and above support UID2 Token transmission.
Attention: The following code is recommended to be set and fetched before initializing the TradPlus SDK .

  UserDataInfo userDataInfo = new UserDataInfo();
  userDataInfo.setAdvertisingToken(token);
  TPSettingManager.getInstance().setUserDataInfo(userDataInfo);

iOS

Attention: iOS V 9.8.0 and above support UID2 Token transmission.
Attention: The following code is recommended to be set and fetched before initializing the TradPlus SDK .

 TradPlusUID2Info *UID2Info = [[TradPlusUID2Info alloc] init];
 UID2Info.UID2Token = @"Your UID2Token";
 [[TradPlus sharedInstance] setUID2Info:UID2Info];

Unity

Attention: The following code is recommended to be set and fetched before initializing the TradPlus SDK .

 Dictionary<string, object> settingMap = new Dictionary<string, object>();
 settingMap.Add("uid2_token", "Your UID2Token");
 TradplusAds.Instance().SetSettingDataParam(settingMap);

Flutter

Attention: The following code is recommended to be set and fetched before initializing the TradPlus SDK .

 Map settingMap = {"uid2_token": "Your UID2Token"};
 TPSDKManager.setSettingDataParam(settingMap);

Overview​

What is UID2​

How UID2 is different​

How developers use UID2​

UID2 Token application and usage process​

How to apply for UID2 Token​

UID2 Client-Side Integration with the TradPlus SDK​

Android​

1.Gradle​

ProGuard Configuration​

2.API Description：​

3.Code Sample​

iOS​

1.Access requirements and methods​

2.API Description：​

3.Code Sample​

Unity​

1.Access requirements and methods​

ProGuard Configuration​

2. Call and parameter description​

3.Code Sample​

Flutter​

1. Access requirements and methods​

ProGuard Configuration​

2. Call and parameter description​

3.Code Sample​

Integration Using Server-Side UID2 Token Generation​

Android​

iOS​

Unity​

Flutter​

Reference​

Overview

What is UID2

How UID2 is different

How developers use UID2

UID2 Token application and usage process

How to apply for UID2 Token

UID2 Client-Side Integration with the TradPlus SDK

Android

1.Gradle

ProGuard Configuration

2.API Description：

3.Code Sample

iOS

1.Access requirements and methods

2.API Description：

3.Code Sample

Unity

1.Access requirements and methods

ProGuard Configuration

2. Call and parameter description

3.Code Sample

Flutter

1. Access requirements and methods

ProGuard Configuration

2. Call and parameter description

3.Code Sample

Integration Using Server-Side UID2 Token Generation

Android

iOS

Unity

Flutter

Reference