UID2 Client-Server Integration Guide for Mobile
This guide is for mobile app publishers who want to integrate with UID2 by generating UID2 tokens server-side via a Public Operator or Private Operator and then passing the tokens and user identities into their mobile apps, which will in turn pass the tokens for bidstream use.
This is called client-server integration because some integration steps are client-side and some are server-side.
If you want to integrate with UID2 via client-side only changes (that is, all integration changes required are within the mobile apps), refer to the UID2 Client-Side Integration Guide for Mobile instead.
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:
- Takes in 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.
You'll need to complete the following steps:
- Complete the UID2 account setup.
- Implement server-side token generation.
- Add the UID2 mobile SDK to your mobile app.
- Configure the UID2 mobile SDK.
- 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.
Complete the UID2 Account Setup
To set up your account, follow the steps described in Account Setup.
When account setup is complete, you'll receive your unique API key and client secret. These values are unique to you, and it's important to keep them secure. For details, see API Key and Client Secret.
Client-Server Mobile Integration Data Flow Overview
The following diagram shows the data flow that the publisher must implement for UID2 client-server mobile integration.
This example uses the SDK for Android in the client-side mobile app and the SDK for Java on the server side.
Implement Server-Side Token Generation
For a client-server UID2 integration for mobile, the first step is to be able to generate the UID2 token on your server. Then, you can pass the token into your mobile apps for sending to the RTB bidstream.
For details, including instructions and examples, see Server-Side Token Generation.
You will need to pass the Identity
response into the mobile app: see Configure the UID2 Mobile SDK.
For security reasons, the API key and secret used in token generation must be called server-side. Do not store these values inside a mobile app.
Server-Side Token Refresh
Token refresh is automatically enabled inside the UID2 mobile SDKs; you don't need to manage it explicitly on the server side.
You might decide to do server-side token refresh if you want to keep your changes in the mobile apps as simple as possible.
If you want to manage token refresh on the server side and not the client/mobile side, you can do so using one of the following:
-
Call the POST /token/refresh endpoint.
-
Use one of the Publisher Client classes, in one of the UID2 server-side SDKs. These classes simplify the request into a single method call.
For instructions, see SDK for Java, Publisher Server-Side Integration section or SDK for Python, Publisher Server-Side Integration section.
Then, pass the newly refreshed Identity
value to the mobile app by following the rest of this guide.
Add the UID2 Mobile SDK to Your Mobile App
For installation instructions, refer to one of the following:
At this point, you are ready to use the UID2 Identity generated server-side in the mobile 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 UID2 integration environment instead, provide the following URL in your call to UID2Manager initialization:
- 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 API key and client secret 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 change it in the init
call:
- Android
- iOS
UID2Manager.init(
context = this,
serverUrl = "https://global.prod.uidapi.com"
)
UID2Settings.shared.environment = .singapore
// or
UID2Settings.shared.environment = .custom(
url: URL(string: "https://global.prod.uidapi.com")!
)
Configure the UID2 Mobile SDK
After you've instantiated UID2Manager
correctly in your mobile app, you'll need to pass a UID2 identity generated server-side (see Implement server-side token generation), and then pass it into the mobile app using the setIdentity
method, as shown in the following:
- Android
- iOS
UID2Manager.getInstance().setIdentity()
UID2Manager.shared.setIdentity()
Token Storage
After you call the setIdentity
method, the UID2 identity is persisted in local file storage.
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
To retrieve the token, in your mobile app, call the following:
- Android
- iOS
UID2Manager.getInstance().getAdvertisingToken()
UID2Manager.shared.getAdvertisingToken()
If a successful identity was added into the UID2Manager, this method returns a string such as the following:
A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g
You can use this identity 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
setIdentity()
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
- Android Java:
- Check to see whether there are any errors from the previous
- 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, follow the instructions in Implement Server-Side Token Generation again, generate a new identity, and pass the result into your mobile app's UID2Manager again.
When to Pass a new UID2 Identity/Token into the SDK
The best way to determine whether a new UID2 identity is required by the UID2 SDK again is to call the getAdvertisingToken()
method in all cases:
- Android
- iOS
UID2Manager.getInstance().getAdvertisingToken()
UID2Manager.shared.getAdvertisingToken()
On startup/resumption of the app, if getAdvertisingToken()
returns null
, it is time to generate new identity on the server by following the instructions in Implement Server-Side Token Generation. Then, pass the result into the mobile app’s UID2Manager again: 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
Enable Automatic Token Refresh in Mobile App/Client Side
By default, after a valid UID2 identity has been passed into the UID2Manager, it performs automatic token refresh. If for any reason token refresh was disabled, you can enable it with the following method call:
- Android
- iOS
Android Java:
UID2Manager.getInstance().setAutomaticRefreshEnabled(false)
Android Kotlin:
UID2Manager.getInstance().automaticRefreshEnabled = false
UID2Manager.shared.automaticRefreshEnabled = false
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 is for Android only, and requires version 1.4.0 of the SDK for Android.
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
})