Protected Audience API デベロッパー ガイド

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

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

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

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

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

このガイドでは、Android 版 Protected Audience API を使用して次のことを行う方法を説明します。

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

準備

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

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

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

      adb shell device_config put adservices ppapi_app_allow_list \"*\"

  4. ターミナルで次の adb コマンドを使用してビーコン レポートを有効にします。

     adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
 adb shell device_config put adservices fledge_register_ad_beacon_enabled true

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

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

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

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

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

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

  8. デフォルトでは、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 に必要な関数シグネチャを確認してください。
  • 広告レンダリング ID: 購入者の広告テクノロジーが設定する任意の ID。これは、B&A のペイロード生成を最適化するためのものです。

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 =
    LeaveCustomAudienceRequest.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 LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

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

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

広告選択を実行する

Protected Audience API を使用して広告を選択するには、次のように 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)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).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)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

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

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

  • 販売者: 広告選択を開始する、販売者の広告ネットワークの識別子。
  • 判断ロジック URL: 販売者の広告ネットワークの JavaScript ロジックを取得するためにクエリされる HTTPS URL。
    • HTTPS URL: 販売者の広告ネットワークの JavaScript ロジックを取得するためにクエリされます。 必要な関数シグネチャを確認してください。
    • 事前構築済み URI: FLEDGE の広告選択形式に準拠しています。サポートされていない、または形式が正しくないビルド済み URI が渡された場合、IllegalArgumentException がスローされます。
  • カスタム オーディエンス購入者: 販売者に広告選択プロセスに参加することを許可されている、購入者の広告ネットワークの識別子の完全なリスト。これらの購入者 ID は、参加するカスタム オーディエンスの CustomAudience.getBuyer() に対応します。

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

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

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

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

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

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

コンテキスト広告

Protected Audience では、Protected Auction にコンテキスト広告を組み込むことができます。 コンテキスト広告は、広告テクノロジー サーバーで選択し、Protected Audience API の外部からデバイスに返す必要があります。コンテキスト広告は、AdSelectionConfig を使用してオークションに参加できます。その時点で、除外広告フィルタの利用資格など、デバイス広告と同じように機能します。Protected Audience オークションが完了したら、reportImpression() を呼び出す必要があります。このメソッドは、落札されたコンテキスト広告の reportWin() をインプレッション レポートと同じパターンで呼び出し、デバイスで落札広告を受け取ります。コンテキスト広告には、購入者、入札単価、レポート ロジックへのリンク、レンダリング URL、広告メタデータが必要です。

アプリにコンテキスト広告をデプロイするには、ターゲット アプリで ContextualAds オブジェクトを作成する必要があります。

Kotlin

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

Java

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

結果の ContextualAds オブジェクトは、AdSelectionConfig の作成時に渡すことができます。

Kotlin

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

Java

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

アプリ インストール広告のフィルタリング

アプリ インストール広告のフィルタリングを使用すると、デバイスにすでにインストールされているアプリのインストール広告をフィルタできます。

このプロセスの最初のステップは、インストールされたパッケージをフィルタできる広告主を定義することです。これは、広告でターゲティングするアプリで行う必要があります。

Kotlin

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

Java

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

上記のコードを実行すると、渡された広告主は、入札の生成時に指定したインストール済みアプリを除外できます。このアプリのインストール ステータスへのアクセス権から広告主を削除する必要がある場合は、広告主の情報を削除して、このコードを再度実行します。

次のステップは、パブリッシャー アプリ内で広告フィルタを設定することです。パブリッシャー アプリ内で広告を配信する事業者（ほとんどの場合、サプライサイド SDK）は、除外するアプリ関連の広告に関する情報を使用して AdFilters オブジェクトを初期化する必要があります。

Kotlin

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

Java

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

デマンドサイドのパブリッシャーは、カスタム オーディエンス内に存在する広告に AdFilter を設定することもできます。

AdFilters は、新しい AdData オブジェクトのインスタンス化時に渡すこともできます。

Kotlin

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

Java

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

フリークエンシー キャップ フィルタリング

フリークエンシー キャップ フィルタリングにより、広告テクノロジーで広告の表示回数を制限できます。フリークエンシー キャップ フィルタリングは、広告の過剰な露出を減らし、特定の広告キャンペーンに対する代替広告の選択を最適化します。

