Android 版 FLEDGE のデベロッパー ガイド

Android 版プライバシー サンドボックスのドキュメントをご覧になる際は、[デベロッパー プレビュー] または [ベータ版] ボタンで対象のプログラム バージョンを選択してください（手順が異なる場合があります）。

フィードバックを送信

Android 版 FLEDGE には、Custom Audience API と Ad Selection API が用意されています。これらの API を使用することで、広告テクノロジー プラットフォームと広告主は、アプリ間の識別子の共有と、ユーザーのアプリ操作情報の第三者との共有を制限しながら、過去のアプリ エンゲージメントに基づくカスタマイズされた広告を配信できます。

Custom Audience API は、共通の意図を持ったユーザーのグループを表す「カスタム オーディエンス」の抽象化を主な役割としています。広告主は、ユーザーをカスタム オーディエンスに登録し、関連性の高い広告を関連付けることができます。この情報はローカルに保存され、広告主の入札、広告フィルタリング、広告レンダリングへの情報提供に使用されます。

Ad Selection API は、複数のデベロッパーがカスタム オーディエンスのオークションをローカルで実行することを可能にするフレームワークを提供します。これを実現するために、システムでは、カスタム オーディエンスに関連付けられた関連性の高い広告を検討し、広告テクノロジー プラットフォームがデバイスに返す広告に追加の処理を行います。

広告テクノロジー プラットフォームでは、これらの API を統合することで、ユーザーのプライバシーを保護するリマーケティングを実装できます。今後のリリースでは、アプリ インストール広告など、他のユースケースもサポートされる予定です。Android 版 FLEDGE の詳細については、設計案をご覧ください。

このデベロッパー ガイドでは、Android 版 FLEDGE を使用して以下を行う方法を説明します。

  1. カスタム オーディエンスの管理
  2. デバイスでの広告選択のセットアップと実行
  3. 広告のインプレッションのレポート

準備

始める前に、次のことを行ってください。

  1. Android 版プライバシー サンドボックス用に開発環境をセットアップします。
  2. サポート対象のデバイスにシステム イメージをインストールするか、Android 版プライバシー サンドボックスのサポートを含むエミュレータをセットアップします。

  3. ターミナルで、次の adb コマンドを使用して FLEDGE API へのアクセスを有効にします（デフォルトでは無効になっています）。

      adb shell device_config put adservices ppapi_app_allow_list \"*\"

  4. アプリ マニフェストに ACCESS_ADSERVICES_CUSTOM_AUDIENCE 権限を含めます。

      <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

  5. マニフェストの <application> 要素で広告サービス構成を参照します。

      <property android:name="android.adservices.AD_SERVICES_CONFIG"
            android:resource="@xml/ad_services_config" />

  6. マニフェストで参照される広告サービス XML リソースを指定します（res/xml/ad_services_config.xml など）。広告サービスの権限と SDK のアクセス制御の詳細をご覧ください。

      <ad-services-config>
    <custom-audiences allowAllToAccess="true" />
  </ad-services-config>

  7. デフォルトでは、Ad Selection API により、オークションやインプレッション レポート スクリプトが割り当てることのできるメモリの最大量に上限が適用されます。メモリ制限機能には、WebView バージョン 105.0.5195.58 以降が必要です。プラットフォームがバージョン チェックが適用して、これが満たされない場合に selectAds API と reportImpression API の呼び出しが失敗します。これをセットアップするには、2 つの方法があります。

    • 方法 1: 次の adb コマンドを実行してこのチェックを無効にします。

      adb device_config put fledge_js_isolate_enforce_max_heap_size false

    • 方法 2: Google Play ストアから WebView ベータ版をインストールします。これは、上記のバージョン以上である必要があります。

カスタム オーディエンスに参加する

カスタム オーディエンスは、広告主のアプリが決定した、共通の意図や関心を持つユーザーのグループを表します。アプリまたは SDK は、カスタム オーディエンスを使用して、特定のオーディエンス（ショッピング カートにアイテムを残しているユーザーなど）を示すことができます。カスタム オーディエンスの作成、またはそれへの参加を非同期で行うには、次の手順を実行します。

  1. CustomAudienceManager オブジェクトを初期化します。
  2. 購入者のパッケージや適切な名前などの主要なパラメータを指定して、CustomAudience オブジェクトを作成します。次に、CustomAudience オブジェクトを指定して JoinCustomAudienceRequest オブジェクトを初期化します。
  3. 非同期の joinCustomAudience() を、JoinCustomAudienceRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

次のパラメータの組み合わせにより、デバイス上のオブジェクトである CustomAudience のそれぞれが一意に識別されます。

  • owner: オーナーアプリのパッケージ名。暗黙的に、呼び出し元アプリのパッケージ名に設定されます。
  • buyer: このカスタム オーディエンスの広告を管理する、購入者の広告ネットワークの識別子。
  • name: カスタム オーディエンスの任意の名前または識別子。

