Android 版 FLEDGE のデベロッパー ガイド

Android 版プライバシー サンドボックスのドキュメントをご覧になる際は、[デベロッパー プレビュー] または [ベータ版] ボタンで対象のプログラム バージョンを選択してください（手順が異なる場合があります）。

フィードバックを送信

Android 版 FLEDGE には、Custom Audience API と Ad Selection API が用意されています。これらの API を使用することで、広告テクノロジー プラットフォームと広告主は、アプリ間の識別子の共有と、ユーザーのアプリ操作情報の第三者との共有を制限しながら、過去のアプリ エンゲージメントに基づくカスタマイズされた広告を配信できます。

Custom Audience API は、共通の意図を持ったユーザーのグループを表す「カスタム オーディエンス」の抽象化を主な役割としています。広告主は、ユーザーをカスタム オーディエンスに登録し、関連性の高い広告を関連付けることができます。この情報はローカルに保存され、広告主の入札、広告フィルタリング、広告レンダリングへの情報提供に使用されます。

Ad Selection API は、複数のデベロッパーがカスタム オーディエンスのオークションをローカルで実行することを可能にするフレームワークを提供します。これを実現するために、システムでは、カスタム オーディエンスに関連付けられた関連性の高い広告を検討し、広告テクノロジー プラットフォームがデバイスに返す広告に追加の処理を行います。

広告テクノロジー プラットフォームでは、これらの API を統合することで、ユーザーのプライバシーを保護するリマーケティングを実装できます。今後のリリースでは、アプリ インストール広告など、他のユースケースもサポートされる予定です。Android 版 FLEDGE の詳細については、設計案をご覧ください。

このデベロッパー ガイドでは、Android 版 FLEDGE を使用して以下を行う方法を説明します。

1. カスタム オーディエンスの管理
2. デバイスでの広告選択のセットアップと実行
3. 広告のインプレッションのレポート

準備

始める前に、次のことを行ってください。

1. Android 版プライバシー サンドボックス用に開発環境をセットアップします。
2. サポート対象のデバイスにシステム イメージをインストールするか、Android 版プライバシー サンドボックスのサポートを含むエミュレータをセットアップします。

3. ターミナルで、次の adb コマンドを使用して FLEDGE API へのアクセスを有効にします（デフォルトでは無効になっています）。

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. アプリ マニフェストに ACCESS_ADSERVICES_CUSTOM_AUDIENCE 権限を含めます。

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

5. マニフェストの <application> 要素で広告サービス構成を参照します。

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

6. マニフェストで参照される広告サービス XML リソースを指定します（res/xml/ad_services_config.xml など）。広告サービスの権限と SDK のアクセス制御の詳細をご覧ください。

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

7. デフォルトでは、Ad Selection API により、オークションやインプレッション レポート スクリプトが割り当てることのできるメモリの最大量に上限が適用されます。メモリ制限機能には、WebView バージョン 105.0.5195.58 以降が必要です。プラットフォームがバージョン チェックが適用して、これが満たされない場合に selectAds API と reportImpression API の呼び出しが失敗します。これをセットアップするには、2 つの方法があります。

   • 方法 1: 次の adb コマンドを実行してこのチェックを無効にします。

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • 方法 2: Google Play ストアから WebView ベータ版をインストールします。これは、上記のバージョン以上である必要があります。

カスタム オーディエンスに参加する

カスタム オーディエンスは、広告主のアプリが決定した、共通の意図や関心を持つユーザーのグループを表します。アプリまたは SDK は、カスタム オーディエンスを使用して、特定のオーディエンス（ショッピング カートにアイテムを残しているユーザーなど）を示すことができます。カスタム オーディエンスの作成、またはそれへの参加を非同期で行うには、次の手順を実行します。

1. CustomAudienceManager オブジェクトを初期化します。
2. 購入者のパッケージや適切な名前などの主要なパラメータを指定して、CustomAudience オブジェクトを作成します。次に、CustomAudience オブジェクトを指定して JoinCustomAudienceRequest オブジェクトを初期化します。
3. 非同期の joinCustomAudience() を、JoinCustomAudienceRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

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)

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 に必要な関数のシグネチャを確認してください。

CustomAudience オブジェクトのオプション パラメータには、次のものがあります。

