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

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 が必要です。

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

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

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

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

TimeoutException がスローされた場合は、落札広告を見つけるための入札、スコアリング、または全体的な選択プロセス中にタイムアウトが発生した場合に発生します。

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

SecurityException がスローされた場合は、呼び出し元が承認されていないか、権限がリクエストされていない場合に発生します。
必須: AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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

getTestAdSelectionManager

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 services.」とともにスローされた場合は、広告選択サービスの内部エラーが原因です。

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 に関連付けられた広告で発生するすべての発生です。広告イベントがいつレポートされるかは保証されません。イベント レポートが遅れ、レポートがバッチ処理される可能性があります。

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

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

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

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

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

SecurityException がスローされた場合は、呼び出し元に権限がないか、権限がリクエストされていない場合に発生します。

イベントは、ベスト エフォートの試みとして最大 1 回報告されます。
必須: AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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

reportImpression

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

adSelectionId によって識別される広告選択によって選択された広告について、報告する新しいインプレッションがあることをサービスに通知します。インプレッションがいつレポートされるかは保証されません。インプレッション レポートが遅れて、レポートがバッチ処理される可能性があります。

落札した販売者のレポート URL を計算するために、サービスは ReportImpressionRequest.getAdSelectionConfig() にある AdSelectionConfig#getDecisionLogicUri() から販売者の JavaScript ロジックを取得します。次に、サービスは、販売者 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 を計算するために、サービスは落札購入者の JavaScript ロジックを取得します。このロジックは、購入者の CustomAudience.getBiddingLogicUri() を介して取得されます。次に、サービスは、購入者の JS にある reportWin という関数を実行し、オンデバイス シグナル、reportResult で計算された signals_for_buyer、および 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 } }; }

購入者と販売者は、登録して特定の広告イベントに関するレポートを受け取ることもできます。そのためには、購入者と販売者のそれぞれについて、reportWin と reportResult 内でプラットフォームが提供する registerAdBeacon 関数を呼び出します。

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

function registerAdBeacon(beacons)（beacons は文字列と文字列のペアの辞書）

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

購入者/販売者は、イベントを受け取るペアをすべて追加したら、registerAdBeacon(beacons) を呼び出すことができます。ここで、beacons はペアを追加した辞書の名前です。

registerAdBeacon は次のような場合に TypeError をスローします。

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

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

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

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

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 は Ads SDK によって提供され、AdSelectionFromOutcomesConfig オブジェクトは Binder 呼び出しを介して転送されます。このため、これらのオブジェクトの合計サイズには Android IPC の制限が適用されます。AdSelectionFromOutcomesConfig の転送に失敗すると、TransactionTooLargeException がスローされます。

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

入力 adSelectionFromOutcomesConfig には以下が含まれます。

  • Seller は AdTechIdentifier に登録されている必要があります。そうしないと、IllegalStateException がスローされます。
  • List of ad selection ids が存在し、同じアプリからの selectAds(AdSelectionConfig, Executor, OutcomeReceiver) 呼び出しで発生している必要があります。それ以外の場合、入力検証のための IllegalArgumentException は、広告選択 ID に違反しているリスティングを発生させます。
  • HTTPS または Ad Selection の事前ビルド済みスキーマに従うことができる Selection logic URI。

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

    ビルド済みの URI を使用して、selectOutcome の代わりに、必要な JavaScript の汎用的なビルド済みのロジックを置き換えることができます。このエンドポイントのビルド済み URI に従う必要があります。

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

    サポートされていないビルド済みの URI が渡されたか、サービスでビルド済みの URI 機能が無効になっている場合は、IllegalArgumentException がスローされます。

    サポートされている <name> と必要な <script-generation-parameters> については、AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri をご覧ください。

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

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

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 は Ads SDK によって提供され、AdSelectionConfig オブジェクトは Binder 呼び出しを介して転送されます。このため、これらのオブジェクトの合計サイズには Android IPC の制限が適用されます。AdSelectionConfig の転送に失敗すると、TransactionTooLargeException がスローされます。

入力 adSelectionConfig には、HTTPS スキーマまたは Ad Selection 事前ビルド済みスキーマに従うことができる Decision Logic Uri が含まれています。

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

ビルド済みの URI を使用して、scoreAds の代わりに、必要な JavaScript の汎用的なビルド済みのロジックを置き換えることができます。このエンドポイントのビルド済み URI に従う必要があります。

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

サポートされていないビルド済みの URI が渡された場合や、サービスでビルド済みの URI 機能が無効になっている場合は、IllegalArgumentException がスローされます。

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

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

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

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

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 で識別されるアプリまたはエンティティに API の使用権限がありません。
フォアグラウンド アクティビティのあるアプリからの呼び出しではない場合、outcomeReceiver を介して IllegalStateException が返されます。

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

他のすべての失敗の場合、outcomeReceiver は空の Object を返します。なお、ユーザーのプライバシーを保護するため、例外によって内部エラーが返却されることはありません。
必須: AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

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