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: カスタム オーディエンスの任意の名前または識別子。
別のインスタンスを指定して joinCustomAudience() を繰り返し呼び出している
CustomAudience は、既存の CustomAudience を
owner, buyer、および name パラメータが照合されます。プライバシー保護のため、API の結果で「作成」と「更新」は区別されません。
また、CustomAudience は次の必須パラメータを指定して作成する必要があります。
- 日次更新 URL: カスタム オーディエンスのユーザー入札シグナル、信頼できる入札データ、広告のレンダリング URL とメタデータを更新するために、バックグラウンドで毎日クエリされる HTTPS URL。
- 入札ロジック URL: 購入者の JavaScript 入札ロジックを取得するために、広告選択でクエリされる HTTPS URL。この JavaScript に必要な関数シグネチャを確認してください。
- 広告レンダリング ID: 購入者の広告テクノロジーが設定した任意の ID。これは B&A のペイロードを生成するための最適化。
CustomAudience オブジェクトのオプション パラメータには、次のものがあります。
- 有効化時刻: カスタム オーディエンスは、その有効化時刻後にのみ広告選択または日次更新に参加できます。使用をやめたユーザーのエンゲージメントなどに役立ちます。
- 有効期限: この将来の時刻以降に、カスタム オーディエンスがデバイスから削除されます。
- ユーザー入札シグナル: 購入者の入札ロジックの JavaScript が入札を生成するために広告選択プロセスで処理する、ユーザーが設定した言語や地域などのユーザー シグナルを含んだ JSON 文字列。この形式を使用することで、広告テクノロジー プラットフォームはプラットフォーム間でコードを再利用でき、JavaScript 関数での使用が簡単になります。
- 信頼できる入札データ: 信頼できる Key-Value から入札シグナルを取得する広告選択プロセス あります。
- 広告: 広告選択に参加する広告に対応する
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: 販売者の広告ネットワークに関する情報を取得するためにクエリされる HTTPS URL
JavaScript ロジック。
- HTTPS URL: 販売者の広告ネットワークの JavaScript ロジックを取得するためにクエリされます。 必要な関数シグネチャを確認する。
- ビルド済み URI: FLEDGE の広告選択形式に従います。
サポートされていない場合や形式が正しくない場合、
IllegalArgumentExceptionがスローされます。 渡されます。
- カスタム オーディエンス購入者: 販売者に広告選択プロセスに参加することを許可されている、購入者の広告ネットワークの識別子の完全なリスト。これらの購入者 ID は次に対応します:
CustomAudience.getBuyer()カスタム オーディエンスです。
以下のパラメータを指定して、さらに細かく広告選択をカスタマイズできます。
- 広告選択シグナル:
CustomAudience.getBiddingLogicUrl()から取得した購入者の入札ロジックの JavaScript で処理するシグナルを含む、文字列にシリアル化された JSON オブジェクト。 - 販売者シグナル:
AdSelectionConfig.getDecisionLogicUrl()から取得した販売者の JavaScript の判断ロジックで処理するシグナルを含む、文字列にシリアル化された JSON オブジェクト。 - 購入者ごとのシグナル:
CustomAudience.getBiddingLogicUrl()から取得した特定の購入者の入札ロジックの JavaScript で処理するシグナルを含む、文字列にシリアル化された JSON オブジェクトのマップ。シグナルは参加するカスタム オーディエンスの購入者フィールドで識別されます。 - コンテキスト広告: 直接収集された広告候補のコレクション Protected Audience 以外で行われたオークションでの購入者からの入札 決定します
広告が選択されると、結果、入札単価、シグナルが内部で保持される
レポートに使用できます。OutcomeReceiver.onResult() コールバックは、
次を含む AdSelectionOutcome:
AdData.getRenderUrl()から取得した、落札された広告のレンダリング URL。- デバイス ユーザーに固有の広告選択の ID。この ID は広告のインプレッションのレポートに使用されます。
無効な引数、タイムアウト、リソースの過剰消費などの理由で、広告選択が正常に完了できない場合、以下のような形で OutcomeReceiver.onError() コールバックが AdServicesException を示します。
- 広告選択が無効な引数を指定して開始された場合、
AdServicesExceptionにIllegalArgumentExceptionが原因として示されます。 - 他のすべてのエラーでは、
IllegalStateExceptionが設定されたAdServicesExceptionを原因として受け取ります。
コンテキスト広告
Protected Audience では、Protected Auction にコンテキスト広告を組み込むことができます。
コンテキスト広告は、広告テクノロジー サーバーで選択し、
デバイスを保護する必要がありますそれによりコンテキスト広告を
オークションに参加し、AdSelectionConfigを使用して入札が行われます。
デバイス広告と同じです（除外広告フィルタの利用資格など）。完了後
Protected Audience オークションが完了しました。次を呼び出す必要があります
reportImpression()。これにより、落札されたコンテキスト広告で reportWin() が呼び出されます。
インプレッション レポートと同じパターンで、
ダウンロードします各コンテキスト広告には、購入者、入札単価、レポート ロジックへのリンク、
広告メタデータが含まれます
アプリにコンテキスト広告をデプロイするには、ターゲット アプリで
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();
フリークエンシー キャップ フィルタリング
フリークエンシー キャップ フィルタリングにより、広告テクノロジーは広告が配信される回数を制限できる 表示されます。フリークエンシー キャップ フィルタリングにより、広告の過剰露出を低減し、代替広告を最適化 選択されます。
フリークエンシー キャップ フィルタの主な構成要素は、広告イベントタイプと 渡します。使用できる広告イベントタイプは次のとおりです。
- 落札（近日提供予定）: 落札イベントは、広告がオークションで落札されたことを示します。 落札イベントは Protected Audience API によって自動更新され、 デベロッパーが直接呼び出すことができます。落札データは、 特定のカスタムオーディエンスを 対象にできます
- インプレッション:
reportImpressionとは別の、デバイス上の発信者（SSP または MMP など）では、updateAdCounterHistogram()を使用してインプレッション イベントを 使用できます。インプレッション イベントは、 同じカスタム オーディエンス内の広告に限定されません。 - View: デバイス上のどこかの時点でイベントが、デバイス上の呼び出し元（SSP または MMP）によって呼び出されます。
updateAdCounterHistogram()の呼び出しを使用して選択したコードです。ビューイベントは 特定の DSP に属するすべての広告に表示され、同じ DSP の広告に限定されない カスタム オーディエンス - クリック: イベントのポイントで、デバイス上の呼び出し元（SSP または MMP）によってイベントが呼び出されます。
updateAdCounterHistogram()の呼び出しを使用して選択したコードです。クリック イベント 特定の DSP に属するすべての広告に表示され、 同じカスタムオーディエンスです
パブリッシャー アプリでは、デバイス上に存在している SSP または MMP から広告が呼び出されます。
できます。updateAdCounterHistogram() が呼び出されると、頻度のカウンタ
今後のオークションが最新の状態になるように、上限フィルタが
特定の広告に対するユーザーの露出に関する情報。この広告イベントタイプは
ユーザー操作と無関係に関連付けられており、ユーザーを
イベント システムを構造化します。イベント発生時に
イベントが発生すると、デバイス上のアクターは落札広告オークションの広告選択 ID を提供します。
広告カウンタキーは、購入者の広告によって割り当てられた任意の 32 ビット符号付き整数です DSP で定義された特定の広告セットに対応します。広告開始後 カウンタキーは特定の DSP に属する広告のみに制限され、 他の広告テクノロジーのヒストグラムと重ならないように選択されます。広告カウンタ キーは、DSP の広告全体や広告内で DSP 固有の識別子を 今後のオークションから広告を除外できます。
カウンタキーを活用して、価値の高い広告を優先的に配信 特定のサイトの他の広告に対するインタラクションに基づいて、 特定の購入者の広告テクノロジーを指定しますたとえば、過去 30 日間に 広告オークションを落札することによるエンゲージメント、視聴回数、クリック数は、推定される データポイントです。この点をさらに詳しく説明すると、左利きのゴルフクラブの広告です。 は、ユーザーが右利き用に関心がないことを示す可能性がある。 左利きの広告に割り当てられたカウンタキーに対してフリークエンシー キャップ フィルタを設定した場合、 右利きクラブの広告を除外できます
オークションでフリークエンシー キャップを使用するには、まず
次のように 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 を使用してシグナルをスコアリングすることで実現できます。詳しくは、サポートされている
「ビルド済み URI のユースケースと名前」セクション（scoreAds のリストを参照）
あります。
ネットワーク呼び出しなしで広告選択を実行するには:
- 広告フィルタを設定する
- コンテキスト広告を作成する
次の内容で
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 を実行する
現在、プライバシー サンドボックス プラットフォームには基本的なレポート JavaScript しかない
使用できる実装を示しています。独自のデータセンターを
JavaScript を報告しつつ、ビルド済み URI を使用して低レイテンシの広告を実現
広告選択と広告選択の間の 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（3P ネットワーク）が必要です。 ファースト パーティ 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
説明をご覧ください。広告を報告する方法
インプレッション（単一 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 を 。
reportWin()JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。
セルサイド プラットフォームのエンドポイント:
AdSelectionConfigオブジェクトで指定された判断ロジック URL を使用して、販売者の判断ロジックの JavaScript を取得します。reportResult()JavaScript 関数を呼び出します。この関数は、 販売者のインプレッション レポート URL を入力します。
入札とオークション サービスのレポート
入札とオークションでオークションサービスに必要なすべての広告枠と レポート情報（広告インタラクション レポート用に生成された URL など） サーバーサイド オークションから暗号化されたレスポンスに含まれる URL を返します。Google 復号されると、適切な URL がプラットフォームに登録されるため、 広告とインプレッションのレポートは、上記と同じ手順で行います。
ベスト エフォート型のインプレッション レポート
reportImpression() メソッドは、次の要素をベスト エフォートで完了するように設計されています。
レポート
広告のインタラクションをレポート
Protected Audience では、 レンダリングされます。これには、閲覧時間、クリック、カーソルを合わせたとき、 その他の有用な指標も確認できます。メッセージを受け取るプロセスは、 レポートを作成するには 2 つのステップが必要です。まず、購入者と販売者は レポート用の JavaScript で表示できます。その後、クライアントは次の操作を行う必要があります。 これらのイベントを報告します。
操作イベントを受信する登録
インタラクション イベントの登録は、購入者の reportWin() で行われます。
JavaScript 関数を使用する販売者の reportResult() JavaScript 関数
プラットフォーム（registerAdBeacon）から提供されます。登録して
イベント レポートを作成するには、レポートからプラットフォームの JavaScript 関数を呼び出すだけです。
使用できます。以下のスニペットでは購入者の reportWin() を使用していますが、同じです
アプローチは reportResult() に適用されます。
reportWin(
adSelectionSignals,
perBuyerSignals,
signalsForBuyer,
contextualSignals,
customAudienceSignals) {
...
// Calculate reportingUri, clickUri, viewUri, and hoverUri
registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});
return reportingUri;
}
インタラクション イベントの報告
クライアントはインプレッションを報告した後、そのインタラクションを
獲得したバイサイド プラットフォームとセルサイド プラットフォームを
AdSelectionManager.reportInteraction() メソッドを使用します。広告イベントを報告するには:
AdSelectionManagerオブジェクトを初期化します。- 広告選択 ID を使用して
ReportInteractionRequestオブジェクトを作成します。 操作キー、操作データ、レポート先 requestオブジェクトを使用して非同期reportInteraction()メソッドを呼び出す および関連する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: 以前に返された広告選択 ID
AdSelectionOutcome。 - インタラクション キー: アクションを説明する、クライアントが定義した文字列キー できます。これは、販売者が登録したキーと一致する必要があります。 必ず指定してください
- インタラクション データ: イベントに含めるデータを含む文字列 サーバーに POST で返されます。
- レポート送信先: イベントの送信が必要かどうかを指定するビットマスク
購入者、販売者、またはその両方に送信されますこれらのフラグは、
プラットフォームと最終デスティネーション マスクは、ビット演算を使用して
必要があります。1 つの送信先にレポートするには、
直接やり取りできます。複数の宛先にレポートを送信するには、ビット演算
OR（
|）でフラグの値を結合します。
非同期の reportInteraction() メソッドが OutcomeReceiver オブジェクトを使用して API 呼び出しの結果を通知します。
onResult()コールバックは、レポート インタラクションの呼び出しが有効であることを示します。onError()コールバックは、次の状況を通知します。- アプリがバックグラウンドで実行されているときに呼び出しが行われると、
失敗の説明を含む
IllegalStateExceptionが返されます。 - クライアントが
reportInteraction()の呼び出しをスロットリングされている場合、LimitExceededExceptionが返されます。 - パッケージが Privacy Preserving API を呼び出すように登録されていない場合は、
SecurityException()が返されます。 - アプリのインタラクションが、呼び出したアプリと異なっている場合
selectAds()の場合、IllegalStateExceptionが返されます。
- アプリがバックグラウンドで実行されているときに呼び出しが行われると、
失敗の説明を含む
- ユーザーがプライバシー サンドボックス API の有効化に同意しなかった場合、 通知なく失敗します
インタラクション レポートのエンドポイント
レポート インタラクション API は、 落札したバイサイド プラットフォームを 組み合わせることです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: 次の形式の JSON オブジェクト。var ad = { 'render_url': url, 'metadata': json_metadata };auction_signals, per_buyer_signals: オークションで指定された JSON オブジェクト configuration オブジェクト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 オブジェクト。 <ph type="x-smartling-placeholder">- </ph>
reporting_url: プラットフォームが販売者にインプレッションを通知するために使用する URL
registerAdBeacon()
function registerAdBeacon(
beacons
)
入力パラメータ:
beacons: 操作キーと操作キーの Key-Value ペアを含むオブジェクト レポート URI などです。リストの形式は次のとおりです。let beacons = { 'interaction_key': 'reporting_uri', 'interaction_key': 'reporting_uri', ... }interaction_key: イベントを表す文字列。これは Pod の 後でイベント インタラクションを報告する際に、 通知するreporting_uri。この鍵は次の間で一致する必要があります。 購入者または販売者が登録する内容、販売者が報告する内容が含まれます。reporting_uri: イベント レポートを受け取る URI。具体的であること 指定する必要がありますPOST リクエストを受け入れて イベントと一緒にレポートされたデータ。
例:
let beacons = { 'click': 'https://reporting.example.com/click_event', 'view': 'https://reporting.example.com/view_event' }
広告選択のビルド済み URI
事前構築された URI により、広告テクノロジーは広告の JavaScript 関数を指定できます。
AdSelectionConfig にある選択決定ロジックと、
AdSelectionFromOutcomesConfig クラス。ビルド済み URI はネットワークを必要としない
して、対応する JavaScript をダウンロードします。広告テクノロジーはビルド済み URI を使用できる
JavaScript をホストするための登録済みドメインを設定する必要はありません。
ビルド済み URI は、次の形式で構成されます。
ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>
プライバシー サンドボックス プラットフォームは、ここからの情報を使用する JavaScript を提供します。 URI を返します。
次の場合、IllegalArgumentException がスローされます。
- 必須パラメータが URI に存在しない
- URI に認識できないパラメータがあります
サポートされているビルド済み URI のユースケースと名前
ユースケース 1: 広告選択
ad-selection のユースケースでのビルド済み URI は、
selectAds(AdSelectionConfig) フロー。
ビルド済み URI 名: highest-bid-wins
この事前構築済み URI は、入札単価が最も高い広告を選択する JavaScript を提供します
最適化されますまた、基本的なレポート機能も備わっているため、
の勝者の render_uri と bid でした。
必須パラメータ
reportingUrl:
render_uri と落札広告の bid:
<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>
使用目的
ベース レポート URL が https://www.ssp.com/reporting の場合、事前構築済みの URL は
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
waterfall-mediation-truncation のビルド済み URI は、次の 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 の最大数 | 未定 | |
| オークションあたりの広告の最大数 | 未定 | |
| 初期接続タイムアウト | 5 秒 | |
| 接続読み取りタイムアウト | 5 秒 | |
AdSelection 全体の最長実行時間 |
10 秒 | |
AdSelection での CA あたりの入札の最長実行時間 |
5 秒 | |
AdSelection でのスコアリングの最長実行時間 |
5 秒 | |
AdSelection での購入者ごとの最長実行時間 |
未定 | |
| 広告選択 / 販売者 / 購入者ごとのシグナルの最大サイズ | 未定 | |
| 販売者 / 購入者のスクリプトの最大サイズ | 未定 | |
selectAds の最大呼び出しレート |
1 QPS | |
| インプレッション レポート | 広告選択が永続性から削除されるまでの最小時間 | 24 時間 |
| ストレージ広告選択の最大数 | 未定 | |
| レポート出力 URL の最大サイズ | 未定 | |
| インプレッション レポートの最長期間 | 未定 | |
| 通知呼び出しの再試行の最大回数 | 未定 | |
| 接続タイムアウト | 5 秒 | |
reportImpression 全体の最長実行時間 |
2 秒 | |
reportImpressions の最大呼び出しレート |
1 QPS | |
| イベント レポート | 各オークションの購入者ごとのビーコンの最大数 | 10 |
各オークションの販売者ごとのビーコンの最大数 |
10 |
|
イベントキーの最大サイズ |
40 バイト |
|
イベントデータの最大サイズ |
64KB |
|
| 広告 | 広告リストの最大サイズ | 10 KB（コンテキストの場合、単一の CA の AdData すべてで共有） |
| URL | 入力として使用される URL 文字列の最大長 | 未定 |
| JavaScript | 最長実行時間 | インプレッション レポートの入札とスコアリングで 1 秒 |
| 最大使用メモリ | 10 MB |
バグと問題を報告する
皆様からのフィードバックは、Android 版プライバシー サンドボックスに欠かせない要素です。問題が見つかった場合や Android 版プライバシー サンドボックスを改善するためのアイデアがありましたらお知らせください。
あなたへのおすすめ
- 注: JavaScript がオフになっている場合はリンクテキストが表示されます
- Protected Audience API を使用してカスタム オーディエンス ターゲティングをサポートする
- リリースノート
- Protected Audience: 統合ガイド