• 有効化時刻: カスタム オーディエンスは、その有効化時刻後にのみ広告選択または日次更新に参加できます。使用をやめたユーザーのエンゲージメントなどに役立ちます。
• 有効期限: この未来の時刻以降に、カスタム オーディエンスがデバイスから削除されます。
• ユーザー入札シグナル: 購入者の入札ロジックの JavaScript が入札を生成するために広告選択プロセスで処理する、ユーザーが設定した言語や地域などのユーザー シグナルを含んだ JSON 文字列。この形式を使用することで、広告テクノロジー プラットフォームはプラットフォーム間でコードを再利用でき、JavaScript 関数での使用が簡単になります。
• 信頼できる入札データ: 信頼できる Key-Value サーバーから入札シグナルを取得する広告選択プロセスで使用される HTTPS URL と文字列のリスト。
• 広告: 広告選択に参加する広告に対応する AdData オブジェクトのリスト。各 AdData オブジェクトは、次の要素で構成されます。
  • レンダリング URL: 最終的な広告を表示するためにクエリされる HTTPS URL。
  • メタデータ: 広告選択プロセスで購入者の入札ロジックで処理する情報を含む、文字列にシリアル化された JSON オブジェクト。

以下に、CustomAudience オブジェクトのインスタンス化の例を示します。

// 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()

// 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() の結果を処理する例を次に示します。

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

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 をその一意のパラメータに基づいて削除する手順は次のとおりです。

1. CustomAudienceManager オブジェクトを初期化します。
2. カスタム オーディエンスの buyer、name を指定して LeaveCustomAudienceRequest を初期化します。これらの入力フィールドの詳細については、カスタム オーディエンスに参加するをご覧ください。
3. 非同期の leaveCustomAudience() メソッドを、LeaveCustomAudienceRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() の呼び出しと同様に、OutcomeReceiver が API 呼び出しの終了を通知します。プライバシー保護のため、エラー結果で内部エラーと無効な引数とは区別されません。一致するカスタム オーディエンスが正常に削除されたかどうかにかかわらず、API 呼び出しが完了すると onResult() コールバックが呼び出されます。

広告選択を実行する

FLEDGE を使用して広告を選択するには、次のようにして selectAds() メソッドを呼び出します。

1. AdSelectionManager オブジェクトを初期化します。
2. AdSelectionConfig オブジェクトを作成します。
3. 非同期の selectAds() メソッドを、AdSelectionConfig オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

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)
                .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver)

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)
                .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver);

selectAds() メソッドには AdSelectionConfig の入力が必要です。これには、次の必須パラメータを指定する必要があります。

• 販売者: 広告選択を開始する、販売者の広告ネットワークの識別子。
• 判断ロジック URL: 販売者の広告ネットワークの JavaScript ロジックを取得するためにクエリされる HTTPS URL。この JavaScript に必要な関数のシグネチャを確認してください。
• カスタム オーディエンス購入者: 販売者に広告選択プロセスに参加することを許可されている、購入者の広告ネットワークの識別子の完全なリスト。これらの購入者の識別子は、参加するカスタム オーディエンスの CustomAudience.getBuyer() に対応しています。

以下のパラメータを指定して、さらに細かく広告選択をカスタマイズできます。

• 広告選択シグナル: CustomAudience.getBiddingLogicUrl() から取得した購入者の入札ロジックの JavaScript で処理するシグナルを含む、文字列にシリアル化された JSON オブジェクト。
• 販売者シグナル: AdSelectionConfig.getDecisionLogicUrl() から取得した販売者の JavaScript の判断ロジックで処理するシグナルを含む、文字列にシリアル化された JSON オブジェクト。
• 購入者ごとのシグナル: CustomAudience.getBiddingLogicUrl() から取得した特定の購入者の入札ロジックの JavaScript で処理するシグナルを含む、文字列にシリアル化された JSON オブジェクトのマップ。シグナルは参加するカスタム オーディエンスの購入者のフィールドで識別されます。

広告が選択されると、結果、入札単価、シグナルは、以降のレポート用に内部的に保持されます。OutcomeReceiver.onResult() コールバックから、次を含む AdSelectionOutcome が返されます。

• AdData.getRenderUrl() から取得した、落札された広告のレンダリング URL。
• デバイス ユーザーに固有の広告選択の ID。この ID は、広告のインプレッションのレポートに使用されます。

広告選択が、無効な引数、タイムアウト、リソースの過剰消費などの理由で正常に完了できない場合、以下の挙動で OutcomeReceiver.onError() コールバックが AdServicesException を与えます。

• 広告選択が無効な引数を指定して開始された場合、AdServicesException に IllegalArgumentException が原因として示されます。
• 他のすべてのエラーでは、IllegalStateException が設定された AdServicesException を原因として受け取ります。

広告のインプレッションのレポート

広告選択ワークフローで落札する広告が選択されると、AdSelectionManager.reportImpression() メソッドを使用して、参加しているバイサイド プラットフォームとセルサイド プラットフォームにインプレッションをレポートできます。広告のインプレッションをレポートするには:

1. AdSelectionManager オブジェクトを初期化します。
2. 広告選択 ID を指定して ReportImpressionRequest オブジェクトを作成します。
3. 非同期の reportImpression() メソッドを、AdSelectionConfig オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig);
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

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() コールバックは、広告選択が完了したかどうかを示します。
• onError() コールバックは、次の状況を通知します。
  • 呼び出しが無効な入力引数を指定して初期化されている場合、AdServicesException は IllegalArgumentException を原因として示します。
  • 他のすべてのエラーでは、IllegalStateException が設定された AdServicesException を原因として受け取ります。