フリークエンシー キャップ フィルタの主な構成要素は、広告イベントタイプと広告カウンタキーの 2 つです。使用できる広告イベントタイプは次のとおりです。

  • 落札: 落札イベントは、広告がオークションで落札されたことを示します。コンバージョン イベントは Protected Audience API によって自動的に更新され、デベロッパーが直接呼び出すことはできません。獲得データは、特定のカスタム オーディエンス内の広告にのみ表示されます。
  • インプレッション: reportImpression とは別に、デバイス上の呼び出し元（SSP または MMP）は updateAdCounterHistogram() を使用して、選択したコードのポイントでインプレッション イベントを呼び出します。インプレッション イベントは、特定の DSP に属するすべての広告に表示され、同じカスタム オーディエンスの広告に限定されません。
  • ビュー: デバイス上の呼び出し元（SSP または MMP）が、updateAdCounterHistogram() の呼び出しを使用して選択したコードでイベントを呼び出します。視聴イベントは、同じカスタム オーディエンス内の広告に限定されず、特定の DSP に属するすべての広告に表示されます。
  • クリック: デバイス上の呼び出し元（SSP または MMP）が、updateAdCounterHistogram() の呼び出しを使用して選択したコードでイベントを呼び出します。クリック イベントは、特定の DSP に属するすべての広告に表示され、同じカスタム オーディエンスの広告に限定されません。

パブリッシャー アプリでは、デバイス上に存在する SSP または MMP が広告イベントを呼び出します。updateAdCounterHistogram() が呼び出されると、フリークエンシー キャップ フィルタのカウンタが増分され、今後のオークションで、特定の広告に対するユーザーの接触に関する最新情報が使用されるようになります。広告イベントタイプは、対応するユーザー アクションに強制的に関連付けられるものではありません。これは、呼び出し元がイベント システムを構築する際に役立つガイドラインです。イベント時に広告カウンタをインクリメントするために、オンデバイス アクターは落札した広告オークションの広告選択 ID を提供します。

広告カウンタキーは、購入者の広告テクノロジーによって割り当てられた任意の 32 ビット符号付き整数であり、DSP で定義された特定の広告セットに対応します。広告カウンタキーは特定の DSP に属する広告に限定されるため、他の広告テクノロジーのヒストグラムと重複することなくキーを選択できます。広告カウンタキーは、DSP の広告全体または特定のカスタム オーディエンス内で DSP 固有の ID をインクリメントし、今後のオークションで広告を除外するために使用されます。

カウンタキーを使用すると、特定の購入者の広告テクノロジーによる他の広告とのインタラクションに基づいて、特定のユーザーにとって興味深い可能性が高い広告を優先できます。たとえば、広告オークションの落札、視聴、クリックで高いエンゲージメントを得た広告は、推定データポイントを表します。たとえば、左利きのゴルフクラブの広告は、ユーザーが右利きのゴルフクラブには興味がないことを示しています。左利き用広告に割り当てられたカウンタキーに設定されたフリークエンシー キャップ フィルタにより、右利き用クラブの広告が除外される可能性があります。

オークションでフリークエンシー キャップを使用するには、まず、次のように KeyedFrequencyCap オブジェクトを作成する必要があります。

Kotlin

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

Java

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

KeyedFrequencyCap オブジェクトを作成したら、それらを AdFilters オブジェクトに渡すことができます。

Kotlin

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

Java

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

AdFilters オブジェクトにフリークエンシー キャップ フィルタが入力されている場合は、カスタム オーディエンスの作成時に渡すことができます。

Kotlin

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

Java

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

フリークエンシー キャップ フィルタがカスタム オーディエンスに実装されると、SSP は必要なクリック、ビュー、インプレッション イベントを呼び出すことができます。

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

事前に設定したフリークエンシー キャップ フィルタの上限に達した広告は、オークションから除外されます。フィルタリングは、デバイス上のオークションで入札ロジックが実行される前と、入札とオークション サービスのオークションでペイロードが生成されるときに行われます。このツールキットを使用すると、広告テクノロジーがカスタム オーディエンス内のユーザーと広告とのインタラクションに基づいて柔軟に広告ターゲティングを行い、広告の過剰露出を最小限に抑えることができます。

ネットワーク呼び出しを使用しないコンテキスト広告のフィルタリング

