メインコンテンツまでスキップ

UID2 Client-Side Integration Guide for Mobile

このガイドは、モバイルアプリのみの変更で UID2 とインテグレーションしたいモバイルアプリパブリッシャー向けです。

以下の手順は、Private Operator を使用したいパブリッシャーや、Server-Side でトークンを生成したいパブリッシャーには適用されません。これらのパブリッシャーは、Client-Server Integration Guide for Mobile に従う必要があります。

このページでは、インテグレーション手順の概要と、追加のドキュメントへのリンクを提供します。

UID2 は、Android および iOS 向けのモバイル SDK を提供しています。各 SDK には以下の機能があります:

  • UID2 identity (UID2 Token と関連する値) を生成し、ローカルファイルストレージに保存します。
  • UID2 Token を自動的にリフレッシュします。
注記

このガイドの、UID2 mobile SDKs は、SDK for Android と SDK for iOS の両方を含むグループ用語です。

モバイルパブリッシャーインテグレーションに関する FAQs については、FAQs for Mobile Integrations を参照してください。

UID2 を Client-Side でインテグレーションするには、以下の手順を完了する必要があります:

  1. Complete the UID2 account setup.

  2. Add the UID2 mobile SDK to your mobile app.

  3. Configure the UID2 mobile SDK.

  4. Check that the token was successfully generated and then pass it for bidstream use.

  5. Optionally, integrate the UID2 GMA/IMA Plugin for GAM Secure Signals integration.

Mobile SDK Version​

このガイドは、次のいずれかの UID2 mobile SDK のバージョン 1.2.0 以上を使用する方法について説明します:

  • SDK for Android
  • SDK for iOS

正しい SDK/バージョンをモバイルアプリにインストールする手順については、Add the UID2 Mobile SDK to Your Mobile App を参照してください。

Client-Side Integration Example​

UID2 mobile SDK の設定方法と、モバイル用の Client-Side インテグレーションを使用したトークンの生成方法の例については、UID2 開発アプリを試してください。

Android または iOS 向けの適用可能な手順に従ってください:

  1. SDK for Android source code repository on GitHub の main ブランチをチェックアウトします。
  2. Android Studio (Jellyfish/v2023.3.1 または SDK for Android リリース時に必要な Android Gradle Plugin バージョンをサポートする将来のバージョン) で、チェックアウトしたディレクトリを開きます。
  3. dev-app アプリを実行します。
  4. アプリを起動したら、Client Side チェックボックスがチェックされていることを確認します。
  5. メールアドレスまたは電話番号を入力し、右側の矢印をクリックします。

アプリの背後で、開発アプリは次の UID2 SDK API コールを行います。このコールは、メール/電話番号入力に対して UID2 Service に identity (UID2 Token と関連する値) を生成するリクエストを送信します:

UID2Manager.getInstance().generateIdentity(
    identityRequest: IdentityRequest,
    subscriptionId: String,
    publicKey: String,
    onResult: (GenerateIdentityResult) -> Unit
)

API コールが成功すると、アプリは生成された identity を表示し、UID2Manager クラス内に永続化します。

identity には、getAdvertisingToken() メソッドコールで取得できる UID2 Advertising Token が含まれます:

UID2Manager.getInstance().getAdvertisingToken()

このメソッドコールは、広告リクエストを行うために必要な値を返します: 詳細は Pass Generated Token for Bidstream Use を参照してください。

Testing With Your Own Configuration​

デフォルトでは、開発アプリは Subscription ID と public key のデフォルト値を使用します。これらの値は、次のオブジェクトに保存されています:

com.uid2.dev.ui.MainScreenViewModel.Companion

デフォルトでは、開発アプリは UID2 インテグレーション環境に接続されています。これは、次の Android メソッドコール/iOS ファイルで指定されています:

com.uid2.UID2Manager.Companion#init

必要に応じて、デフォルトの Subscription ID と public key を割り当てられた値に変更し、UID2 本番環境に接続することもできます。詳細は Optional: Specifying the API Base URL to Reduce Latency を参照してください。

Complete the UID2 Account Setup​

アカウントをセットアップするには、Account Setup に記載されている手順に従ってください。アカウントセットアッププロセスの一環として、UID2 mobile SDK とインテグレーションするすべてのモバイルアプリの app names のリストを提供する必要があります。これには、以下の値が該当します:

  • Android Application ID
  • iOS Bundle Identifier
  • iOS App Store ID

アカウントのセットアップが完了すると、UID2 サーバーがユーザーを識別するために使用する 2 つの値であるクライアントキーペアが発行されます: Subscription ID と Public key。これらの値はあなたに固有で、UID2 モジュールの設定に使用します。詳細は Subscription ID and Public Key を参照してください。