CustomAudience の別のインスタンスを指定して joinCustomAudience() を繰り返し呼び出すと、owner, buyer、name のパラメータが一致する既存の CustomAudience が更新されます。プライバシー保護のため、API の結果で「作成」と「更新」は区別されません。

また、CustomAudience は、次の必須パラメータを指定して作成する必要があります。

  • 日次更新 URL: カスタム オーディエンスのユーザー入札シグナル、信頼できる入札データ、広告のレンダリング URL とメタデータを更新するために、バックグラウンドで毎日クエリされる HTTPS URL。
  • 入札ロジック URL: 購入者の JavaScript 入札ロジックを取得するために、広告選択でクエリされる HTTPS URL。この JavaScript に必要な関数のシグネチャを確認してください。

CustomAudience オブジェクトのオプション パラメータには、次のものがあります。

  • 有効化時刻: カスタム オーディエンスは、その有効化時刻後にのみ広告選択または日次更新に参加できます。使用をやめたユーザーのエンゲージメントなどに役立ちます。
  • 有効期限: この未来の時刻以降に、カスタム オーディエンスがデバイスから削除されます。
  • ユーザー入札シグナル: 購入者の入札ロジックの JavaScript が入札を生成するために広告選択プロセスで処理する、ユーザーが設定した言語や地域などのユーザー シグナルを含んだ JSON 文字列。この形式を使用することで、広告テクノロジー プラットフォームはプラットフォーム間でコードを再利用でき、JavaScript 関数での使用が簡単になります。
  • 信頼できる入札データ: 信頼できる Key-Value サーバーから入札シグナルを取得する広告選択プロセスで使用される HTTPS URL と文字列のリスト。
  • 広告: 広告選択に参加する広告に対応する AdData オブジェクトのリスト。各 AdData オブジェクトは、次の要素で構成されます。
    • レンダリング URL: 最終的な広告を表示するためにクエリされる HTTPS URL。
    • メタデータ: 広告選択プロセスで購入者の入札ロジックで処理する情報を含む、文字列にシリアル化された JSON オブジェクト。

以下に、CustomAudience オブジェクトのインスタンス化の例を示します。

Kotlin

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

Java

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

joinCustomAudience() の結果を処理する

非同期の joinCustomAudience() メソッドが OutcomeReceiver オブジェクトを使用して API 呼び出しの結果を通知します。

  • onResult() コールバックは、カスタム オーディエンスが正常に作成または更新されたことを通知します。
  • onError() コールバックは、2 つの状況を通知します。
    • JoinCustomAudienceRequest が無効な引数を指定して初期化されている場合、AdServicesException が IllegalArgumentException を原因として通知します。
    • 他のすべてのエラーでは、IllegalStateException が設定された AdServicesException を原因として受け取ります。

joinCustomAudience() の結果を処理する例を次に示します。

Kotlin

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

Java

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

カスタム オーディエンスから脱退する

ユーザーが特定のカスタム オーディエンスのビジネス基準を満たさなくなった場合、アプリまたは SDK は leaveCustomAudience() を呼び出して、そのカスタム オーディエンスをデバイスから削除できます。CustomAudience をその一意のパラメータに基づいて削除する手順は次のとおりです。

  1. CustomAudienceManager オブジェクトを初期化します。
  2. カスタム オーディエンスの buyer、name を指定して LeaveCustomAudienceRequest を初期化します。これらの入力フィールドの詳細については、カスタム オーディエンスに参加するをご覧ください。
  3. 非同期の leaveCustomAudience() メソッドを、LeaveCustomAudienceRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() の呼び出しと同様に、OutcomeReceiver が API 呼び出しの終了を通知します。プライバシー保護のため、エラー結果で内部エラーと無効な引数とは区別されません。一致するカスタム オーディエンスが正常に削除されたかどうかにかかわらず、API 呼び出しが完了すると onResult() コールバックが呼び出されます。

広告選択を実行する

FLEDGE を使用して広告を選択するには、次のようにして selectAds() メソッドを呼び出します。

  1. AdSelectionManager オブジェクトを初期化します。
  2. AdSelectionConfig オブジェクトを作成します。
  3. 非同期の selectAds() メソッドを、AdSelectionConfig オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

Kotlin

val adSelectionManager: AdSelectionManager =
    context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
        AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver)

Java

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
        new AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver);

selectAds() メソッドには AdSelectionConfig の入力が必要です。これには、次の必須パラメータを指定する必要があります。

  • 販売者: 広告選択を開始する、販売者の広告ネットワークの識別子。
  • 判断ロジック URL: 販売者の広告ネットワークの JavaScript ロジックを取得するためにクエリされる HTTPS URL。この JavaScript に必要な関数のシグネチャを確認してください。
  • カスタム オーディエンス購入者: 販売者に広告選択プロセスに参加することを許可されている、購入者の広告ネットワークの識別子の完全なリスト。これらの購入者の識別子は、参加するカスタム オーディエンスの CustomAudience.getBuyer() に対応しています。