デバイスにリマーケティングの需要がない場合は、ネットワーク呼び出しなしでコンテキスト広告の広告選択を実行できます。事前構築済みの URI と入札を含むコンテキスト広告のリストを使用すると、プラットフォームは入札ロジック、入札シグナル、スコアリング シグナルの取得をスキップできます。プラットフォームは、ビルド済みの URI を使用して、最も高い入札単価のコンテキスト広告を選択します。

レイテンシを改善するため、広告テクノロジーは、ネットワーク呼び出しなしの広告フィルタリング機能を備えたコンテキスト広告のみを含む広告選択フローを実行できます。これは、シグナルのスコアリングにビルド済み URI を使用することで実現されます。scoreAds の実装の一覧については、サポートされている事前構築済み URI のユースケースと名前のセクションをご覧ください。

ネットワーク呼び出しなしで広告選択を実行するには:

  1. 広告フィルタリングを設定する
  2. コンテキスト広告を作成する

  3. 次の内容で AdSelectionConfig オブジェクトを作成します。

    1. 購入者の空のリスト
    2. 最高入札単価を選択する事前構築済み URI
    3. コンテキスト広告
    4. スコアリング シグナルの空の URI。空の URI は、スコアリングに信頼できるシグナルの取得を使用しないことを示すために使用できます。
    Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUri(prebuiltURIScoringUri)
    .setCustomAudienceBuyers(Collections.emptyList())
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(buyerContextualAds)
    .setTrustedScoringSignalsUri(Uri.EMPTY)
    .build();

  4. 広告選択を実行:

    adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver);

ビルド済みの URI を使用して独自のレポート JavaScript を実行する

現在、プライバシー サンドボックス プラットフォームでは、ビルド済み URI に使用できる基本的なレポート JavaScript 実装のみを使用できます。低レイテンシの広告選択のために事前構築された URI を引き続き使用しながら、独自のレポート JavaScript を実行する場合は、広告選択とレポート実行の間に DecisionLogicUri をオーバーライドできます。

  1. 事前構築済みの URI を使用してコンテキスト広告の広告選択を実行する手順を実行します。

  2. レポートを実行する前に、AdSelectionConfigのコピーを作成してください

    adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
  // Replace <urlToFetchYourReportingJS> with your own URL:
  .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
  .build();

  3. インプレッション レポートを作成する

    // adSelectionId is from the result of the previous selectAds run
ReportImpressionRequest request = new ReportImpressionRequest(
  adSelectionId,
  adSelectionConfigWithYourReportingJS);
adSelectionManager.reportImpression(
  request,
  executor,
  outcomeReceiver);

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

ウォーターフォール メディエーションでは、複数のサードパーティ SDK（サードパーティ ネットワーク）をファースト パーティ SDK メディエーション ネットワークでオーケストレーションする必要があります。ウォーターフォール メディエーションは、オークションがデバイスで行われたか、入札 / オークション サービス（B&A）で行われたかにかかわらず、同じ方法で実行されます。

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

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

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

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

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 プロバイダは、オンデバイス オークションの場合は広告選択を実行する方法、B&A オークションの場合は B&A 説明機能のセクションを参照してください。（Single SSP のインプレッション レポートに沿って）広告のインプレッションをレポートします。

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

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

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

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

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

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

メディエーション SDK を、ファースト パーティの広告入札のライブ eCPM に基づいて、メディエーション チェーンに組み込むことができます。Protected Audience API では、広告の入札単価は不透明です。メディエーション 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 である場合は、このセクションに従います。ウォーターフォール メディエーションを実装する場合は、ウォーターフォール メディエーションのインプレッション レポートのセクションに記載されている手順に従ってください。

単一 SSP のインプレッション レポート

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

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

Java

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

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        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() コールバックは、インプレッション レポート URL が作成され、リクエストがスケジュール設定されたかどうかを示します。
  • 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 を取得します。この JavaScript には、インプレッション レポート URL を返すロジックが含まれています。
  • reportWin() JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。

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

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

入札およびオークション サービスのレポート

入札とオークション サービスで実行されるオークションでは、必要なすべてのレポート情報（広告インタラクション レポート用に生成された URL など）が、サーバーサイド オークションから暗号化されたレスポンスに含まれます。レスポンスが復号されると、適切な URL がプラットフォームに登録されるため、広告とインプレッションのレポートが上記と同じ手順で処理されます。

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

