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

UID2 Client-Server Integration Guide for Mobile

このガイドは、Public Operator または Private Operator を介して Server-Side で UID2 Token を生成し、そのトークンとユーザー ID をモバイルアプリに渡して UID2 とインテグレーションしたいモバイルアプリパブリッシャー向けです。モバイルアプリは、そのトークンを ビッドストリーム に使用するために渡します。

これは Client-Server インテグレーションと呼ばれます。これは、いくつかのインテグレーションステップがクライアントサイドで行われ、いくつかがサーバーサイドで行われるためです。

Client-Side のみの変更で UID2 とインテグレーションしたい場合 (つまり、すべてのインテグレーション変更がモバイルアプリ内で行われる場合) は、代わりに UID2 Client-Side 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 を参照してください。

以下の手順を完了する必要があります:

  1. Complete the UID2 account setup.
  2. Implement server-side token generation.
  3. Add the UID2 mobile SDK to your mobile app.
  4. Configure the UID2 mobile SDK.
  5. Check that the token was successfully generated and then pass it for bidstream use.
  6. Optionally, integrate the UID2 GMA/IMA Plugin for GAM Secure Signals integration.

Mobile SDK Version​

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

  • SDK for Android (version 1.6.0 or later)
  • SDK for iOS (version 1.7.0 or later)

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

Complete the UID2 Account Setup​

アカウントの設定を完了するには、Account Setup に記載されている手順に従ってください。

アカウントの設定が完了すると、ユニークな API Key とクライアントシークレットが送信されます。これらの値はあなたに固有であり、安全に保管することが重要です。詳細は API Key and Client Secret を参照してください。

Client-Server Mobile Integration Data Flow Overview​

下記の図は、UID2 Client-Server モバイルインテグレーションを実装するためにパブリッシャーが実装する必要があるデータフローを示しています。

この例では、Client-Side のモバイルアプリで SDK for Android を使用し、Server-Side で SDK for Java を使用しています。

Mobile Client-Server Integration Example

Implement Server-Side Token Generation​

モバイル向けの Client-Server UID2 インテグレーションの場合、最初のステップは、サーバーで UID2 Token を生成できるようにすることです。その後、トークンをモバイルアプリに渡して RTB ビッドストリームに送信できます。

手順や例については、Server-Side Token Generation を参照してください。

Identity レスポンスをモバイルアプリに渡す必要があります: Configure the UID2 Mobile SDK を参照してください。

警告

セキュリティ上の理由から、トークン生成に使用される API キーとシークレットはサーバーサイドで呼び出す必要があります。これらの値をモバイルアプリ内に保存しないでください。

Server-Side Token Refresh​

UID2 mobile SDK では Token Refresh が自動的に有効になっています。Server-Side で明示的に管理する必要はありません。

モバイルアプリでの変更をできるだけシンプルにしたい場合は、Server-Side で Token Refresh を行うこともできます。

Token Refresh を Server-Side で管理し、クライアント/モバイルサイドではなく行いたい場合は、次のいずれかを使用してください:

その後、このガイドの残りの部分に従って、新しくリフレッシュされた Identity 値をモバイルアプリに渡します。

Add the UID2 Mobile SDK to Your Mobile App​

インストール方法については、以下のいずれかを参照してください:

この時点で、Server-Side で生成された UID2 Identity をモバイル SDK で使用する準備が整いました。

Using the UID2 Integration Environment​

デフォルトでは、SDK は UID2 本番環境で動作するように構成されています: https://prod.uidapi.com。代わりに UID2 インテグレーション環境を使用する場合は、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 サーバーを指定するには、init 呼び出しで変更してください:

UID2Manager.init(
  context = this,
  UID2Manager.Environment.Signapore
)
// or 
UID2Manager.init(
  context = this,
  UID2Manager.Environment.Custom("https://global.prod.uidapi.com")
)

Configure the UID2 Mobile SDK​

モバイルアプリで UID2Manager を正しくインスタンス化した後、Server-Side で生成された UID2 identity を渡し (Implement server-side token generation を参照してください)、以下のようにモバイルアプリに渡してください:

UID2Manager.getInstance().setIdentity()

Token Storage​

setIdentity メソッドを呼び出すと、UID2 identity がローカルファイルストレージに永続化されます。

警告

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

Pass Generated Token for Bidstream Use​

トークンを取得するには、モバイルアプリで次のように呼び出します:

UID2Manager.getInstance().getAdvertisingToken()

UID2Manager への ID の追加が成功した場合、このメソッドは次のような文字列を返します:

A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g

この identity をダウンストリームに渡して RTB ビッドストリームに送信できます。

getAdvertisingToken()　メソッドが null を返す場合、identity または有効なトークンが生成されていません。これにはいくつかの理由が考えられ、トラブルシューティングするためにできることは次のとおりです:

  • Identity が無効です。この場合、いくつかのオプションがあります:
    • 前の setIdentity() 呼び出しでエラーがあるかどうかを確認します。
    • 以下のいずれかを使用して、identity のステータスを確認します:
      • Android Java: UID2Manager.getInstance().getCurrentIdentityStatus()
      • Android Kotlin: UID2Manager.getInstance().currentIdentityStatus()
      • iOS: UID2Manager.shared.identityStatus
  • ロギングを有効にして詳細情報を取得します: Enable Logging を参照してください。
  • UID2 identity 内の Advertising Token の有効期限が切れていて、Refresh Token も有効期限が切れているため、SDK がトークンをリフレッシュできません。

ID が無効の場合、Implement Server-Side Token Generation に従って新しい identity を生成し、その結果をモバイルアプリの UID2Manager に再度渡してください。

When to Pass a new UID2 Identity/Token into the SDK​

UID2 SDK が新しい UID2 identity を再度必要とするかどうかを判断するための最良の方法は、すべてのケースで getAdvertisingToken() メソッドを呼び出すことです:

UID2Manager.getInstance().getAdvertisingToken()

アプリの起動/再開時に、getAdvertisingToken() が null を返す場合、Implement Server-Side Token Generation の手順に従ってサーバーで、新しい identity を生成してください。その後、モバイルアプリの UID2Manager に結果を再度渡してください: 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
)

Enable Automatic Token Refresh in Mobile App/Client Side​

デフォルトでは、有効な UID2 ID が UID2Manager に渡されると、自動的にトークンリフレッシュが実行されます。トークンリフレッシュが無効になっていた場合、次のメソッド呼び出しで有効にできます:

Android Java:

UID2Manager.getInstance().setAutomaticRefreshEnabled(false)

Android Kotlin:

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

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​

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()
    }