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

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 and configure account.
  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 を使用する方法について説明します:

  • SDK for Android (version 1.6.0 以降)
  • SDK for iOS (version 1.7.0 以降)

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

Integrating with Single Sign-On (SSO)​

SSO ログインを提供するために1つ以上の SSO プロバイダーとインテグレーションしている場合、SSO プロバイダーからログインユーザーのメールアドレスを取得して UID2 Token を生成できる可能性があります。

詳細は、Publisher Integration with SSO Providers を参照してください。

Preparing DII for Processing​

UID2 に変換する入力データが許容可能な形式であることは非常に重要です。そうでない場合、期待される結果は得られません。たとえば、Phone Number Normalization で説明されているように、電話番号には国コードを含めるように正規化する必要があります。

詳細は、Preparing Emails and Phone Numbers for Processing を参照してください。

フルトークン生成パイプラインをエンドツーエンドで検証し、正規化・ハッシュ化・エンコードされた値から生成されたトークンが正確であることを確認するためには、［UID2 Token Validator］（../ref-info/ref-token-validator.md）を使用してください。

Complete UID2 Account Setup and Configure Account​

UID2 とインテグレーションするには、UID2 アカウントが必要です。アカウントをまだ作成していない場合は、まず Account Setup ページの手順に従ってください。

アカウントの初期設定が完了すると、UID2 Portal にアクセスするための手順とリンクが送信されます。ここで、本番環境用の credentials を作成し、必要に応じて追加の値を設定できます。詳細は、Getting Started with the UID2 Portal を参照してください。

Client-Server インテグレーションには、UID2 Portal の API Keys ページでこれらの値を設定する必要があります:

  • API Key、Client Key とも呼ばれます
  • Client Secret、参加者と UID2 Service のみが知っている値
important

これらの値を安全に保管することが非常に重要です。詳細は、Security of 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 Key と Client Secret は Server-Side で呼び出す必要があります。これらの値をモバイルアプリ内に保存しないでください。

Server-Side Token Refresh​

UID2 mobile SDK では トークンリフレッシュ が自動的に有効になっています。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 を指定してください。

各環境の認証情報を取得する方法は、Getting Your Credentials を参照してください。

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

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

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

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
  • ロギングを有効 (isLoggingEnabled を true に設定する) にして詳細情報を取得します: Enable Logging を参照してください。
  • UID2 Identity 内の Advertising Token の有効期限が切れていて、Refresh Token も有効期限が切れているため、SDK がトークンをリフレッシュできません。

Identity が無効の場合、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​

UID2 SDK はログを生成することができ、UID2 インテグレーションにログを使用して問題をデバッグすることができます。ログを有効にするには、次の手順を実行します:

// 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​

UID2 Token を生成して Google GMA SDK または Google IMA SDK に送信する場合、このガイドに従っていると仮定して、モバイルアプリに UID2 GMA/IMA プラグインを追加する必要があります。手順は、該当するプラグインガイドを参照してください。

Advertising Token を取得して Google GMA/IMA SDK に手動で渡すために、明示的に getAdvertisingToken() メソッドを呼び出す必要はありません。UID2 GMA/IMA プラグインが自動的に処理します。

必要なことは、getAdvertisingToken() が null でない文字列オブジェクトを返すようにするだけです。

UID2Manager.getInstance().getAdvertisingToken()

トークンが存在する場合、Google GMA/IMA プラグインは UID2 GMA/IMA プラグインを介して自動的に取得できます。

Optional: UID2 Integration with Prebid Mobile SDK​

important

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

Prebid Mobile SDK v3 を使用している場合は、UID2 SDK for Android または iOS のバージョン 2.0.0 が必要です。

このセクションは、UID2 とインテグレーションし、Android および iOS アプリケーションでヘッダービディングを行うために Prebid Mobile SDK を使用したい参加者向けです。

UID2 Prebid インテグレーションは、UID2Identity の状態を監視します。状態が変更されるたびに、Prebid インテグレーションは自動的に Prebid の外部ユーザー ID を更新します。これには、Identity がリフレッシュされ、新しい Advertising Token が生成される場合も含まれます。

