Skip to main content

UID2 SDK for iOS Reference Guide

You can use the UID2 SDK for iOS for the following:

  • Generating or establishing client identity using UID2.
  • Retrieving advertising tokens for bidstream use.
  • Automatically refreshing UID2 tokens.

The following iOS-related plugins, and associated documentation, are also available:

PurposeProduct/Documentation
To use the Google Mobile Ads (GMA) SDK to send UID2 tokens as secure signals in ad requests from iOS/tvOS appsUID2 GMA Plugin for iOS Integration Guide
To use the Google Interactive Media Ads SDK for iOS to send UID2 tokens as secure signals in ad requests from iOS/tvOS appsUID2 IMA Plugin for iOS Integration Guide

tvOS Support​

Although this page refers to UID2 SDK for iOS, this SDK also supports tvOS. For the required tvOS version, see Minimum Requirements.

Functionality​

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

Encrypt Raw UID2 to UID2 TokenDecrypt UID2 TokenGenerate UID2 Token from DIIRefresh UID2 Token
Not supportedNot supportedSupportedSupported

The UID2 SDK for iOS is designed to generate and/or manage UID2 identity on behalf of iOS 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.

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.

SDK Version​

This documentation is for the UID2 SDK for iOS version 1.2.0 and later.

For current and past release notes information, see https://github.com/IABTechLab/uid2-ios-sdk/releases.

GitHub Open-Source Repository​

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

Minimum Requirements​

Minimum requirements for this SDK are as follows:

  • Xcode version: 15.0+
  • iOS minimum target version: 13.0+
  • tvOS minimum target version: 13.0+
  • Swift version: 5.0+

Installation​

Install the iOS SDK via Swift Package Manager (SPM) or CocoaPods. There are three installation options:

Installing with Package.swift​

Add the following dependency to Package.swift:

dependencies: [
  .package(url: "https://github.com/IABTechLab/uid2-ios-sdk.git", from: "1.2.0"),
]

Installing with Xcode​

In the XCode user interface, under Package Dependencies, add the following entry for your apps:

NameLocationDependency Rule
uid2-ios-sdkgit@github.com:IABTechLab/uid2-ios-sdk.gitUp to next major version: 1.2.0 < 2.0.0

Installing with CocoaPods​

Add the following entry in your Podfile:

pod 'UID2', '~> 1.2'

Usage Guidelines​

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

For iOS, the UID2Manager is initialized automatically the first time it is accessed. You can configure it to support automatic or manual refresh capabilities.

There are two ways to establish an initial UID2 Identity:

  1. Generate the UID2 identity using DII—email (hashed or unhashed) or phone number (hashed or unhashed). For integration instructions, see Client-Side Integration Guide for Mobile.

  2. Create a UID2 identity from your server's back end and then pass it to the UID2 SDK. For integration instructions, see Client-Server Integration Guide for Mobile.

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.

Code Samples​

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

Generate an initial UID2 Identity (for instructions, see Client-Side Integration Guide for Mobile):

UID2Manager.shared.generateIdentity(
    _ identity: IdentityType,
    subscriptionID: String,
    serverPublicKey: String,
    appName: String? = nil
)

Set the Initial UID2 Identity (for instructions, see Client-Server Integration Guide for Mobile):

UID2Manager.shared.setIdentity(_ identity: UID2Identity)

Get the UID2 token (advertising token) to pass to the Advertising SDK (for ad request or bidstream use):

UID2Manager.shared.getAdvertisingToken()

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:

generateIdentity()​

Generate a UID2 Identity using Directly identifying information (DII). For details, see Configure the UID2 mobile SDK in the Client-Side Integration Guide for Mobile.

setIdentity()​

Sets a UID2 Identity, created server-side, to be managed by the SDK. For details, see Configure the UID2 Mobile SDK in the Client-Server Integration Guide for Mobile.

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​

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.