以下のパラメータを指定して、さらに細かく広告選択をカスタマイズできます。

  • 広告選択シグナル: CustomAudience.getBiddingLogicUrl() から取得した購入者の入札ロジックの JavaScript で処理するシグナルを含む、文字列にシリアル化された JSON オブジェクト。
  • 販売者シグナル: AdSelectionConfig.getDecisionLogicUrl() から取得した販売者の JavaScript の判断ロジックで処理するシグナルを含む、文字列にシリアル化された JSON オブジェクト。
  • 購入者ごとのシグナル: CustomAudience.getBiddingLogicUrl() から取得した特定の購入者の入札ロジックの JavaScript で処理するシグナルを含む、文字列にシリアル化された JSON オブジェクトのマップ。シグナルは参加するカスタム オーディエンスの購入者のフィールドで識別されます。

広告が選択されると、結果、入札単価、シグナルは、以降のレポート用に内部的に保持されます。OutcomeReceiver.onResult() コールバックから、次を含む AdSelectionOutcome が返されます。

  • AdData.getRenderUrl() から取得した、落札された広告のレンダリング URL。
  • デバイス ユーザーに固有の広告選択の ID。この ID は、広告のインプレッションのレポートに使用されます。

広告選択が、無効な引数、タイムアウト、リソースの過剰消費などの理由で正常に完了できない場合、以下の挙動で OutcomeReceiver.onError() コールバックが AdServicesException を与えます。

  • 広告選択が無効な引数を指定して開始された場合、AdServicesException に IllegalArgumentException が原因として示されます。
  • 他のすべてのエラーでは、IllegalStateException が設定された AdServicesException を原因として受け取ります。

ウォーターフォール メディエーションを実行する

ウォーターフォール メディエーションでは、複数のサードパーティ SDK（サードパーティ ネットワーク）をファースト パーティ SDK メディエーション ネットワークによってオーケストレーションする必要があります。

サードパーティ ネットワーク

サードパーティ ネットワークでは、オークションの実行に必要なメソッドをメディエーション ネットワークが呼び出せるようにするためのアダプタを提供する必要があります。

  • 広告選択を実行する
  • インプレッションを報告する

以下は、メディエーション ネットワーク アダプタの例です。

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

各 SDK には、独自の広告選択サービス マネージャーとクライアント、独自の selectAds と reportImpressions の実装があります。SDK プロバイダの方は、広告選択を実行するおよび広告のインプレッションをレポートする（シングル SPP のインプレッション レポートの続き）をご覧ください。

メディエーション ネットワーク

サードパーティ ネットワークと同様に、メディエーション ネットワークでは selectAds と reportImpression の実装が必要です。詳しくは、広告選択を実行する方法と広告インプレッションを報告する方法に関するセクションをご覧ください。

メディエーション ネットワークは、メディエーション チェーンの実行と、メディエーション チェーンへの自身の配置を行います。次のセクションでは、このプロセスを設定して実行する方法について説明します。

メディエーション チェーンと入札単価の下限を取得する

メディエーション ネットワークは、ファーストパーティ（1P）のコンテキスト広告、メディエーション チェーン、サードパーティ ネットワークの最小価格（3P）を取得します。これは、メディエーション ネットワークによって実行されたコンテキスト広告を取得するリクエストで発生する可能性があります。メディエーション チェーンがサードパーティ ネットワークで反復処理を行う方法を決定します。入札単価の下限は adSelectionSignals としてオークション プロセスに渡すことができます。

メディエーション チェーンのネットワーク プレースメント

メディエーション SDK を、ファーストパーティの広告入札のライブ eCPM に基づいて、メディエーション チェーンに組み込むことができます。FLEDGE では、広告の入札単価は不透明です。メディエーション SDK は、AdSelectionFromOutcomesConfig を使用して、特定のファーストパーティ広告の入札単価を、チェーン内の次のサードパーティ ネットワークの入札下限と比較できます。ファーストパーティの入札価格が最小価格より高い場合、メディエーション SDK はそのサードパーティ ネットワークの前に配置されています。

広告選択を実行する

ファースト パーティ広告の候補を取得するために、広告選択を実行するセクションの手順に従い、メディエーション ネットワークがデバイス上でオークションを実行します。これにより、ファーストパーティの広告候補、入札単価、メディエーション プロセスで使用される AdSelectionId が生成されます。

AdSelectionFromOutcomesConfig を作成する

AdSelectionFromOutcomesConfig を使用すると、メディエーション ネットワークは AdSelectionIds（以前のオークションの結果）のリスト、広告選択シグナル、複数の候補から広告を選択する JavaScript を取得する URI を渡すことができるようになります。AdSelectionIds のリストと入札のリストおよびそれらのシグナルは、JavaScript に渡されます。この JavaScript は、入札単価の下限を上回った場合は AdSelectionIds のいずれかを返し、メディエーション チェーンを継続する必要がある場合は何も返しません。

