API レベル 34 で追加されました。
Ad Services Extensions 4 にも追加
概要: メソッド | 継承されるメソッド

AdSelectionManager

public class AdSelectionManager
extends Object

java.lang.Object
   ↳ android.adservices.adselection.AdSelectionManager

AdSelection Manager は、アプリと広告 SDK が広告選択プロセスを実行するための API を提供します。 レポートインプレッション数です。

概要

パブリック メソッド

static AdSelectionManager get(Context context)

AdSelectionManager のインスタンスを作成するためのファクトリ メソッド。

void getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

デバイスからカスタム オーディエンス データを収集します。

TestAdSelectionManager getTestAdSelectionManager()
void persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

サーバーサイドからの広告選択結果を保持します。

void reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

adSelectionId で識別される広告選択の実行。

void reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

adSelectionId で識別される広告選択の実行。

void selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

以前に実行された広告選択の結果から広告を選択します。

void selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

デバイスで広告選択プロセスを実行して、呼び出し元のリマーケティング広告を選択します 説明します。

void updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)

selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) の呼び出しによって以前に選択された広告のカウンタ ヒストグラムを更新します。

継承されるメソッド

パブリック メソッド

get

API レベル 34 で追加されました。
Ad Services Extensions 6 にも追加されました。 
public static AdSelectionManager get (Context context)

AdSelectionManager のインスタンスを作成するためのファクトリ メソッド。

パラメータ
context Context: 使用する Context この値が null になることはありません。
戻り値
AdSelectionManager AdSelectionManager インスタンス この値が null になることはありません。

getAdSelectionData

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

デバイスからカスタム オーディエンス データを収集します。送信する圧縮および暗号化された blob を返します。 オークションサーバーと通信します詳しくは、単価設定 オークション サービスに関する説明をご覧ください。

カスタム オーディエンス広告を収集するには、ad_render_idが必要です。

次の結果を処理する方法については、AdSelectionManager#persistAdSelectionResult をご覧ください。 広告選択は、この API によって生成された blob を使用してサーバーサイドで実行されます。

出力はレシーバーによって渡されます。レシーバーは、実行が成功すると GetAdSelectionDataOutcome を返すか、Exception に次のタイプを スローされた例外と対応するエラー メッセージ。

IllegalArgumentException がスローされた場合は、無効な入力引数が原因です 広告選択を実行するために受信した API。

IllegalStateException がエラー メッセージ「Failure of AdSelection」でスローされた場合 広告選択サービスの内部エラーが原因です。

TimeoutException がスローされた場合は、タイムアウトが発生した場合に発生します。 （入札、スコアリング、全体的な選択プロセスで）。

LimitExceededException がスローされた場合は、呼び出し元パッケージが レート制限を超えた場合に、スロットリングされます。

SecurityException がスローされた場合は、呼び出し元が承認されていない場合に発生します。 許可または拒否されます。
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE が必要です

パラメータ
request GetAdSelectionDataRequest: この値を null にすることはできません。
executor Executor: この値を null にすることはできません。 コールバック イベントとリスナー イベントは、この Executor: どのスレッドを表示するかを簡単に制御できます。 分析できますアプリケーションのメインスレッドを介してイベントをディスパッチするには、 作成する場合は、 Context.getMainExecutor()。 それ以外の場合は、適切なスレッドにディスパッチする Executor を提供します。
receiver OutcomeReceiver: この値を null にすることはできません。

getTestAdSelectionManager

API レベル 34 で追加されました。
Ad Services Extensions 4 にも追加 
public TestAdSelectionManager getTestAdSelectionManager ()

戻り値
TestAdSelectionManager この値が null になることはありません。

persistAdSelectionResult

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

サーバーサイドからの広告選択結果を保持します。詳しくは、単価設定 オークション サービスに関する説明

暗号化された blob を生成する方法については、AdSelectionManager#getAdSelectionData をご覧ください。 サーバーサイドで広告選択を実行する。

出力はレシーバーによって渡されます。レシーバーは AdSelectionOutcome を返します。 または Exception にスローされた例外の型と 対応するエラー メッセージが返されます。

IllegalArgumentException がスローされた場合は、無効な入力引数が原因です 広告選択を実行するために受信した API。

IllegalStateException がエラー メッセージ「Failure of AdSelection」でスローされた場合 広告選択サービスの内部エラーが原因です。

TimeoutException がスローされた場合は、タイムアウトが発生した場合に発生します。 （入札、スコアリング、全体的な選択プロセスで）。

