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 を使用して次のことを行う方法を説明します。
始める前に
始める前に、次のことを行ってください。
- Android 版プライバシー サンドボックス用に開発環境をセットアップします。
- サポート対象のデバイスにシステム イメージをインストールするか、Android 版プライバシー サンドボックスをサポートしているエミュレータをセットアップします。
ターミナルで、次の adb コマンドを使用して Protected Audience API へのアクセスを有効にします（デフォルトでは無効になっています）。
adb shell device_config put adservices ppapi_app_allow_list \"*\"アプリ マニフェストに
ACCESS_ADSERVICES_CUSTOM_AUDIENCE権限を含めます。<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />マニフェストの
<application>要素で広告サービス構成を参照します。<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />マニフェストで参照される広告サービス XML リソースを指定します（
res/xml/ad_services_config.xmlなど）。広告サービスの権限と SDK のアクセス制御の詳細をご覧ください。<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>デフォルトでは、Ad Selection API により、オークションやインプレッション レポート スクリプトが割り当てることのできるメモリの最大量に上限が適用されます。メモリ制限機能には、WebView バージョン 105.0.5195.58 以降が必要です。プラットフォームがバージョン チェックを実行し、これが満たされない場合
selectAdsAPI とreportImpressionAPI の呼び出しは失敗します。このセットアップ方法は 2 つあります。方法 1: 次の adb コマンドを実行してこのチェックを無効にします。
adb device_config put fledge_js_isolate_enforce_max_heap_size false方法 2: Google Play ストアから WebView ベータ版をインストールします。これは上記のバージョン以上である必要があります。
カスタム オーディエンスに参加する
カスタム オーディエンスは、広告主のアプリが決定した、共通の意図や関心を持つユーザーのグループを表します。アプリまたは SDK は、カスタム オーディエンスを使用して、特定のオーディエンス（ショッピング カートにアイテムを残しているユーザーなど）を示すことができます。カスタム オーディエンスの作成、またはそれへの参加を非同期で行うには、次の手順を実行します。
CustomAudienceManagerオブジェクトを初期化します。- 購入者のパッケージや適切な名前などの主要なパラメータを指定して、
CustomAudienceオブジェクトを作成します。次に、CustomAudienceオブジェクトを指定してJoinCustomAudienceRequestオブジェクトを初期化します。 - 非同期の
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 をその一意のパラメータに基づいて削除する手順は次のとおりです。
CustomAudienceManagerオブジェクトを初期化します。- カスタム オーディエンスの
buyerとnameを指定してLeaveCustomAudienceRequestを初期化します。これらの入力フィールドの詳細については、カスタム オーディエンスに参加するをご覧ください。 - 非同期の
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() メソッドを呼び出します。
AdSelectionManagerオブジェクトを初期化します。AdSelectionConfigオブジェクトを作成します。- 非同期の
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 の広告選択形式に従います。
IllegalArgumentExceptionは、サポートされていない、または不正な形式の事前ビルドされた URI が渡されるとスローされます。
- カスタム オーディエンス購入者: 販売者に広告選択プロセスに参加することを許可されている、購入者の広告ネットワークの識別子の完全なリスト。これらの購入者 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 オークションにコンテキスト広告を組み込むことができます。
コンテキスト広告は、広告テクノロジー サーバーで選択し、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 を設定することもできます。
新しい AdData オブジェクトをインスタンス化するときに、AdFilters を渡すこともできます。
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 固有の識別子を増やすために使用されます。
カウンタキーを使用すると、特定の購入者の広告テクノロジーの他の広告とのインタラクションに基づいて、特定のユーザーが関心を持つ可能性が高い広告を優先できます。たとえば、広告オークション、視聴回数、クリック数で高いエンゲージメントを獲得している広告は、推定データポイントを表します。この点をさらに詳しく説明すると、左利きのゴルフクラブの広告は、ユーザーが右利きのゴルフクラブに興味がないことを示唆しているとします。この場合、左利き用広告に割り当てられたカウンタキーにフリークエンシー キャップ フィルタを設定して、右利き用クラブの広告を除外できます。
オークションでフリークエンシー キャップを使用するには、まず次の 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 のユースケースと名前のセクションをご覧ください。
ネットワーク呼び出しを使用せずに広告選択を実行するには:
- 広告フィルタを設定する
- コンテキスト広告を作成する
次のように
AdSelectionConfigオブジェクトを作成します。- 購入者のリストが空の場合
- 最も高い入札単価を選択するための事前構築済みの URI
- コンテキスト広告
- スコアリング シグナルの空の 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();広告選択を実行:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
事前構築された URI を使用しながら独自のレポート用 JavaScript を実行する
現在、プライバシー サンドボックス プラットフォームでは、事前構築された URI で利用できる基本的なレポート JavaScript の実装のみが可能です。低レイテンシの広告選択のためにビルド済みの URI を使用しながら、独自のレポート JavaScript を実行したい場合は、広告選択とレポート実行の間で DecisionLogicUri をオーバーライドできます。
- 事前設定された URI を使用してコンテキスト広告の広告選択を実行する手順を実施する
レポートを実行する前に
AdSelectionConfigのコピーを作成してくださいadSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder() // Replace <urlToFetchYourReportingJS> with your own URL: .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>)) .build();インプレッション レポートを作成する
// 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 オークションの場合）をご覧ください。広告のインプレッションをレポートする方法（単一 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);
ウォーターフォール メディエーションをオーケストレートする
以下は、メディエーション プロセスの実行順序です。
- ファースト パーティ広告選択を実行します。
- メディエーション チェーンを反復処理します。サードパーティ ネットワークごとに次の操作を行います。
- ファースト パーティの
outcomeIdとサードパーティの SDK の入札下限を含むAdSelectionFromOutcomeConfigを作成します。 - 前のステップの構成で
selectAds()を呼び出します。 - 結果が空でない場合は、広告を返します。
- 現在の SDK ネットワーク アダプターの
selectAds()メソッドを呼び出します。結果が空でない場合は、広告を返します。
- ファースト パーティの
- チェーンで落札者が見つからなかった場合は、ファースト パーティ広告を返します。
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() メソッドを使用して、参加しているバイサイド プラットフォームとセルサイド プラットフォームにインプレッションをレポートできます。広告のインプレッションをレポートするには:
AdSelectionManagerオブジェクトを初期化します。- 広告選択 ID を指定して
ReportImpressionRequestオブジェクトを作成します。 - 非同期の
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 を取得します。これには、インプレッション レポート URL を返すロジックが含まれています。
reportWin()JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。
セルサイド プラットフォームのエンドポイント:
AdSelectionConfigオブジェクトで指定された判断ロジック URL を使用して、販売者の判断ロジックの JavaScript を取得します。reportResult()JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。
入札とオークション サービスのレポート
入札とオークション サービスで実行されるオークションでは、サーバーサイド オークションからの暗号化レスポンスに、広告インタラクション レポート用に生成された URL など、必要なすべてのレポート情報が含まれます。レスポンスが復号されると、適切な URL がプラットフォームに登録されるため、広告とインプレッションのレポートは上記と同じ手順で行われます。
ベスト エフォート型のインプレッション レポート
reportImpression() メソッドは、ベスト エフォートでレポートを完了するように設計されています。
広告のインタラクションをレポートする
Protected Audience では、レンダリングされた広告インタラクションについて、より詳細なレポートを作成できます。これには、閲覧時間、クリック数、カーソルを合わせるなどのインタラクションや、収集可能なその他の有用な指標が含まれます。これらのレポートを受信するプロセスには 2 つのステップが必要です。購入者と販売者は、まずレポート JavaScript でこれらのレポートを受け取るには、登録する必要があります。その後、クライアントはこれらのイベントを報告する必要があります。
インタラクション イベントを受信するための登録
インタラクション イベントの登録は、プラットフォーム（registerAdBeacon）が提供する JavaScript 関数を使用して、購入者の reportWin() と販売者の reportResult() の JavaScript 関数で行われます。イベント レポートを受け取るよう登録するには、レポートの JavaScript からプラットフォームの JavaScript 関数を呼び出します。次のスニペットでは購入者の reportWin() を使用していますが、同じアプローチが reportResult() にも当てはまります。
reportWin(
adSelectionSignals,
perBuyerSignals,
signalsForBuyer,
contextualSignals,
customAudienceSignals) {
...
// Calculate reportingUri, clickUri, viewUri, and hoverUri
registerAdBeacon("click", clickUri)
registerAdBeacon("view", viewUri)
registerAdBeacon("hover", hoverUri)
return reportingUrl;
}
インタラクション イベントの報告
インプレッションを報告した後、クライアントは AdSelectionManager.reportInteraction() メソッドを使用して、以前に登録されたバイサイド プラットフォームとセルサイド プラットフォームにインタラクションを報告できます。広告イベントを報告するには:
AdSelectionManagerオブジェクトを初期化します。- 広告選択 ID、インタラクション キー、インタラクション データ、レポート先を指定して、
ReportInteractionRequestオブジェクトを作成します。 - 非同期の
reportInteraction()メソッドを、requestオブジェクト、適切なExecutorオブジェクト、OutcomeReceiverオブジェクトを指定して呼び出します。
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。 - Interaction Key: 報告されるアクションを記述するクライアントによって定義される文字列キー。これは、レポート用 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:selectAdsAPI の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:sellerSignalsAdSelectionConfigAPI パラメータから読み取った JSON オブジェクト。trusted_scoring_signal:AdSelectionConfigAPI パラメータのadSelectionSignalsフィールドから読み取ります。contextual_signals, user_signals: JSON オブジェクト。現在は空のオブジェクトで渡されますが、今後のリリースでは、空でないオブジェクトが渡される予定です。これらの形式はプラットフォームでは適用されず、広告テクノロジーが管理します。per_buyer_signals:AdSelectionConfigAPI パラメータの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(
interaction_key,
reporting_uri
)
入力パラメータ:
interaction_key: イベントを表す文字列。これは、後でイベント操作を報告して、通知すべきreporting_uriを検索する際にプラットフォームによって使用されます。この鍵は、購入者または販売者が登録しているものと、販売者が報告しているものの間で一致している必要があります。reporting_uri: イベント レポートを受け取る URI。これは、報告するイベントタイプに固有のものです。イベントとともに報告されるデータを処理するために、POST リクエストを受け入れる必要があります。
広告選択の事前ビルド済み 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 ユースケースのビルド済み URI は、selectAds(AdSelectionFromOutcomesConfig) ワークフローをサポートします。
事前ビルド済みの URI 名: waterfall-mediation-truncation
事前ビルド済み URI waterfall-mediation-truncation には、ウォーターフォール メディエーションの切り捨てロジックを実装する 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 台セットアップする必要があります。
- 入札ロジックの JavaScript を提供する購入者のエンドポイント。
- 入札シグナルを提供するエンドポイント。
- 判断ロジックの JavaScript を提供する販売者のエンドポイント。
- スコアリング シグナルを提供するエンドポイント。
- 落札した購入者のインプレッション レポート用エンドポイント
- 販売者のインプレッション レポート用エンドポイント
- カスタム オーディエンスの日次更新を提供するエンドポイント。
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 のオーバーライドをセットアップするには、以下のサンプルコードのように次の操作を実行します。
AdSelectionManagerオブジェクトを初期化します。AdSelectionManagerオブジェクトからTestAdSelectionManagerへの参照を取得します。AdSelectionConfigオブジェクトを作成します。AdSelectionConfigオブジェクトと、オーバーライドとして使用する JavaScript を表すStringを指定して、AddAdSelectionOverrideRequestを作成します。- 非同期の
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 のオーバーライドをリセットするには:
- 非同期の
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 をオーバーライドする
- カスタム オーディエンスに参加する手順を実施します。
- オーバーライドとして使用する入札ロジックとデータに加え、オーバーライドするカスタム オーディエンスの購入者と名前を指定して、
AddCustomAudienceOverrideRequestを作成します。 - 非同期の
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 への参照があることを前提としています。
すべてのカスタム オーディエンスのオーバーライドをリセットするには:
- 非同期の
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 の最大数 | TBD | |
| オークションあたりの広告の最大数 | TBD | |
| 初期接続タイムアウト | 5 秒 | |
| 接続読み取りタイムアウト | 5 秒 | |
AdSelection 全体の最長実行時間 |
10 秒 | |
AdSelection での CA あたりの入札の最長実行時間 |
5 秒 | |
AdSelection でのスコアリングの最長実行時間 |
5 秒 | |
AdSelection での購入者ごとの最長実行時間 |
未定 | |
| 広告選択 / 販売者 / 購入者ごとのシグナルの最大サイズ | TBD | |
| 販売者 / 購入者のスクリプトの最大サイズ | TBD | |
selectAds の最大呼び出しレート |
1 QPS | |
| インプレッション レポート | 広告選択が永続性から削除されるまでの最小時間 | 24 時間 |
| ストレージ広告選択の最大数 | TBD | |
| レポート出力 URL の最大サイズ | TBD | |
| インプレッション レポートの最長期間 | TBD | |
| 通知呼び出しの再試行の最大回数 | TBD | |
| 接続タイムアウト | 5 秒 | |
reportImpression 全体の最長実行時間 |
2 秒 | |
reportImpressions の最大呼び出しレート |
1 QPS | |
| イベント レポート | 各オークションの購入者ごとのビーコンの最大数 | 10 |
オークションごとの販売者ごとのビーコンの最大数 |
10 |
|
イベントキーの最大サイズ |
40 バイト |
|
イベントデータの最大サイズ |
64KB |
|
| 広告 | 広告リストの最大サイズ | 10 KB（コンテキストの場合、単一の CA の AdData すべてで共有） |
| URL | 入力として使用される URL 文字列の最大長 | TBD |
| JavaScript | 最長実行時間 | インプレッション レポートの入札とスコアリングで 1 秒 |
| 最大使用メモリ | 10 MB |
バグと問題を報告する
皆様からのフィードバックは、Android 版プライバシー サンドボックスに欠かせない要素です。問題が見つかった場合や Android 版プライバシー サンドボックスを改善するためのアイデアがありましたらお知らせください。
あなたへのおすすめ
- 注: JavaScript がオフになっている場合はリンクテキストが表示されます
- Protected Audience API でカスタム オーディエンス ターゲティングをサポートする
- リリースノート
- Protected Audience: 統合ガイド