メディエーション ネットワークは、前のセクションのファーストパーティ AdSelectionId を使用して AdSelectionFromOutcomesConfig を作成し、サードパーティ ネットワークの入札単価の下限を考慮します。メディエーション チェーンの各ステップに新しい AdSelectionFromOutcomesConfig を作成する必要があります。

Kotlin

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

Java

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

ウォーターフォール メディエーションの selectAds() メソッドのオーバーライドには AdSelectionFromOutcomesConfig 入力が必要です。ここで、次の必須パラメータを指定する必要があります。

  • 販売者: 広告選択を開始する、販売者の広告ネットワークの識別子。
  • AdSelectionIds: ファースト パーティ広告に対して実行された過去の selectAds() のシングルトン リスト。
  • 広告選択シグナル: 購入者の入札ロジックで使用するシグナルを含む、文字列としてシリアル化された JSON オブジェクト。この場合、特定のサードパーティ ネットワークに関して取得した最小価格を含みます。
  • 選択ロジック URI: 落札広告を選択するためのメディエーション ネットワークの JavaScript を取得するために、広告選択中にクエリされる HTTPS URL。この JavaScript に必要な関数のシグネチャを確認してください。JavaScript が、入札額が入札単価の下限よりも高い場合はサードパーティ広告を返し、そうでない場合は null を返します。これにより、メディエーション SDK で落札者が見つかった場合にメディエーション チェーンを切り捨てることができます。

AdSelectionOutcomesConfig を作成した状態で、チェーンの最初であるサードパーティ ネットワークの selectAds() メソッドを呼び出します。

Kotlin

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

Java

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

ウォーターフォール メディエーションをオーケストレートする

以下は、メディエーション プロセスの実行順序です。

  1. ファースト パーティ広告選択を実行します。
  2. メディエーション チェーンを反復処理します。サードパーティ ネットワークごとに次の操作を行います。
    1. ファーストパーティの outcomeId とサードパーティの SDK の入札単価の下限を含む AdSelectionFromOutcomeConfig を作成します。
    2. 前のステップの構成を行って selectAds() を呼び出します。
    3. 結果が空でない場合は、広告を返します。
    4. 現在の SDK ネットワーク アダプターの selectAds() メソッドを呼び出します。結果が空でない場合は、広告を返します。
  3. チェーンで落札者が見つからなかった場合は、ファースト パーティ広告を返します。

Kotlin

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

Java

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

広告のインプレッションのレポート

オークションの実行方法に応じた、広告のインプレッションをレポートする 2 つのフローがあります。オークションを行う単一の SSP である場合は、このセクションに従います。ウォーターフォール メディエーションを実装する場合は、ウォーターフォール メディエーションのインプレッション レポートのセクションに記載されている手順に従ってください。

シングル SPP インプレッション レポート

広告選択ワークフローで落札する広告が選択されると、AdSelectionManager.reportImpression() メソッドを使用して、参加しているバイサイド プラットフォームとセルサイド プラットフォームにインプレッションをレポートできます。広告のインプレッションをレポートするには:

  1. AdSelectionManager オブジェクトを初期化します。
  2. 広告選択 ID を指定して ReportImpressionRequest オブジェクトを作成します。
  3. 非同期の reportImpression() メソッドを、AdSelectionConfig オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

Java

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig);
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

Kotlin

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig);
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

次の必須パラメータを指定して ReportImpressionRequest を初期化します。

  • 広告選択 ID: 成功した広告選択を識別する、デバイス ユーザーに固有の ID。
  • 広告選択設定: 指定された広告選択 ID で識別される selectAds() 呼び出しで使用されている設定と同じものです。

非同期の reportImpression() メソッドが OutcomeReceiver オブジェクトを使用して API 呼び出しの結果を通知します。

  • onResult() コールバックは、広告選択が完了したかどうかを示します。
  • onError() コールバックは、次の状況を通知します。
    • 呼び出しが無効な入力引数を指定して初期化されている場合、AdServicesException は IllegalArgumentException を原因として示します。
    • 他のすべてのエラーでは、IllegalStateException が設定された AdServicesException を原因として受け取ります。

ウォーターフォール メディエーションのインプレッション レポート

メディエーション SDK は、落札された SDK をトラッキングしてレポートフローをトリガーする必要があります。メディエーション チェーンに参加する SDK は、メディエータが独自の報告フローをトリガーするために呼び出すメソッドを提供する必要があります。メディエーション オークションに参加する SDK は、上記の手順に沿って独自のレポートを実装できます。

SSP は、次のサードパーティの SDK コード例を、メディエーション フローに参加する方法のプロトタイプとして使用できます。

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

インプレッション レポートのエンドポイント

レポート インプレッション API は、セルサイド プラットフォームが提供するエンドポイントと、落札したバイサイド プラットフォームが提供するエンドポイントに、HTTPS GET リクエストを発行します。

バイサイド プラットフォームのエンドポイント:

  • この API は、カスタム オーディエンスで指定された入札ロジック URL を使用して、購入者の入札ロジックの JavaScript を取得します。
  • reportResult() JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。