reportImpression() メソッドは、ベスト エフォートでレポートを完了できるように設計されています。

広告のインタラクションを報告する

Protected Audience では、レンダリングされた広告のより詳細なインタラクションをレポートできます。これには、閲覧時間、クリック数、カーソルを合わせた回数などのインタラクションや、収集可能なその他の有用な指標が含まれます。これらのレポートを受け取るプロセスには 2 つのステップが必要です。まず、購入者と販売者は、レポート JavaScript でこれらのレポートを受信するように登録する必要があります。その後、クライアントはこれらのイベントを報告する必要があります。

インタラクション イベントを受信するための登録

インタラクション イベントの登録は、購入者の reportWin() と販売者の reportResult() JavaScript 関数で、プラットフォームが提供する JavaScript 関数 registerAdBeacon を使用して行われます。イベント レポートを受け取るように登録するには、レポート用 JavaScript からプラットフォームの JavaScript 関数を呼び出すだけです。次のスニペットでは購入者の reportWin() を使用していますが、reportResult() にも同じ方法が適用されます。

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

インタラクション イベントのレポート

インプレッションを報告した後、クライアントは AdSelectionManager.reportInteraction() メソッドを使用して、以前に落札したバイサイド プラットフォームとセルサイド プラットフォームにインタラクションをレポートできます。広告イベントを報告するには:

  1. AdSelectionManager オブジェクトを初期化します。
  2. 広告選択 ID、インタラクション キー、インタラクション データ、レポート先を指定して、ReportInteractionRequest オブジェクトを作成します。
  3. request オブジェクトと、関連する Executor オブジェクトと OutcomeReceiver オブジェクトを指定して、非同期の reportInteraction() メソッドを呼び出します。
AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

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

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

  • 広告選択 ID: 以前に返された AdSelectionOutcome から取得された広告選択 ID。
  • インタラクション キー: 報告するアクションを説明する、クライアントによって定義された文字列キー。これは、レポート JavaScript 関数で販売者または購入者が登録したキーと一致している必要があります。
  • インタラクション データ: イベント レポートに含めてレポート サーバーに POST するデータを格納する文字列。
  • レポート先: イベントを購入者、販売者、またはその両方にレポートするかどうかを指定するビットマスク。これらのフラグはプラットフォームによって提供され、最終デスティネーション マスクはビット演算を使用して作成できます。1 つの宛先に報告するには、プラットフォームが提供するフラグを直接使用します。複数の宛先に報告するには、ビットごとの OR（|）を使用してフラグ値を組み合わせます。

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

  • onResult() コールバックは、レポート操作呼び出しが有効であることを示します。
  • onError() コールバックは、次の状況を通知します。
    • アプリがバックグラウンドで実行されているときに呼び出しが行われると、失敗の説明を含む IllegalStateException が返されます。
    • クライアントが reportInteraction() の呼び出しでスロットリングされている場合、LimitExceededException が返されます。
    • パッケージがプライバシー保護 API の呼び出しに登録されていない場合、SecurityException() が返されます。
    • アプリのレポート操作が selectAds() を呼び出したアプリと異なる場合は、IllegalStateException が返されます。
  • ユーザーがプライバシー サンドボックス API の有効化に同意していない場合、呼び出しは通知なく失敗します。

インタラクション レポートのエンドポイント

レポート インタラクション API は、セルサイド プラットフォームと落札したバイサイド プラットフォームが提供するエンドポイントに HTTPS POST リクエストを発行します。Protected Audience は、インタラクション キーをレポート用 JavaScript で宣言された URI と照合し、レポートされるインタラクションごとに各エンドポイントに POST リクエストを送信します。リクエストのコンテンツ タイプはテキストで、本文はインタラクション データです。

ベスト エフォート型のインタラクション レポート

reportInteraction() は、HTTP POST を介してベスト エフォートでレポートを完了するように設計されています。

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