LimitExceededException がスローされた場合は、呼び出し元パッケージが 許可されるレート制限を超えて、スロットリングされます。

SecurityException がスローされた場合は、呼び出し元が承認されていない場合に発生します。 許可または拒否されます。
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE が必要です

パラメータ
request PersistAdSelectionResultRequest: この値を null にすることはできません。
executor Executor: この値を null にすることはできません。 コールバック イベントとリスナー イベントは、この Executor: どのスレッドを表示するかを簡単に制御できます。 分析できますアプリケーションのメインスレッドを介してイベントをディスパッチするには、 作成する場合は、 Context.getMainExecutor()。 それ以外の場合は、適切なスレッドにディスパッチする Executor を提供します。
receiver OutcomeReceiver: この値を null にすることはできません。

reportEvent

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

adSelectionId で識別される広告選択の実行。広告イベントとは 指定された adSelectionId に関連付けられた広告に対して行われます。すべての Pod が 広告イベントが報告されるタイミングイベント レポートは遅れて、 バッチ処理されます。

サービスは ReportEventRequest#getKey() を使用して reportingUri を取得します。 （registerAdBeacon に登録されているもの）registerAdBeacon の詳細については、reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) のドキュメントをご覧ください。次に、Service で ReportEventRequest#getData() を POST リクエストのリクエスト本文に添付し、 リクエストを送信します。POST リクエストの本文の content-type は text/plain となり、データは charset=UTF-8 で送信されます。

出力はレシーバによって渡され、レシーバは空の Object を 成功した場合は、Exception にスローされた例外のタイプと 対応するエラー メッセージが返されます。

IllegalArgumentException がスローされた場合は、無効な入力引数が原因です 広告イベントを報告するために受け取った API

IllegalStateException がエラー メッセージ「Failure of AdSelection」でスローされた場合 広告選択サービスの内部エラーが原因です。

LimitExceededException がスローされた場合は、呼び出し元パッケージが 許可されるレート制限を超えて、スロットリングされます。

SecurityException がスローされた場合は、呼び出し元が承認されていない場合に発生します。 許可または拒否されます。

イベントは、ベスト エフォートとして最大 1 回報告されます。
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE が必要です

パラメータ
request ReportEventRequest: この値を null にすることはできません。
executor Executor: この値を null にすることはできません。
receiver OutcomeReceiver: この値を null にすることはできません。

reportImpression

API レベル 34 で追加されました。
Ad Services Extensions 4 にも追加 
public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

adSelectionId で識別される広告選択の実行。停止した場合、 表示されなくなります。インプレッションのレポート作成が遅れたり、 バッチ処理されます。

落札した販売者のレポート URL を計算するために、このサービスは販売者の JavaScript を取得します。 ReportImpressionRequest.getAdSelectionConfig() にある AdSelectionConfig#getDecisionLogicUri() のロジック。すると、サービスは Cloud Storage の 販売者 JS にある reportResult という関数を使用して、デバイス上のシグナルを 入力パラメータとして ReportImpressionRequest#getAdSelectionConfig() を指定します。

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 } }; }

落札した購入者のレポート URL を計算するには、落札した購入者の 購入者の CustomAudience.getBiddingLogicUri() を介して取得される JavaScript ロジック。次に、Service で 購入者 JS にある reportWin という関数の 1 つを実行し、 オンデバイスのシグナル、signals_for_buyer（reportResult で計算） ReportImpressionRequest#getAdSelectionConfig() のフィールドを入力パラメータとして使用することはできません。

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 } }; }

また、購入者と販売者は、登録することで特定の状況に関する特定のレポートが できます。これを行うには、プラットフォームが提供する registerAdBeacon 関数を呼び出します。 それぞれ購入者と販売者のそれぞれ reportWin と reportResult の内部に存在します。

registerBeacon の関数定義は次のとおりです。

function registerAdBeacon(beacons)。ここで、beacons は変換先の文字列の辞書です。 文字列ペア

購入者/販売者がレポートに関心がある広告イベントごとに、event_key: event_reporting_uri のペアを beacons 辞書に追加します。ここで、event_key はその特定のイベントの識別子です。この event_key は以下と一致する必要があります SDK が reportEvent(ReportEventRequest, Executor, OutcomeReceiver) を呼び出したときに ReportEventRequest#getKey() を返します。また 各 event_reporting_uri が適切に解析されて Uri に変換される必要があります。この SDK が reportEvent(ReportEventRequest, Executor, OutcomeReceiver) を呼び出したときに報告される Uri です。