セルサイド プラットフォーム エンドポイント:

  • AdSelectionConfig オブジェクトで指定された判断ロジック URL を使用して、販売者の判断ロジックの JavaScript を取得します。
  • reportWin() JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。

ベスト エフォート型のインプレッション レポート

reportImpression() は、ベスト エフォートでレポートを行うように設計されています。

毎日のバックグラウンド更新

カスタム オーディエンスを作成する際、アプリまたは SDK はカスタム オーディエンス メタデータを初期化できます。さらに、プラットフォームは毎日のバックグラウンド更新プロセスで以下のカスタム オーディエンス メタデータを更新できます。

  • ユーザー入札シグナル
  • 信頼できる入札データ
  • AdData リスト

このプロセスでは、カスタム オーディエンスで定義されている日次更新の URL に対してクエリが行われ、URL から JSON レスポンスが返される場合があります。

  • JSON レスポンスには、更新が必要なサポートされているメタデータ フィールドが含まれている場合があります。
  • 各 JSON フィールドは個別に検証されます。クライアントは、レスポンス内の特定のフィールドを更新しない、不適切な形式のフィールドを無視します。
  • 空の HTTP レスポンス、または空の JSON オブジェクト「{}」では、メタデータは更新されません。
  • レスポンス メッセージのサイズは 10 KB に制限する必要があります。
  • HTTPS を使用するには、すべての URI が必要です。
  • trusted_bidding_uri は、購入者と同じ ETLD+1 を共有する必要があります。

例: バックグラウンドでの日次更新の JSON レスポンス

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

広告選択用の JavaScript

広告選択ワークフローでは、購入者提供の JavaScript と販売者提供の JavaScript の実行についてオーケストレーションを行います。

購入者提供の JavaScript は、カスタム オーディエンスで指定された入札ロジックの URL から取得されます。返される JavaScript には次の関数が含まれます。

販売者提供の JavaScript は、広告選択 API の AdSelectionConfig パラメータで指定された判断ロジック URL から取得されます。返される JavaScript には次の関数が含まれます。

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

入力パラメータ:

  • ad: var ad = { 'render_url': url, 'metadata': json_metadata }; 形式の JSON オブジェクト。
  • auction_signals, per_buyer_signals: オークション設定オブジェクトで指定された JSON オブジェクト。

  • custom_audience_bidding_signals: プラットフォームによって生成された JSON オブジェクト。この JSON オブジェクトの形式は次のとおりです。

    var custom_audience_bidding_signals = {
  "owner":"ca_owner",
  "buyer":"ca_buyer",
  "name":"ca_name",
  "activation_time":"ca_activation_time_epoch_ms",
  "expiration_time":"ca_expiration_time_epoch_ms",
  "user_bidding_signals":"ca_user_bidding_signals"
}

    ここで:

    • owner, buyer と name は、広告選択に参加するカスタム オーディエンスと同じ名前のプロパティから取得された文字列です。
    • activation_time と expiration_time は、それぞれカスタム オーディエンスの有効化時刻と有効期限です。Unix エポックからの経過秒数で表されます。
    • ca_user_bidding_signals は、作成時に CustomAudience の userBiddingSignals フィールドで指定された JSON 文字列です。
    • trusted_bidding_signals, contextual_signals と user_signals は、JSON オブジェクトです。現在は空のオブジェクトで渡されますが、今後のリリースでは、空でないオブジェクトが渡される予定です。これらの形式はプラットフォームでは適用されず、広告テクノロジー プラットフォームが管理します。

結果:

  • ad: 入札が参照する広告。スクリプトは、受け取った広告のコピーを、さまざまなメタデータとともに返すことができます。広告の render_url プロパティが変更されることはありません。
  • bid: この広告の入札単価を表す浮動小数点値。
  • status: 次の整数値。
    • 0: 実行が成功した場合。
    • 1（またはゼロ以外の値）: 入力シグナルのいずれかが無効な場合。generate-bid がゼロ以外の値を返す場合、すべての CA 広告の入札プロセスが無効になります。

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_scoring_signals) {
    return {'status': 0, 'score': score };
}

入力パラメータ:

  • ad: generateBid のドキュメントをご覧ください。
  • bid: 広告の入札単価。

  • ad_selection_config: selectAds API の AdSelectionConfig パラメータを表す JSON オブジェクト。形式は次のとおりです。

    var ad_selection_config = {
  'seller': 'seller',
  'decision_logic_url': 'url_of_decision_logic',
  'custom_audience_buyers': ['buyer1', 'buyer2'],
  'auction_signals': auction_signals,
  'per_buyer_signals': per_buyer_signals,
  'contextual_ads': [ad1, ad2]
}

  • seller_signals: sellerSignals AdSelectionConfig API パラメータから読み取った JSON オブジェクト。

  • trusted_scoring_signal: AdSelectionConfig API パラメータの adSelectionSignals フィールドから読み取ります。

  • contextual_signals, user_signals: JSON オブジェクト。現在は空のオブジェクトで渡されますが、今後のリリースでは、空でないオブジェクトが渡される予定です。これらの形式はプラットフォームでは適用されず、広告テクノロジーが管理します。

  • per_buyer_signals: AdSelectionConfig API パラメータの perBuyerSignal マップから現在のカスタム オーディエンス購入者をキーに使用して読み取られた JSON オブジェクト。マップに指定された購入者のエントリが含まれていない場合は空になります。