インプレッション レポートのエンドポイント

レポート インプレッション API は、セルサイド プラットフォームが提供するエンドポイントと、落札したバイサイド プラットフォームが提供するエンドポイントに、HTTPS GET リクエストを発行します。

バイサイド プラットフォームのエンドポイント:

• この API は、カスタム オーディエンスで指定された入札ロジック URL を使用して、購入者の入札ロジックの JavaScript を取得します。
• reportResult() JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。

セルサイド プラットフォーム エンドポイント:

• AdSelectionConfig オブジェクトで指定された判断ロジック URL を使用して、販売者の判断ロジックの JavaScript を取得します。
• reportWin() JavaScript 関数を呼び出します。この関数は、購入者のインプレッション レポート URL を返します。

ベスト エフォート型のインプレッション レポート

reportImpression() は、ベスト エフォートでレポートを行うように設計されています。

毎日のバックグラウンド更新

カスタム オーディエンスを作成する際、アプリまたは 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 には次の関数が含まれます。

• generateBid()
• reportResult()

販売者提供の JavaScript は、広告選択 API の AdSelectionConfig パラメータで指定された判断ロジック URL から取得されます。返される JavaScript には次の関数が含まれます。

• scoreAd()
• reportWin()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_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_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: selectAds API の 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: sellerSignals AdSelectionConfig API パラメータから読み取った JSON オブジェクト。

• trusted_scoring_signal: AdSelectionConfig API パラメータの adSelectionSignals フィールドから読み取ります。

• contextual_signals, user_signals: JSON オブジェクト。現在は空のオブジェクトで渡されますが、今後のリリースでは、空でないオブジェクトが渡される予定です。これらの形式はプラットフォームでは適用されず、広告テクノロジーが管理します。

• per_buyer_signals: AdSelectionConfig API パラメータの perBuyerSignal マップから現在のカスタム オーディエンス購入者をキーに使用して読み取られた JSON オブジェクト。マップに指定された購入者のエントリが含まれていない場合は空になります。

出力:

• score: この広告のスコア値を表す浮動小数点値。
• status: 次の整数値。
  • 0: 実行が成功した場合。
  • 1: customAudienceSignals が無効の場合。
  • 2: AdSelectionConfig が無効な場合。
  • 3: 他のシグナルのいずれかが無効な場合。
  • ゼロ以外の値があるとプロセスが失敗し、値によってスローされる例外のタイプが決まります

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

テスト

FLEDGE を簡単に始められるように、Kotlin と Java のサンプルアプリを作成しました。GitHub から入手できます。

前提条件

FLEDGE は、広告選択とインプレッション レポートの際、JavaScript を必要とします。この JavaScript をテスト環境で提供する方法は 2 つあります。

• JavaScript を返す必要な HTTPS エンドポイントを使用してサーバーを稼働させる
• ローカルソースから必要なコードを提供することでリモート取得をオーバーライドする

いずれの方法でも、インプレッション レポートを処理するために HTTPS エンドポイントをセットアップする必要があります。

HTTPS エンドポイント

広告選択とインプレッション レポートをテストするには、テストデバイスまたはエミュレータがアクセスできる HTTPS エンドポイントを 7 台セットアップする必要があります。

1. 入札ロジックの JavaScript を提供する購入者のエンドポイント。
2. 入札シグナルを提供するエンドポイント。
3. 判断ロジックの JavaScript を提供する販売者のエンドポイント。
4. スコアリング シグナルを提供するエンドポイント。
5. 落札した購入者のインプレッション レポート用エンドポイント
6. 販売者のインプレッション レポート用エンドポイント
7. カスタム オーディエンスの日次更新を提供するエンドポイント。

GitHub リポジトリにテスト用の基本的な JavaScript コードを用意しています。サポートされているモックまたはマイクロサービスのプラットフォームにデプロイ可能な OpenAPI サービス定義も含まれています。詳しくは、プロジェクトの README ファイルをご覧ください。

JavaScript のリモート取得をオーバーライドする

この機能は、エンドツーエンドのテストに使用することを目的としています。リモート取得をオーバーライドするには、開発者向けオプションを有効にして、アプリをデバッグモードで実行する必要があります。

アプリのデバッグモードを有効にするには、AndroidManifest.xml の application 属性に次の行を追加します。

<application
  android:debuggable="true">

オーバーライドの使用方法の例については、GitHub の FLEDGE サンプルアプリをご覧ください。