イベントを受け取るすべてのペアリングを追加したら、購入者と販売者が以下を行います。 registerAdBeacon(beacons) を呼び出す（beacons は対象の辞書の名前） ペアを追加します。

次の場合、registerAdBeacon は TypeError をスローします。

  1. registerAdBeacon が複数回呼び出されています。このエラーが reportWin/reportResult を使用すると、元のペアのセットが登録されます。
  2. registerAdBeacon の辞書引数は 1 つだけではありません。
  3. 1 つの dict 引数の内容が、すべての String: String ペアとは限りません。

出力は receiver によって渡され、空の Object が返されます。 または Exception にスローされた例外の型と 対応するエラー メッセージが返されます。

IllegalArgumentException がスローされた場合は、無効な入力引数が原因です インプレッションをレポートするために受信します

IllegalStateException がエラー メッセージ「Failure of AdSelection」でスローされた場合 広告選択サービスの内部エラーが原因です。

LimitExceededException がスローされた場合は、呼び出し元パッケージが レート制限を超えた場合に、スロットリングされます。

SecurityException がスローされた場合は、呼び出し元が承認されていない場合に発生します。 許可または拒否されます。

インプレッション数は、ベスト エフォートとして最大 1 回記録されます。
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE が必要です

パラメータ
request ReportImpressionRequest: この値を null にすることはできません。
executor Executor: この値を null にすることはできません。
receiver OutcomeReceiver: この値を null にすることはできません。

selectAds

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

以前に実行された広告選択の結果から広告を選択します。

入力 adSelectionFromOutcomesConfig は Google 広告 SDK によって提供され、AdSelectionFromOutcomesConfig オブジェクトはバインダー呼び出しを介して転送されます。このため、 これらのオブジェクトの合計サイズは Android IPC の制限を受けます。移行の失敗 AdSelectionFromOutcomesConfig は TransactionTooLargeException をスローします。

出力はレシーバーによって渡されます。レシーバーは AdSelectionOutcome を返します。 または Exception にスローされた例外の型と 対応するエラー メッセージが返されます。

入力 adSelectionFromOutcomesConfig には次のものが含まれます。

  • Seller は登録済みの AdTechIdentifier である必要があります。それ以外の場合は、IllegalStateException がスローされます。
  • List of ad selection ids が存在し、同じアプリからの selectAds(AdSelectionConfig, Executor, OutcomeReceiver) 呼び出しから取得される必要があります。それ以外の場合は 入力検証で IllegalArgumentException を実行すると、違反しているリスティングが表示されます。 選択されます。
  • Selection logic URI: HTTPS または広告選択（事前構築済み）に従う 説明します。

    URI が HTTPS スキーマに従っている場合、ホストは seller と一致する必要があります。 そうしないと、IllegalArgumentException がスローされます。

    事前構築済み URI は、必要なリソースの代わりに汎用の事前構築済みロジックを selectOutcome の JavaScript。次のエンドポイントの事前構築済み URI が続きます。

    • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

    サポートされていないビルド済み URI が渡された場合、またはビルド済み URI 機能が サービスに対して IllegalArgumentException がスローされます。

    サポート対象については、AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri をご覧ください <name>。<script-generation-parameters> が必要です。

IllegalArgumentException がスローされた場合は、無効な入力引数が原因です 広告選択を実行するために受信した API。

IllegalStateException がエラー メッセージ「Failure of AdSelection」でスローされた場合 広告選択サービスの内部エラーが原因です。

TimeoutException がスローされた場合は、タイムアウトが発生した場合に発生します。 （入札、スコアリング、全体的な選択プロセスで）。

LimitExceededException がスローされた場合は、呼び出し元パッケージが 許可されるレート制限を超えて、スロットリングされます。

SecurityException がスローされた場合は、呼び出し元が承認されていない場合に発生します。 許可または拒否されます。
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE が必要です

パラメータ
adSelectionFromOutcomesConfig AdSelectionFromOutcomesConfig: この値を null にすることはできません。
executor Executor: この値を null にすることはできません。 コールバック イベントとリスナー イベントは、この Executor: どのスレッドを表示するかを簡単に制御できます。 分析できますアプリケーションのメインスレッドを介してイベントをディスパッチするには、 作成する場合は、 Context.getMainExecutor()。 それ以外の場合は、適切なスレッドにディスパッチする Executor を提供します。
receiver OutcomeReceiver: この値を null にすることはできません。