Add the UID2 Mobile SDK to Your Mobile App​

Mobile SDK をアプリに追加するには、適用可能な以下のドキュメントに従ってください:

SDK をアプリに追加したら、SDK を使用して UID2 Token を生成する準備が整います。

Using the UID2 Integration Environment​

デフォルトでは、SDK は UID2 本番環境で動作するように構成されています: https://prod.uidapi.com。代わりにインテグレーション環境を使用する場合は、UID2Manager の初期化に次の URL を指定してください:

UID2Manager.init(
  context = this,
  UID2Manager.Environment.Custom("https://operator-integ.uidapi.com")
)
注記

次のような環境間の違いに注意してください:

  • UID2 インテグレーション環境のトークンは、ビッドストリームに渡しても有効ではありません。
  • 各環境（インテグレーションおよび本番）には異なる API Key とクライアントシークレット値があります。各環境で正しい値を使用してください。

Optional: Specifying the API Base URL to Reduce Latency​

デフォルトでは、この SDK は米国の UID2 本番環境サーバーにリクエストを送信します。

ユースケースに最適な URL を選択する方法と、有効なベース URL の完リストについては、Environments を参照してください。

別の UID2 サーバを指定するには、次の例に示すように構成変更を行います:

UID2Manager.init(
  context = this,
  UID2Manager.Environment.Custom("https://global.prod.uidapi.com")
)
// or use a named environment
UID2Manager.init(
  context = this,
  UID2Manager.Environment.Sydney
)

Configure the UID2 Mobile SDK​

UID2 は、以下の値を提供します。これらは、UID2 Token を Client-Side クライアで生成する際に必要です:

  • Subscription ID
  • Public key

これらの値は、アカウントセットアップ時に受け取ります。インテグレーション環境用の 1 つのセットと、本番環境用の別のセットがあります。

SDK を構成するには、アカウントセットアップ時に受け取った Subscription ID と public key、およびユーザーのハッシュ化またはハッシュ化されていない直接識別情報 (DII) (メールアドレスまたは電話番号) を次のメソッドコールに渡す必要があります:

UID2Manager.getInstance().generateIdentity(
    identityRequest: IdentityRequest,
    subscriptionId: String,
    publicKey: String,
    onResult: (GenerateIdentityResult) -> Unit
)

設定が完了すると、UID2 mobile SDK は以下の操作を行います:

  • ユーザーの UID2 identity (トークンを含む) を生成します。
  • トークンをユーザーのデバイスにローカルに保存します。
  • アプリが開いている間、必要に応じてトークンを自動的にリフレッシュします。
ヒント

ユーザーの DII を UID2 mobile SDK に渡す際、ハッシュ化またはハッシュ化されていない DII を渡すことができます。DII をハッシュ化されていない状態で渡す場合、SDK がハッシュ化します。ハッシュ化された DII を SDK に渡す場合、ハッシュ化する前に正規化する必要があります。詳細は Normalization and Encoding を参照してください。

Format Examples for DII​

SDK は、ハッシュ化された DII を UID2 Service に送信する前に暗号化します。

ユーザーごとに、DII のフォーマットが異なる場合でも、任意のフォーマットで generateIdentity メソッドを呼び出すことができます。DIIのフォーマットはユーザごとに異なる場合がありますが、ユーザーごと送信できる値は 1 つだけです。

以下の例は、UID2 mobile SDK を構成する異なる方法を示し、SDK に渡す DII に必要な要件を示しています:

  • Email, Unhashed
  • Email, Normalized and Hashed
  • Phone Number, Unhashed
  • Phone Number, Normalized and Hashed

generateIdentity メソッドが複数回呼び出される場合、UID2 mobile SDK は最新の構成値を使用します。

以下の例は、UID2 mobile SDK をメールアドレスで構成する方法を示しています。

UID2Manager.getInstance().generateIdentity(
    IdentityRequest.Email("test@example.com"),
    subscriptionId,
    publicKey,
) { result ->
    when (result) {
        is Error -> ...
        is Success -> ...
    }
}

このシナリオでは:

  • パブリッシャーはメールアドレスを正規化またはハッシュ化する必要はありません。
  • UID2 mobile SDK は、暗号化されたハッシュを UID2 Service に送信する前にメールアドレスを正規化およびハッシュ化します。

Token Storage and Refresh​

Format Examples for DII に記載されている適用可能なメソッドを呼び出した後、identity が生成され、ローカルファイルストレージに保存されます。UID2 mobile SDK は定期的に UID2 Token をリフレッシュします。

警告

ローカルファイルストレージに保存されているファイルの形式、またはファイル名自体が予告なく変更される可能性があります。ファイルを直接読み取ったり更新したりしないようにしてください。

