UID2 Client-Side Integration Guide for Mobile
This guide is for mobile app publishers who want to integrate with UID2 with changes only within their mobile app.
These instructions do not apply to publishers who want to use a Private Operator, or who want to generate tokens server-side. Those publishers should follow the Client-Server Integration Guide for Mobile.
This page provides a high-level overview of integration steps and links to additional documentation.
UID2 provides mobile SDKs for Android and iOS. Each SDK has the following features:
- Generates a UID2 identity (a UID2 token and associated values) and persists it in local file storage.
- Automatically refreshes UID2 tokens.
This guide uses the group term UID2 mobile SDKs to include both the SDK for Android and the SDK for iOS.
For FAQs relating to mobile publisher integrations, see FAQs for Mobile Integrations.
To integrate with UID2 client-side, you'll need to complete the following steps:
-
Check that the token was successfully generated and then pass it for bidstream use.
-
Optionally, integrate the UID2 GMA/IMA Plugin for GAM Secure Signals integration.
Mobile SDK Version
This guide provides instructions for using version 1.2.0 or higher of either of these UID2 mobile SDKs:
- SDK for Android
- SDK for iOS
For instructions for installing the correct SDK/version into your mobile app, see Add the UID2 Mobile SDK to Your Mobile App.
Client-Side Integration Example
For an example of how to configure a UID2 mobile SDK, and how to generate tokens using client-side integration for mobile, you can try out the UID2 development app.
Follow the applicable instructions, for Android or iOS:
- Android
- iOS
- Check out the main branch of the SDK for Android source code repository on GitHub.
- In Android Studio (check the version required in the Minimum Requirements section in the SDK for Android Reference Guide), open the directory that you checked out.
- Run the dev-app app.
- When you've started the app, make sure that the Client Side checkbox is checked.
- Enter an email or phone number, and then click the arrow to the right.
-
Check out the main branch of the UID2 SDK For iOS source code repository on GitHub.
-
In Xcode, open this project file:
Development/UID2SDKDevelopmentApp/UID2SDKDevelopmentApp.xcodeproj
-
Run the UID2SDKDevelopmentApp app scheme.
-
When you've started the app, make sure that the Client Side checkbox is checked.
-
Enter an email or phone number, and then click the arrow to the right.
Behind the scenes, the development app makes the following UID2 SDK API call. This call sends a request to the UID2 service to generate an identity (a UID2 token and associated values) for the email/phone input:
- Android
- iOS
UID2Manager.getInstance().generateIdentity(
identityRequest: IdentityRequest,
subscriptionId: String,
publicKey: String,
onResult: (GenerateIdentityResult) -> Unit
)
UID2Manager.shared.generateIdentity(
_ identity: IdentityType,
subscriptionID: String,
serverPublicKey: String,
appName: String? = nil
)
When the API call is successful, the app displays the resulting identity and persists it inside the UID2Manager
class.
The identity includes the generated UID2 advertising token value, which you can retrieve using the getAdvertisingToken()
method call:
- Android
- iOS
UID2Manager.getInstance().getAdvertisingToken()
UID2Manager.shared.getAdvertisingToken()
This method call returns the value that you need to make an ad request: see Pass Generated Token for Bidstream Use.
Testing With Your Own Configuration
By default, the development app uses default values for Subscription ID and public key, which are stored in the following object:
- Android
- iOS
com.uid2.dev.ui.MainScreenViewModel.Companion
RootViewModel
By default, the development app is configured to connect to the UID2 integration environment, as specified in the following Android method call/iOS file:
- Android
- iOS
com.uid2.UID2Manager.Companion#init
see UID2SDKDevelopmentApp/UID2SDKDevelopmentApp/Info.plist
If necessary, you can also change the default Subscription ID and public key to values assigned to you, and connect to the UID2 Production environment. For details, see Optional: Specifying the API Base URL to Reduce Latency.
Complete the UID2 Account Setup
To set up your account, follow the steps described in Account Setup. As part of the account setup process, you'll need to provide a list of app names for all the mobile apps that you'll be integrating with the UID2 mobile SDKs, including any of these values that apply:
- Android Application ID
- iOS Bundle Identifier
- iOS App Store ID
When account setup is complete, you'll receive a client keypair consisting of two values that identify you to the UID2 servers: Subscription ID and public key. These values are unique to you, and you'll use them when you configure the UID2 mobile SDK. For details, see Subscription ID and Public Key.
Add the UID2 Mobile SDK to Your Mobile App
To add the mobile SDK to your app, follow the applicable documentation:
At this point, you are ready to start generating UID2 tokens using the SDK.
Using the UID2 Integration Environment
By default, the SDK is configured to work with the UID2 production environment: https://prod.uidapi.com
. If you want to use the integration environment instead, provide the following URL in your call to initialize UID2Manager
:
- Android
- iOS
UID2Manager.init(
context = this,
serverUrl = "https://operator-integ.uidapi.com"
)
// Must be set before UID2Manager.shared is accessed
UID2Settings.shared.environment = .custom(
url: URL(string: "https://operator-integ.uidapi.com")!
)
Bear in mind the following differences between environments:
- Tokens from the UID2 integration environment are not valid for passing to the bidstream.
- You'll have a different set of Subscription ID and public key values for each environment (integration and production). Be sure to use the correct values for each environment.
Optional: Specifying the API Base URL to Reduce Latency
By default, this SDK makes calls to a UID2 production environment server in the USA.
For information about how to choose the best URL for your use case, and a full list of valid base URLs, see Environments.
To specify a UID2 server that is not the default, you can make config changes, as shown in the following examples:
- Android
- iOS
UID2Manager.init(
context = this,
serverUrl = "https://global.prod.uidapi.com"
)
// Must be set before UID2Manager.shared is accessed
UID2Settings.shared.environment = .custom(
url: URL(string: "https://global.prod.uidapi.com")!
)
// or use a named environment
UID2Settings.shared.environment = .sydney
Configure the UID2 Mobile SDK
UID2 provides the publisher with the following values, which are needed for generating the UID2 token on the client side:
- Subscription ID
- Public key
You'll have one set of these values for your Integration environment, and a separate set for your production environment.
To configure the SDK, you must pass in the Subscription ID and public key that you received during account setup, as well as the user’s hashed or unhashed directly identifying information (DII) (email address or phone number), into the following method call:
- Android
- iOS
UID2Manager.getInstance().generateIdentity(
identityRequest: IdentityRequest,
subscriptionId: String,
publicKey: String,
onResult: (GenerateIdentityResult) -> Unit
)
UID2Manager.shared.generateIdentity(
_ identity: IdentityType,
subscriptionID: String,
serverPublicKey: String,
appName: String? = nil
)
Once it's configured, the UID2 mobile SDK does the following:
- Generates a UID2 identity, including token, for the user.
- Stores the token locally on the user’s device.
- Automatically refreshes the token as required while your app is open.
You can pass the user’s DII to the UID2 mobile SDK either hashed or unhashed. If you pass the DII unhashed, the SDK hashes it for you. If you want to pass the DII to the SDK already hashed, you must normalize it before hashing. For details, see Normalization and Encoding.
Format Examples for DII
The SDK encrypts the hashed DII before sending it to the UID2 service.
You can invoke the generateIdentity
method using any of the four accepted formats for DII, for any specific user. The DII format might vary per user, but you can only send one value per user.
The following examples demonstrate the different ways that you can configure the UID2 mobile SDK and list the requirements for the DII passed into the SDK:
- Email, Unhashed
- Email, Normalized and Hashed
- Phone Number, Unhashed
- Phone Number, Normalized and Hashed
If the generateIdentity
method is called multiple times, the UID2 mobile SDK uses the most recent configuration values.
- Email, Unhashed
- Email, Normalized and Hashed
- Phone Number, Unhashed
- Phone Number, Normalized and Hashed
The following example configures the UID2 mobile SDK with an email address.
- Android
- iOS
UID2Manager.getInstance().generateIdentity(
IdentityRequest.Email("test@example.com"),
subscriptionId,
publicKey,
) { result ->
when (result) {
is Error -> ...
is Success -> ...
}
}
struct InvalidEmailError: Error, LocalizedError {
var errorDescription: String = "Invalid email address"
}
Task<Void, Never> {
do {
guard let normalizedEmail = IdentityType.NormalizedEmail(string: "test@example.com") else {
throw InvalidEmailError() // email is invalid and cannot be normalized, handle error
}
try await UID2Manager.shared.generateIdentity(
.email(normalizedEmail),
subscriptionID: subscriptionID,
serverPublicKey: serverPublicKeyString
)
} catch {
// read `error` object for troubleshooting or enable logging to view it in logs
}
}
In this scenario:
- No normalization or hashing is required by the publisher.
- The UID2 mobile SDK normalizes and hashes the email address before sending the encrypted hash to the UID2 service.
The following example configures the UID2 SDK with a hashed email address.
- Android
- iOS
UID2Manager.getInstance().generateIdentity(
IdentityRequest.EmailHash(
"EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4="
),
subscriptionId,
publicKey,
) { result ->
when (result) {
is Error -> ...
is Success -> ...
}
}
Task<Void, Never> {
do {
try await UID2Manager.shared.generateIdentity(
.emailHash("EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4="),
subscriptionID: subscriptionID,
serverPublicKey: serverPublicKeyString
)
} catch {
// read `error` object for troubleshooting or enable logging to view it in logs
}
}
In this scenario:
- The publisher is responsible for normalizing and hashing the email address. For details, see Email Address Normalization.
- The UID2 mobile SDK encrypts the hashed DII before sending it to the UID2 service.
The following example configures the UID2 mobile SDK with a phone number.
- Android
- iOS
UID2Manager.getInstance().generateIdentity(
IdentityRequest.Phone("+12345678901"),
subscriptionId,
publicKey,
) { result ->
when (result) {
is Error -> ...
is Success -> ...
}
}
struct InvalidPhoneError: Error, LocalizedError {
var errorDescription: String = "Invalid phone number"
}
Task<Void, Never> {
do {
guard let normalizedPhone = IdentityType.NormalizedPhone(normalized: "+12345678901") else {
throw InvalidPhoneError() // Phone number is not normalized according to ITU E.164.
}
try await UID2Manager.shared.generateIdentity(
.phone(normalizedPhone),
subscriptionID: subscriptionID,
serverPublicKey: serverPublicKeyString
)
} catch {
// read `error` object for troubleshooting or enable logging to view it in logs
}
}
In this scenario:
- The publisher is responsible for normalizing the phone number. For details, see Phone Number Normalization.
- The UID2 mobile SDK hashes the phone number before sending the encrypted hash to the UID2 service.
The following example configures the UID2 mobile SDK with a hashed and Base64-encoded phone number.
- Android
- iOS
UID2Manager.getInstance().generateIdentity(
IdentityRequest.PhoneHash(
"EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4="
),
subscriptionId,
publicKey,
) { result ->
when (result) {
is Error -> ...
is Success -> ...
}
}
Task<Void, Never> {
do {
try await UID2Manager.shared.generateIdentity(
.phoneHash("EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4="),
subscriptionID: subscriptionID,
serverPublicKey: serverPublicKeyString
)
} catch {
// read `error` object for troubleshooting or enable logging to view it in logs
}
}
In this scenario:
- The publisher is responsible for normalizing and hashing the phone number. For details, see Phone Number Hash Encoding.
- The UID2 mobile SDK encrypts the hashed DII before sending it to the UID2 service.
Token Storage and Refresh
After a call to the applicable method listed in Format Examples for DII is successful, an identity is generated and stored in local file storage. The UID2 mobile SDK refreshes the UID2 token periodically.
The format of the file stored in the local file storage, or the filename itself, could change without notice. We recommend that you do not read or update the file directly.
Pass Generated Token for Bidstream Use
In your mobile app, if the call to generateIdentity
was successful, it returned an identity. The next step is to call the getAdvertisingToken()
method, as follows:
- Android
- iOS
UID2Manager.getInstance().getAdvertisingToken()
UID2Manager.shared.getAdvertisingToken()
If successful, this method call returns the token—a non-null string object such as the following:
A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g
You can use this token to pass downstream for sending in the RTB bidstream.
If the getAdvertisingToken()
method call returns null
, there was no identity or valid token generated.
Some possible reasons for this, and some things you could do to troubleshoot, are as follows:
- The identity is invalid. In this scenario there are a couple of options:
-
Check to see whether there are any errors from the previous
generateIdentity
call. -
Check the status of the identity, using one of the following:
- Android Java:
UID2Manager.getInstance().getCurrentIdentityStatus()
- Android Kotlin:
UID2Manager.getInstance().currentIdentityStatus()
- iOS:
UID2Manager.shared.identityStatus
It's possible that the DII has been opted out of UID2: for details, see When to Pass DII into the SDK.
- Android Java:
-
- You could enable logging to get more information: see Enable Logging.
- The advertising token inside the UID2 identity has expired, and the refresh token has also expired, so the SDK cannot refresh the token.
If there is no identity, you'll need to call the generateIdentity
method again: see Configure the UID2 Mobile SDK.
For more information, see When to Pass DII into the SDK (next section).
When to Pass DII into the SDK
The first time a new user opens the app, no UID2 identity exists. You'll need to call the generateIdentity
method, with the DII, to start the token generation:
- Android
- iOS
UID2Manager.getInstance().generateIdentity(
identityRequest: IdentityRequest,
subscriptionId: String,
publicKey: String,
onResult: (GenerateIdentityResult) -> Unit
)
UID2Manager.shared.generateIdentity(
_ identity: IdentityType,
subscriptionID: String,
serverPublicKey: String,
appName: String? = nil
)
When this method call completes successfully, the advertising token (UID2 token) is available for you to send to the bidstream.
If the UID2 identity stored in local file storage has expired and cannot be refreshed, you must call the generateIdentity
method again to generate a new identity and get the resulting UID2 token. The only exception is when the response to the following Android method/iOS object indicates that the DII was opted out of UID2:
- Android
- iOS
Android Java:
UID2Manager.getInstance().getCurrentIdentityStatus()
Android Kotlin:
UID2Manager.getInstance().currentIdentityStatus()
UID2Manager.shared.identityStatus
A response status of OPT_OUT
for Android, or optOut
for iOS, indicates that the DII has been opted out of UID2 and no identity/token should be generated for it. You might want to avoid making repeated generateIdentity
calls: if the DII has a status of opted out, the UID2 token is not generated.
The best way to determine if DII is required by the UID2 mobile SDKs is to always call the getAdvertisingToken()
method when the app starts up or resumes:
- Android
- iOS
UID2Manager.getInstance().getAdvertisingToken()
UID2Manager.shared.getAdvertisingToken()
If getAdvertisingToken()
returns null, and the identity status is not OPT_OUT
/optOut
, you'll need to generate a new token. To do this, pass the DII into the generateIdentity
method again. For details, see Configure the UID2 mobile SDK.
Enable Logging
The UID2 SDK can generate logs, which could help in debugging any issues during UID2 integration work. To enable logging, do the following:
- Android
- iOS
// During UID2Manager initialization:
UID2Manager.init(
context = this,
isLoggingEnabled = true
)
// On iOS, you must set UID2Settings before you first access UID2Manager.shared.
// Changes made to settings after first access are not read.
UID2Settings.shared.isLoggingEnabled = true
Optional: UID2 GMA/IMA Plugin for GAM Secure Signals integration
If you intend to generate UID2 tokens to send to the Google GMA SDK or the Google IMA SDK, assuming you have followed the instructions in this guide, you must also add the UID2 GMA/IMA plugins into your mobile app. For instructions, refer to the applicable plug-in guide:
- UID2 GMA Plugin for Android Integration Guide
- UID2 GMA Plugin for iOS Integration Guide
- UID2 IMA Plugin for Android Integration Guide
- UID2 IMA Plugin for iOS Integration Guide
You do not need to explicitly make the getAdvertisingToken()
method call to retrieve the advertising tokens and pass them into Google GMA/IMA SDK manually. The UID2 GMA/IMA plugins manage this for you.
All you need to do is make sure that getAdvertisingToken()
returns a non-null string object:
- Android
- iOS
UID2Manager.getInstance().getAdvertisingToken()
UID2Manager.shared.getAdvertisingToken()
If the token exists, the Google GMA/IMA plug-ins can retrieve it automatically via the UID2 GMA/IMA plugins.
Optional: UID2 Prebid Mobile SDK Integration
The UID2 Prebid Mobile SDK integration requires version 1.4.0 of the UID2 SDK for Android, or version 1.5.0 of the UID2 SDK for iOS.
This section is for participants who want to integrate with UID2 and use the Prebid Mobile SDK for header bidding in Android and iOS applications.
The UID2 Prebid integration monitors the state of the UID2Identity
. Whenever the state changes, the Prebid integration automatically updates Prebid’s external user IDs. This includes when an identity is refreshed, resulting in a new advertising token.
Prebid then sends the UID2 tokens into the RTB bidstream, along with other external user IDs that you might set.
This integration requires a Prebid Server setup.
To configure your UID2 Prebid for Mobile integration, follow the steps below.
-
Set up Prebid's Mobile SDK, following the steps in Prebid SDK Integration for Android or Prebid SDK Integration for iOS.
-
Add the UID2 Mobile SDK to your app, following the steps in Add the UID2 Mobile SDK to Your Mobile App.
-
The UID2 Prebid integration is distributed as a separate module, so you must add it as a dependency in your project. Follow the installation instructions that apply to your integration, out of the following options:
- Gradle (Android)
- Maven (Android)
- CocoaPods (iOS)
- SPM (iOS)
Include the following in your Gradle configuration:
implementation("com.uid2:uid2-android-sdk-prebid:1.4.0")
To install with Maven, add the SDK as a dependency in the
pom.xml
file:<dependency>
<groupId>com.uid2</groupId>
<artifactId>uid2-android-sdk-prebid</artifactId>
<version>1.4.0</version>
</dependency>Add the following entry in your
Podfile
:pod 'UID2Prebid', '~> 1.5'
warningIntegration via Swift Package Manager is not supported until it is supported by the Prebid Mobile SDK itself. For details, see Prebid's Mobile SDK documentation.
-
After adding the dependency, you'll need to configure the integration. First initialize the
UID2Manager
, and then Prebid, as shown in the following examples.- Android Kotlin
- Android Java
- iOS Swift
UID2Manager.init(context = this)
PrebidMobile.initializeSdk(this) { Log.i(TAG, "Prebid: $it") }
prebid = UID2Prebid().apply {
initialize()
}UID2Manager.init(this);
PrebidMobile.initializeSdk(this, status -> Log.i(TAG, "Prebid: " + status));
prebid = new UID2Prebid();
prebid.initialize();Initialize an instance of UID2Prebid and hold a strong reference to it. UID2Prebid only observes the UID2Manager while the instance is retained.
self.prebid = UID2Prebid()
-
Configure a callback that's passed in during initialization.
The UID2 Prebid integration periodically updates Prebid by setting the relevant external IDs when a new identity is generated or an existing token is refreshed.
This process is destructive, which means that if your application uses external IDs from another source, you'll need to provide those to the UID2 Prebid integration so that all external IDs are retained while the UID2 token is updated.
This is done via the callback, which must be passed in during initialization, as shown in the following examples.
- Android Kotlin
- Android Java
- iOS Swift
prebid = UID2Prebid(
externalUserIdFactory = ::getExternalIds,
).apply {
initialize()
}prebid = new UID2Prebid(UID2Manager.getInstance(), () -> getExternalIds());
prebid.initialize();self.prebid = UID2Prebid(thirdPartyUserIDs: {
// return externalUserIDs
})