入札、スコア決定、レポートなどの広告選択ルーチンを処理するために、独自のカスタム JavaScript を追加する必要があります。必要なリクエストをすべて処理する基本的な JavaScript コードの例が、GitHub リポジトリにあります。FLEDGE サンプルアプリは、そのファイルからコードを読み取り、オーバーライドとして使用するために準備する方法を示しています。

セルサイドとバイサイドの JavaScript 取得を個別にオーバーライドすることもできますが、オーバーライドしない JavaScript を提供するには HTTPS エンドポイントが必要となります。このようなケースに対応するサーバーのセットアップ方法については、README をご覧ください。

パッケージ取得元の JavaScript 取得をオーバーライドできるのは、パッケージが所有しているカスタム オーディエンスのみです。

セルサイドの JavaScript をオーバーライドする

セルサイドの JavaScript のオーバーライドをセットアップするには、以下のサンプルコードのようにします。

1. AdSelectionManager オブジェクトを初期化します。
2. AdSelectionManager オブジェクトから TestAdSelectionManager への参照を取得します。
3. AdSelectionConfig オブジェクトを作成します。
4. AdSelectionConfig オブジェクトと、オーバーライドとして使用する JavaScript を表す String を指定して、AddAdSelectionOverrideRequest を作成します。
5. 非同期の overrideAdSelectionConfigRemoteInfo() メソッドを、AddAdSelectionOverrideRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

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)

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 の FLEDGE サンプルアプリをご覧ください。

非同期の overrideAdSelectionConfigRemoteInfo() メソッドが OutcomeReceiver オブジェクトを使用して API 呼び出しの結果を通知します。

onResult() コールバックは、オーバーライドが正常に適用されたことを示します。selectAds() に対する以降の呼び出しでは、渡した判断とレポートのロジックがすべてオーバーライドとして使用されます。

onError() コールバックは、2 つの状況を通知します。

• オーバーライドが無効な引数を指定して試みられた場合、AdServiceException は原因として IllegalArgumentException を示します。
• 開発者向けオプションを有効にしたデバッグモードで実行されているわけではないアプリでオーバーライドが試みられた場合、AdServiceException は原因として IllegalStateException を示します。

セルサイドのオーバーライドをリセットする

このセクションでは、セルサイドの JavaScript をオーバーライドしていることと、前のセクションで使用した TestAdSelectionManager と AdSelectionConfig への参照があることを前提としています。

すべての AdSelectionConfigs のオーバーライドをリセットするには:

1. 非同期の resetAllAdSelectionConfigRemoteOverrides() メソッドを、適切な OutcomeReceiver オブジェクトを指定して呼び出します。

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

セルサイドのオーバーライドをリセットした後、selectAds() への呼び出しが AdSelectionConfig に格納されている decisionLogicUrl を使用して、必要な JavaScript の取得を試みます。

resetAllAdSelectionConfigRemoteOverrides() の呼び出しが失敗した場合、OutComeReceiver.onError() コールバックは AdServiceException を提供します。開発者向けオプションを有効にしてデバッグモードで実行していないアプリでオーバーライドの削除を試みた場合、AdServiceException は原因として IllegalStateException を示します。

バイサイドの JavaScript をオーバーライドする

1. カスタム オーディエンスに参加する手順を実施します。
2. オーバーライドとして使用する入札ロジックとデータに加え、オーバーライドするカスタム オーディエンスの購入者と名前を指定して、AddCustomAudienceOverrideRequest を作成します。
3. 非同期の overrideCustomAudienceRemoteInfo() メソッドを、AddCustomAudienceOverrideRequest オブジェクト、適切な Executor オブジェクト、OutcomeReceiver オブジェクトを指定して呼び出します。

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)

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 への参照があることを前提としています。

すべてのカスタム オーディエンスのオーバーライドをリセットするには:

1. 非同期の resetAllCustomAudienceOverrides() メソッドを、適切な Executor オブジェクトと OutcomeReceiver オブジェクトを指定して呼び出します。

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// 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() で使用され、インプレッション レポートが正常に完了したことを FLEDGE に通知します。

テストする機能

• ユーザーのこれまでの行動に基づいてカスタム オーディエンスへの参加、そこからの脱退、そのセットアップを行う。
• リモートでホストされる JavaScript を使い、オンデバイスの広告選択を開始する。
• アプリのカスタム オーディエンス設定との関連付けが、広告選択の結果にどのように影響するかを確認する。
• 広告選択後のインプレッション レポートを行う。

制限事項

次の表に、FLEDGE 処理の制限を示します。ここに示されている制限は、フィードバックに基づいて変更される可能性があります。処理中の機能については、リリースノートをご覧ください。

バグと問題を報告する

皆様からのフィードバックは、Android 版プライバシー サンドボックスに欠かせない要素です。問題が見つかった場合や Android 版プライバシー サンドボックスを改善するためのアイデアがありましたらお知らせください。