Pass Generated Token for Bidstream Use​

モバイルアプリで generateIdentity メソッドが成功すると、identity が返されます。次のステップは、次のように getAdvertisingToken() メソッドを呼び出すことです:

UID2Manager.getInstance().getAdvertisingToken()

成功すると、このメソッドコールはトークンを返します。—以下のような、非 null の文字列オブジェクトが返されます:

A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g

このトークンを使用して、ビッドストリームに送信するためにダウンストリームに渡すことができます。

getAdvertisingToken() メソッドコールが null を返す場合、identity または有効なトークンが生成されていません。

その原因として考えられることと、トラブルシューティングに役立ついくつかの方法は次のとおりです:

  • Identity が無効です。この場合、いくつかのオプションがあります:

    • 前の generateIdentity メソッドコールからエラーがあるかどうかを確認します。

    • 次のいずれかを使用して identity のステータスを確認します:

      • Android Java: UID2Manager.getInstance().getCurrentIdentityStatus()
      • Android Kotlin: UID2Manager.getInstance().currentIdentityStatus()
      • iOS: UID2Manager.shared.identityStatus

      UID2 から DII がオプトアウトされている可能性があります: 詳細については When to Pass DII into the SDK を参照してください。

  • ロギングを有効にして詳細情報を取得できます: Enable Logging を参照してください。
  • UID2 identity 内の Advertising Token の有効期限が切れていて、Refresh Token も有効期限が切れているため、SDK がトークンをリフレッシュできません。

Identity が無い場合は、generateIdentity メソッドを再度呼び出す必要があります: 詳細については Configure the UID2 Mobile SDK を参照してください。

詳しくは、When to Pass DII into the SDK(次項) を参照してください。

When to Pass DII into the SDK​

新しいユーザーがアプリを初めて開いた場合、UID2 identity は存在しません。トークン生成を開始するには、generateIdentity メソッドを DII と共に呼び出す必要があります:

UID2Manager.getInstance().generateIdentity(
    identityRequest: IdentityRequest,
    subscriptionId: String,
    publicKey: String,
    onResult: (GenerateIdentityResult) -> Unit
)

メソッドコールが成功すると、Advertising Token (UID2 Token) が生成され、ビッドストリームに送信するために使用できます。

ローカルファイルストレージに保存されている UID2 identity が期限切れで、リフレッシュできない場合は、新しい identity を生成するために generateIdentity メソッドを再度呼び出す必要があります。ただし、次の Android メソッド/iOS オブジェクトの応答が示すように、DII が UID2 からオプトアウトされている場合は、UID2 Token は生成されません:

Android Java:

UID2Manager.getInstance().getCurrentIdentityStatus()

Android Kotlin:

UID2Manager.getInstance().currentIdentityStatus()

レスポンスステータスが OPT_OUT (Android) または optOut (iOS) の場合、DII は UID2 からオプトアウトされており、UID2 Token は生成されません。

UID2 mobile SDK で DII が必要かどうかを判断する最良の方法は、アプリの起動時または再開時に常に getAdvertisingToken() メソッドを呼び出すことです:

UID2Manager.getInstance().getAdvertisingToken()

getAdvertisingToken() が null を返し、identity ステータスが OPT_OUT/optOut でない場合、新しいトークンを生成する必要があります。これを行うには、generateIdentity メソッドに DII を再度渡します。詳細は 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:

// During UID2Manager initialization:
UID2Manager.init(
  context = this,
  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:

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:

UID2Manager.getInstance().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​

important

UID2 Prebid Mobile SDK インテグレーションは、UID2 SDK for Android version 1.6.0 または UID2 SDK for iOS version 1.7.0 が必要です。

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 these steps:

  1. Set up Prebid's Mobile SDK, following the steps in Prebid SDK Integration for Android or Prebid SDK Integration for iOS.

  2. Add the UID2 Mobile SDK to your app, following the steps in Add the UID2 Mobile SDK to Your Mobile App.

  3. 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:

    Include the following in your Gradle configuration:

    implementation("com.uid2:uid2-android-sdk-prebid:1.6.0")

  4. After adding the dependency, you'll need to configure the integration. First initialize the UID2Manager, and then Prebid, as shown in the following examples.

    UID2Manager.init(context = this)

    PrebidMobile.initializeSdk(this) { Log.i(TAG, "Prebid: $it") }
    prebid = UID2Prebid(UID2Manager.getInstance()).apply {
        initialize()
    }

  5. 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.

    prebid = UID2Prebid(
        manager = UID2Manager.getInstance(),
        externalUserIdFactory = ::getExternalIds,
    ).apply {
        initialize()
    }