カスタム オーディエンスを作成する際、アプリまたは 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_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_signal) {
    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_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_signals: generateBid のドキュメントをご覧ください。

出力:

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

registerAdBeacon()

function registerAdBeacon(
  beacons
)

入力パラメータ:

  • beacons: 操作キーとレポート URI の Key-Value ペアを含むオブジェクト。リストの形式は次のとおりです。

    let beacons = {
  'interaction_key': 'reporting_uri',
  'interaction_key': 'reporting_uri',
  ...
}
    • interaction_key: イベントを表す文字列。これは、後でイベント インタラクションを報告して、通知すべき reporting_uri を検索する際にプラットフォームによって使用されます。このキーは、購入者または販売者が登録する内容と、販売者が報告する内容と一致している必要があります。
    • reporting_uri: イベント レポートを受け取る URI。これは、報告するイベントタイプに固有のものです。イベントとともに報告されたデータを処理するには、POST リクエストを受け入れるようにする必要があります。

    例:

      let beacons = {
    'click': 'https://reporting.example.com/click_event',
    'view': 'https://reporting.example.com/view_event'
  }

広告選択のプリビルド URI

ビルド済み URI を使用すると、広告テクノロジーは AdSelectionConfig クラスと AdSelectionFromOutcomesConfig クラスで広告選択決定ロジック用の JavaScript 関数を指定できます。事前ビルドされた URI では、対応する JavaScript をダウンロードするためのネットワーク呼び出しは必要ありません。広告テクノロジーは、JavaScript をホストする登録済みドメインを設定することなく、事前構築済みの URI を使用できます。

事前構築された URI は、次の形式で作成されます。

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

プライバシー サンドボックス プラットフォームは、ランタイムでこの URI の情報を使用して JavaScript を提供します。

次の場合、IllegalArgumentException がスローされます。

  • 必須パラメータが URI に含まれていない
  • URI に認識できないパラメータがあります

サポートされているビルド済み URI のユースケースと名前

ユースケース 1: 広告の選択

ad-selection ユースケースのビルド済み URI は、selectAds(AdSelectionConfig) フローではサポートされていません。

ビルド済み URI 名: highest-bid-wins

この事前構築済み URI には、入札後に最も高い入札単価の広告を選択する JavaScript が用意されています。また、勝者の render_uri と bid を報告する基本的なレポート機能も用意されています。

必須パラメータ

reportingUrl: 落札した広告の render_uri と bid でパラメータ化されたベース レポート URL。

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

使用目的

ベース レポート URL が https://www.ssp.com/reporting の場合、事前構築された URI は次のようになります。

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

ユースケース 2: ad-selection-from-outcomes

ad-selection-from-outcomes ユースケースのビルド済み URI は、selectAds(AdSelectionFromOutcomesConfig) ワークフローをサポートします。

ビルド済み URI 名: waterfall-mediation-truncation

waterfall-mediation-truncation の事前構築済み URI には、ウォーターフォール メディエーションの切り捨てロジックを実装する JavaScript が用意されています。この JavaScript は、bid が bid floor 以上の場合、ファーストパーティ広告を返します。それ以外の場合は null を返します。

必須パラメータ

bidFloor: getSelectionSignals() で渡される入札単価の下限値のキー。メディエーション SDK の広告と比較されます。

使用目的

広告選択シグナルが {"bid_floor": 10} のような場合、ビルド済み URI は次のようになります。

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

テスト

Protected Audience API を簡単に使い始められるように、Kotlin と Java のサンプルアプリを作成しました。GitHub から入手できます。

前提条件

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

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

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

HTTPS エンドポイント

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

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

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

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

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

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

<application
  android:debuggable="true">

オーバーライドの使用方法の例については、GitHub の Protected Audience API サンプルアプリをご覧ください。

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

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

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 の Protected Audience API サンプルアプリをご覧ください。

非同期の 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 ファイルをご覧ください。

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

テストする機能

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

制限事項

次の表は Protected Audience API 処理に関する制限事項をまとめたものです。こちらに示した制限事項は、フィードバックに基づいて変更される可能性があります。開発中の機能については、リリースノートをご覧ください。

コンポーネント 制限の説明 制限値
カスタム オーディエンス（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

オークションあたりの販売者あたりのビーコンの最大数

10

イベントキーの最大サイズ

40 バイト

イベントデータの最大サイズ

64KB
広告 広告リストの最大サイズ 10 KB（コンテキストの場合、単一の CA の AdData すべてで共有）
URL 入力として使用される URL 文字列の最大長 未定
JavaScript 最長実行時間 インプレッション レポートの入札とスコアリングで 1 秒
最大使用メモリ 10 MB

バグと問題を報告する

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