UID2 SDK for Android Reference Guide

You can use the UID2 SDK for Android to facilitate the process of establishing client identity using UID2 and retrieving advertising tokens on Android devices.

The following Android-related plugins, and associated documentation, are also available.

Purpose	Product/Documentation
To use the Google Mobile Ads (GMA) SDK to send UID2 tokens as secure signals in ad requests from Android apps	UID2 GMA Plugin for Android Integration Guide
To use the Google Interactive Media Ads (IMA) SDK for Android to send UID2 tokens as secure signals in ad requests from Android apps	UID2 IMA Plugin for Android Integration Guide

Functionality

This SDK simplifies integration with UID2 for any publishers who want to support UID2 for apps running on Android devices. The following table shows the functions it supports.

Encrypt Raw UID2 to UID2 Token	Decrypt UID2 Token	Generate UID2 Token from DII	Refresh UID2 Token
Not supported	Not supported	Not supported	Supported

API Permissions

To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the Account Setup page.

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 example, publishers get a specific API permission to generate and refresh tokens, but the SDK might support other activities, such as sharing, which require a different API permission.

For details, see API Permissions.

SDK Version

This documentation is for the UID2 Android SDK version 0.5.0 and later.

For information about specific release versions, see https://github.com/IABTechLab/uid2-android-sdk/releases.

Features

The UID2 Android SDK is designed to manage UID2 identity on behalf of Android apps. It enables UID2 identity to be persisted across app lifecycles by securely storing the identity on a device via platform-native encryption tools.

By default, the SDK automatically refreshes UID2 identity based on expiration dates. However, you can disable this to allow implementing apps to manage the UID2 identity lifecycle manually.

GitHub Repository/Binary

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

• https://github.com/IABTechLab/uid2-android-sdk

The binary is published on Sonatype:

• https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk

Minimum Requirements

Minimum requirements for this SDK are as follows:

• Android Studio version: 2022.1.1 Patch 2+
• Minimum target Android version: 4.4+ / API 19+ (SDK) 5.0+ / API 21+ (Dev-App)

Installation

There are two options for installing the Android UID2 SDK:

• Gradle

• Maven

Installing with Gradle

To install with Gradle, add the SDK as a dependency in the build.gradle file:

implementation 'com.uid2:uid2-android-sdk:0.5.0'

Installing with Maven

To install with Maven, add the SDK as a dependency in the pom.xml file:

<dependency> 
  <groupId>com.uid2</groupId> 
  <artifactId>uid2-android-sdk</artifactId> 
  <version>0.5.0</version> 
</dependency> 

Usage Guidelines

The initial UID2 Identity must be generated by the implementing application and then passed into the UID2 SDK. Because of security requirements, the UID2 Mobile SDKs cannot create new UID2 identities.

The UID2 Mobile SDKs can perform refreshes of UID2 identities, after an Identity is established. This is because the refresh functionality relies on the refresh tokens that are part of the UID2 Identity.

The UID2Manager singleton is the primary developer API for the UID2 Android and iOS SDKs. It is responsible for storing, refreshing, and retrieving UID2 Identity.

For Android, you must initialize the UID2Manager manually before you can use it. See Android Initialization.

UID2Manager API

This section includes the functions and variables that are part of the UID2Manager API.

Functions

The following functions are available as part of the UID2Manager API:

• setIdentity()
• resetIdentity()
• refreshIdentity()
• getAdvertisingToken()
• setAutomaticRefreshEnabled()

setIdentity()

Sets the UID2 Identity to be managed by the SDK.

resetIdentity()

Resets or removes the UID2 Identity currently being managed by the SDK.

refreshIdentity()

Manually refreshes the UID2 Identity being managed by the SDK.

getAdvertisingToken()

If the current UID2 Identity is valid, this function returns the UID2 token (advertising token).

setAutomaticRefreshEnabled()

Toggle for automatic refresh functionality.

Variables

The following variables are available as part of the UID2Manager API:

• identity
• identityStatus

identity

The Identity variable stores and returns the current UID2Identity data object being managed by the SDK.

identityStatus

The identityStatus variable stores and returns the status of the current UID2 Identity being managed by the SDK.

Android Initialization

The Android implementation expects the singleton to be initialized before use. This does two things:

• It allows for easier access later.

• It allows the consuming application to potentially provide its own network instance, responsible for making requests.

The initialization can be done during the creation of the APPLICATION instance, as shown in the following example:

class MyApplication : Application() {
  override fun onCreate() {
    super.onCreate()
   // Initialize the UID2Manager class. Use DefaultNetworkSession rather than providing our own
   // custom implementation. This can be done to allow wrapping something like OkHttp.
   UID2Manager.init(this.applicationContext)

Code Samples

The following code samples provide examples of performing specific activities relating to managing UID2 with the UID2 Android SDK.

Set the Initial UID2 Identity:

UID2Manager.getInstance().setIdentity(identity: UID2Identity)

Get the UID2 token (advertising token) to pass to the Advertising SDK:

UID2Manager.getInstance().getAdvertisingToken()