出力:

  • score: この広告のスコア値を表す浮動小数点値。
  • status: 次の整数値。
    • 0: 実行が成功した場合。
    • 1: customAudienceSignals が無効の場合。
    • 2: AdSelectionConfig が無効な場合。
    • 3: 他のシグナルのいずれかが無効な場合。
    • ゼロ以外の値があるとプロセスが失敗し、値によってスローされる例外のタイプが決まります

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

入力パラメータ:

  • outcomes: JSON オブジェクト {“id”: id_string, “bid”: bid_double}
  • selection_signals: オークション設定オブジェクトで指定された JSON オブジェクト。

出力:

  • status: 0 が成功の場合で、失敗の場合はゼロ以外。
  • result: 渡された結果のいずれか、または null

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

入力パラメータ:

  • ad_selection_config: scoreAds のドキュメントをご覧ください。
  • render_url: 落札された広告のレンダリング URL。
  • bid: 落札された広告に提示された入札単価。
  • contextual_signals: generateBid のドキュメントをご覧ください。

出力:

  • status: 0 が成功の場合で、失敗の場合はゼロ以外。
  • results: 次を含む JSON オブジェクト。
    • signals_for_buyer: reportWin 関数に渡される JSON オブジェクト。
    • reporting_url: プラットフォームが購入者にインプレッションを通知するために使用する URL

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_reporting_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

入力パラメータ:

  • ad_selection_signals、per_buyer_signals: scoreAd のドキュメントをご覧ください。
  • signals_for_buyer: reportResult が返す JSON オブジェクト。
  • contextual_signals、custom_audience_reporting_signals: generateBid のドキュメントをご覧ください。

出力:

  • status: 0 が成功の場合で、失敗の場合はゼロ以外。
  • results: 次を含む JSON オブジェクト。
    • reporting_url: プラットフォームが販売者にインプレッションを通知するために使用する URL

テスト

FLEDGE を簡単に始められるように、Kotlin と Java のサンプルアプリを作成しました。[GitHub][43]{:.external} から入手できます。

前提条件

FLEDGE は、広告選択とインプレッション レポートの際、JavaScript を必要とします。この JavaScript をテスト環境で提供する方法は 2 つあります。

  • JavaScript を返す必要な HTTPS エンドポイントを使用してサーバーを稼働させる
  • ローカルソースから必要なコードを提供することでリモート取得をオーバーライドする

いずれの方法でも、インプレッション レポートを処理するために HTTPS エンドポイントをセットアップする必要があります。

HTTPS エンドポイント

広告選択とインプレッション レポートをテストするには、テストデバイスまたはエミュレータがアクセスできる HTTPS エンドポイントを 7 台セットアップする必要があります。

  1. 入札ロジックの JavaScript を提供する購入者のエンドポイント。
  2. 入札シグナルを提供するエンドポイント。
  3. 判断ロジックの JavaScript を提供する販売者のエンドポイント。
  4. スコアリング シグナルを提供するエンドポイント。
  5. 落札した購入者のインプレッション レポート用エンドポイント
  6. 販売者のインプレッション レポート用エンドポイント
  7. カスタム オーディエンスの日次更新を提供するエンドポイント。

GitHub リポジトリにテスト用の基本的な JavaScript コードを用意しています。サポートされているモックまたはマイクロサービスのプラットフォームにデプロイ可能な OpenAPI サービス定義も含まれています。詳しくは、プロジェクトの [README][43]{:.external} をご覧ください。

JavaScript のリモート取得をオーバーライドする

この機能は、エンドツーエンドのテストに使用することを目的としています。リモート取得をオーバーライドするには、開発者向けオプションを有効にして、アプリをデバッグモードで実行する必要があります。

アプリのデバッグモードを有効にするには、AndroidManifest.xml の application 属性に次の行を追加します。

<application
  android:debuggable="true">

これらのオーバーライドの使用例については、GitHub の [FLEDGE サンプルアプリ][43]{:.external} をご覧ください。

入札、スコア決定、レポートなどの広告選択ルーチンを処理するために、独自のカスタム JavaScript を追加する必要があります。必要なすべてのリクエストを処理する基本的な JavaScript コードの例が [GitHub リポジトリ][43]{:.external} にあります。FLEDGE サンプルアプリは、そのファイルからコードを読み取り、オーバーライドとして使用するために準備する方法を示しています。