selectAds

API レベル 34 で追加されました 
public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

デバイスで広告選択プロセスを実行して、呼び出し元のリマーケティング広告を選択します 説明します。

入力 adSelectionConfig は Google 広告 SDK によって提供され、AdSelectionConfig オブジェクトはバインダー呼び出しを介して転送されます。このために、合計サイズは Android IPC の制限が適用されます。AdSelectionConfig の転送に失敗すると、TransactionTooLargeException がスローされます。

入力 adSelectionConfig に、その後に続く Decision Logic Uri が含まれている HTTPS または広告選択の事前構築済みスキーマです。

URI が HTTPS スキーマに従っている場合、ホストは seller と一致する必要があります。それ以外の場合は IllegalArgumentException がスローされます。

事前構築済み URI は、必要なリソースの代わりに汎用の事前構築済みロジックを scoreAds の JavaScript。次のエンドポイントの事前構築済み URI が続きます。

  • ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

サポートされていないビルド済み URI が渡された場合、またはビルド済み URI 機能が サービスに対して IllegalArgumentException がスローされます。

サポートされている <name> と、AdSelectionConfig.Builder#setDecisionLogicUri をご覧ください <script-generation-parameters> が必要です。

出力はレシーバーによって渡されます。レシーバーは AdSelectionOutcome を返します。 または Exception にスローされた例外の型と 対応するエラー メッセージが返されます。

IllegalArgumentException がスローされた場合は、無効な入力引数が原因です 広告選択を実行するために受信した API。

IllegalStateException がエラー メッセージ「Failure of AdSelection」でスローされた場合 広告選択サービスの内部エラーが原因です。

TimeoutException がスローされた場合は、タイムアウトが発生した場合に発生します。 （入札、スコアリング、全体的な選択プロセスで）。

LimitExceededException がスローされた場合は、呼び出し元パッケージが 許可されるレート制限を超えて、スロットリングされます。

SecurityException がスローされた場合は、呼び出し元が承認されていない場合に発生します。 許可または拒否されます。
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE が必要です

パラメータ
adSelectionConfig AdSelectionConfig: この値を null にすることはできません。
executor Executor: この値を null にすることはできません。 コールバック イベントとリスナー イベントは、この Executor: どのスレッドを表示するかを簡単に制御できます。 分析できますアプリケーションのメインスレッドを介してイベントをディスパッチするには、 作成する場合は、 Context.getMainExecutor()。 それ以外の場合は、適切なスレッドにディスパッチする Executor を提供します。
receiver OutcomeReceiver: この値を null にすることはできません。

updateAdCounterHistogram

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) の呼び出しによって以前に選択された広告のカウンタ ヒストグラムを更新します。

カウンタ ヒストグラムは広告選択で使用され、フリークエンシー キャップ フィルタリングを有効にするよう指示します。 フリークエンシー キャップに達しているか超過している広告が 入札プロセスも考慮します

カウンタ ヒストグラムは、同じ呼び出し元アプリから FLEDGE 広告選択への最近の呼び出しによって返された特定の adSelectionId で指定された広告についてのみ更新できます。

次の場合、outcomeReceiver を介して SecurityException が返されます。

  1. アプリのマニフェストで正しい権限が宣言されていない
  2. callerAdTechIdentifier で特定されるアプリまたはエンティティは承認されていません 確認する必要があります
で確認できます。 呼び出しを行うと、outcomeReceiver を介して IllegalStateException が返されます。 フォアグラウンド アクティビティがあるアプリからのものでない場合。

呼び出しを行うと、outcomeReceiver を介して LimitExceededException が返されます。 呼び出し側のアプリの API スロットルを超過します。

それ以外の場合は、outcomeReceiver から空の Object が返されます。なお、ユーザーのプライバシーを保護するため、内部エラーが 発生します。
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE が必要です

パラメータ
updateAdCounterHistogramRequest UpdateAdCounterHistogramRequest: この値を null にすることはできません。
executor Executor: この値を null にすることはできません。 コールバック イベントとリスナー イベントは、この Executor: どのスレッドを表示するかを簡単に制御できます。 分析できますアプリケーションのメインスレッドを介してイベントをディスパッチするには、 作成する場合は、 Context.getMainExecutor()。 それ以外の場合は、適切なスレッドにディスパッチする Executor を提供します。
outcomeReceiver OutcomeReceiver: この値を null にすることはできません。