Prebid は、UID2 Token を RTB ビッドストリームに送信し、設定した他の外部ユーザー ID と共に送信します。

注記

このインテグレーションには、Prebid Server のセットアップが必要です。

UID2 Prebid for Mobile インテグレーションを設定するには、次の手順に従います:

  1. Prebid SDK Integration for Android または Prebid SDK Integration for iOS の手順に従って、Prebid の Mobile SDK を設定します。

  2. Add the UID2 Mobile SDK to Your Mobile App の手順に従って、UID2 Mobile SDK をアプリに追加します。

  3. UID2 Prebid インテグレーションは別のモジュールとして配布されているため、プロジェクトの依存関係として追加する必要があります。以下のオプションのいずれかに適用されるインストール手順に従います:

    Gradle の設定に以下を追加します:

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

  4. 依存関係を追加した後、インテグレーションの設定が必要です。最初に UID2Manager を初期化し、次に Prebid を初期化します。次の例に示すように行います。

    UID2Manager.init(context = this)

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

  5. 初期化の際に渡されるコールバックを設定します。

    UID2 Prebid インテグレーションは、新しい Identity が生成されるか、既存のトークンがリフレッシュされるたびに、関連する外部ユーザー ID を設定することで、定期的に Prebid を更新します。

    このプロセスは破壊的であり、アプリケーションが他のソースから外部 ID を使用している場合、UID2 Prebid インテグレーションにそれらを提供する必要があります。これにより、UID2 Token が更新される間、すべての外部 ID が保持されます。

    これは、以下の例に示される通り、初期化中に渡されるコールバックを介して行われます。

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

Error Response States​

特定の条件下では、モバイル SDK は次のいずれかのエラーレスポンス状態を返す可能性があります:

注記

レスポンスステータスは、Android と iOS の両方で同じです。

Response State of Expired​

Expired のレスポンスステータスは、UID2 Token が有効期限切れであることを示しますが、リフレッシュトークンは有効期限切れではないため、UID2 Token をリフレッシュできます。

Automatic refresh: SDK で自動リフレッシュが有効になっている場合 (automaticRefreshEnabled プロパティ)、SDK がトークンを自動的にリフレッシュします。ただし、この状態が発生する可能性があるいくつかのシナリオがあります。

たとえば、アプリが起動され、SDK がすぐにクエリされた場合、レスポンスステータスが Expired になる可能性がありますが、バックグラウンドで SDK がトークンをリフレッシュしており、すぐに新しい ID で更新されます。

この場合、何もする必要はありません。SDK が初期化されるとすぐにトークンがリフレッシュされます。

Manual refresh: トークンの自動リフレッシュを無効にしている場合、Expired のレスポンスステータスが返された場合、refreshIdentity() メソッドを呼び出してリフレッシュを手動でリクエストできます。

Response State of RefreshExpired​

RefreshExpired のレスポンスステータスは、UID2 Token と Refresh Token の両方が有効期限切れであることを示します。そのため、UID2 Token をリフレッシュできません。

このような状況が発生する可能性がある例としては、ユーザーがアプリを長期間実行しない場合、SDK が Refresh Token が期限切れになる前に UID2 Token をリフレッシュする機会がない場合があります。

この場合、Identity を再生成する必要があります。

Response State of Invalid​

Invalid のレスポンスステータスは、ディスクからロードされたか、API 経由でリクエストされた ID に、必要なすべてのトークンが含まれていないことを示します。これは起こるべきではありませんが、予期しない状況で発生する可能性があります。

SDK がこのエラーを検出すると、以前の ID は使用できないと見なされるため、クリアされます。

この場合、Identity を再生成する必要があります。また、問題を UID2 の連絡先に報告することが望ましいです。

Response State of NoIdentity​

NoIdentity のレスポンスステータスは、SDK は初期化されていますが、現在の identity がまだ生成されていないことを示します。

これは、デバイスで初めて SDK が使用される場合に発生します。この場合、identity を生成する必要があります。