セルサイドとバイサイドの JavaScript 取得を個別にオーバーライドすることもできますが、オーバーライドしない JavaScript を提供するには HTTPS エンドポイントが必要となります。このようなケースに対応するサーバーのセットアップ方法については、[README][43]{:.external} をご覧ください。

パッケージ取得元の JavaScript 取得をオーバーライドできるのは、パッケージが所有しているカスタム オーディエンスのみです。

セルサイドの JavaScript をオーバーライドする

セルサイドの JavaScript のオーバーライドをセットアップするには、以下のサンプルコードのようにします。

  1. AdSelectionManager オブジェクトを初期化します。
  2. AdSelectionManager オブジェクトから TestAdSelectionManager への参照を取得します。
  3. AdSelectionConfig オブジェクトを作成します。
  4. AdSelectionConfig オブジェクトと、オーバーライドとして使用する JavaScript を表す String を指定して、AddAdSelectionOverrideRequest を作成します。
  5. 非同期の overrideAdSelectionConfigRemoteInfo() メソッドを、AddAdSelectionOverrideRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

Kotlin

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

AdSelectionConfig の各フィールドの意味について詳しくは、広告選択を実行するのセクションをご覧ください。重要な違いは、decisionLogicUrl は無視されるためプレースホルダ値に設定できるという点です。

広告選択時に使用する JavaScript をオーバーライドするには、decisionLogicJs に販売者側の適切な関数シグネチャが含まれている必要があります。JavaScript ファイルを文字列として読み取る方法の例については、GitHub の [FLEDGE サンプルアプリ][43]{:.external} をご覧ください。

非同期の overrideAdSelectionConfigRemoteInfo() メソッドが OutcomeReceiver オブジェクトを使用して API 呼び出しの結果を通知します。

onResult() コールバックは、オーバーライドが正常に適用されたことを示します。selectAds() に対する以降の呼び出しでは、渡した判断とレポートのロジックがすべてオーバーライドとして使用されます。

onError() コールバックは、2 つの状況を通知します。

  • オーバーライドが無効な引数を指定して試みられた場合、AdServiceException は原因として IllegalArgumentException を示します。
  • 開発者向けオプションを有効にしたデバッグモードで実行されているわけではないアプリでオーバーライドが試みられた場合、AdServiceException は原因として IllegalStateException を示します。

セルサイドのオーバーライドをリセットする

このセクションでは、セルサイドの JavaScript をオーバーライドしていることと、前のセクションで使用した TestAdSelectionManager と AdSelectionConfig への参照があることを前提としています。

すべての AdSelectionConfigs のオーバーライドをリセットするには:

  1. 非同期の resetAllAdSelectionConfigRemoteOverrides() メソッドを、適切な OutcomeReceiver オブジェクトを指定して呼び出します。

Kotlin

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

Java

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

セルサイドのオーバーライドをリセットした後、selectAds() への呼び出しが AdSelectionConfig に格納されている decisionLogicUrl を使用して、必要な JavaScript の取得を試みます。

resetAllAdSelectionConfigRemoteOverrides() の呼び出しが失敗した場合、OutComeReceiver.onError() コールバックは AdServiceException を提供します。開発者向けオプションを有効にしてデバッグモードで実行していないアプリでオーバーライドの削除を試みた場合、AdServiceException は原因として IllegalStateException を示します。

バイサイドの JavaScript をオーバーライドする

  1. カスタム オーディエンスに参加する手順を実施します。
  2. オーバーライドとして使用する入札ロジックとデータに加え、オーバーライドするカスタム オーディエンスの購入者と名前を指定して、AddCustomAudienceOverrideRequest を作成します。
  3. 非同期の overrideCustomAudienceRemoteInfo() メソッドを、AddCustomAudienceOverrideRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

Kotlin

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

購入者と名前の値は、カスタム オーディエンスの作成に使用したものと同じです。これらのフィールドの詳細についてはこちらをご覧ください。

さらに、次の 2 つのパラメータを追加で指定できます。

  • biddingLogicJs: 広告選択で使用する購入者のロジックを保持する JavaScript。この JavaScript に必要な関数のシグネチャを確認してください。
  • trustedBiddingSignals: 広告選択で使用する入札シグナル。テスト用に空の文字列を指定できます。

非同期の overrideCustomAudienceRemoteInfo() メソッドが OutcomeReceiver オブジェクトを使用して API 呼び出しの結果を通知します。

onResult() コールバックは、オーバーライドが正常に適用されたことを示します。その後の selectAds() の呼び出しでは、渡した入札とレポートのロジックがすべてオーバーライドとして使用されます。

onError() コールバックは、2 つの状況を通知します。

  • オーバーライドが無効な引数を指定して試みられた場合、AdServiceException は原因として IllegalArgumentException を示します。
  • 開発者向けオプションを有効にしたデバッグモードで実行されているわけではないアプリでオーバーライドが試みられた場合、AdServiceException は原因として IllegalStateException を示します。

バイサイドのオーバーライドをリセットする

このセクションでは、バイサイドの JavaScript をオーバーライドしていることと、前のセクションで使用した TestCustomAudienceManager への参照があることを前提としています。

