AdSelectionManager
public
class
AdSelectionManager
extends Object
java.lang.Object | |
↳ | android.adservices.adselection.AdSelectionManager |
AdSelection Manager は、アプリと広告 SDK が広告選択プロセスを実行し、インプレッションを報告するための API を提供します。
まとめ
継承されるメソッド | |
---|---|
パブリック メソッド
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
をスローします。
registerAdBeacon
が複数回呼び出される。このエラーが reportWin/reportResult でキャッチされると、元のペアのセットが登録されます。registerAdBeacon
の dict 引数は 1 つだけではありません。- 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
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
が返されます。
- アプリのマニフェストで適切な権限を宣言していない。
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 にすることはできません。 |