すべてのカスタム オーディエンスのオーバーライドをリセットするには:

  1. 非同期の resetAllCustomAudienceOverrides() メソッドを、適切な Executor オブジェクトと OutcomeReceiver オブジェクトを指定して呼び出します。

Kotlin

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Java

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

バイサイドのオーバーライドをリセットすると、それ以降の selectAds() の呼び出しは、CustomAudience に保存されている biddingLogicUrl と trustedBiddingData を使用して、必要な JavaScript を取得しようとします。

resetCustomAudienceRemoteInfoOverride() の呼び出しが失敗した場合、OutComeReceiver.onError() コールバックは AdServiceException を提供します。開発者向けオプションを有効にしたデバッグモードで実行されているわけではないアプリでオーバーライドの削除が試みられた場合、AdServiceException は原因として IllegalStateException を示します。

レポート サーバーをセットアップする

リモート取得をオーバーライドする場合でも、レポート イベントに対応するためにデバイスまたはエミュレータが利用できるサーバーをセットアップする必要があります。テストには、200 を返すシンプルなエンドポイントで十分です。GitHub リポジトリには、サポートされているモックまたはマイクロサービスのプラットフォームにデプロイ可能な OpenAPI サービス定義が含まれています。詳しくは、プロジェクトの [README][43]{:.external} をご覧ください。

OpenAPI 定義を探す場合は、reporting-server.json を探します。このファイルには、HTTP レスポンス コード 200 を返すシンプルなエンドポイントが含まれています。このエンドポイントは selectAds() で使用され、インプレッション レポートが正常に完了したことを FLEDGE に通知します。

テストする機能

  • ユーザーのこれまでの行動に基づいてカスタム オーディエンスへの参加、そこからの脱退、そのセットアップを行う。
  • リモートでホストされる JavaScript を使い、オンデバイスの広告選択を開始する。
  • アプリのカスタム オーディエンス設定との関連付けが、広告選択の結果にどのように影響するかを確認する。
  • 広告選択後のインプレッション レポートを行う。

制限事項

次の表に、FLEDGE 処理の制限を示します。ここに示されている制限は、フィードバックに基づいて変更される可能性があります。処理中の機能については、リリースノートをご覧ください。

コンポーネント 制限の説明 制限値
カスタム オーディエンス（CA） CA あたりの広告の最大数 100
アプリケーションあたりの CA の最大数 1000
CA を作成できるアプリの最大数 1000
CA の作成時刻から有効化時刻までの最大レイテンシ 60 日間
有効にしてからの CA の最大有効期限 60 日間
デバイス上の CA の最大数 4,000
CA 名の最大サイズ 200 バイト
日時取得 URI の最大サイズ 400 バイト
入札ロジック URI の最大サイズ 400 バイト
信頼できる入札データの最大サイズ 10 KB
ユーザー入札シグナルの最大サイズ 10 KB
購入者あたりの leaveCustomAudience の最大呼び出しレート 1 秒あたり 1
購入者あたりの joinCustomAudience の最大呼び出しレート 1 秒あたり 1
CA バックグラウンド取得 接続タイムアウト 5 秒
HTTP 読み取りタイムアウト 30 秒
最大の合計ダウンロード サイズ 10 KB
取得反復処理の最長時間 5 分
ジョブあたりのアップデートされる CA の最大数 1000
広告の選択 購入者の最大数 未定
購入者あたりの CA の最大数 未定
オークションあたりの広告の最大数 未定
初期接続タイムアウト 5 秒
接続読み取りタイムアウト 5 秒
AdSelection 全体の最長実行時間 10 秒
AdSelection での CA あたりの入札の最長実行時間 5 秒
AdSelection でのスコアリングの最長実行時間 5 秒
AdSelection での購入者ごとの最長実行時間 未定
広告選択 / 販売者 / 購入者ごとのシグナルの最大サイズ 未定
販売者 / 購入者のスクリプトの最大サイズ 未定
selectAds の最大呼び出しレート 1 QPS
インプレッション レポート 広告選択が永続性から削除されるまでの最小時間 24 時間
ストレージ広告選択の最大数 未定
レポート出力 URL の最大サイズ 未定
インプレッション レポートの最長期間 未定
通知呼び出しの再試行の最大回数 未定
接続タイムアウト 5 秒
reportImpression 全体の最長実行時間 2 秒
reportImpressions の最大呼び出しレート 1 QPS
広告 広告リストの最大サイズ 10 KB（コンテキストの場合、単一の CA の AdData すべてで共有）
URL 入力として使用される URL 文字列の最大長 未定
JavaScript 最長実行時間 インプレッション レポートの入札とスコアリングで 1 秒
最大使用メモリ 10 MB

バグと問題を報告する

皆様からのフィードバックは、Android 版プライバシー サンドボックスに欠かせない要素です。問題が見つかった場合や Android 版プライバシー サンドボックスを改善するためのアイデアがありましたらお知らせください。