オーディエンス データを定義する

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

Android Protected Audience API を使用すると、ユーザーのデバイスでカスタム オーディエンスに加入したり、カスタム オーディエンスから離脱したりできます。カスタム オーディエンスを作成して参加する場合は、カスタム オーディエンス プロパティの一部またはすべてを取得するサーバーに委任するか、API を直接呼び出すときにこの情報を指定できます。

カスタム オーディエンス

次のパラメータの組み合わせにより、デバイス上の CustomAudience オブジェクトのそれぞれが一意に識別されます。

  • owner: オーナーアプリのパッケージ名。暗黙的に、呼び出し元アプリのパッケージ名に設定されます。
  • buyer: このカスタム オーディエンスの広告を管理する、購入者の広告ネットワークの識別子。
  • name: カスタム オーディエンスの任意の名前または識別子。

また、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 オブジェクト。
    • Ad Filters: 広告の選択時にアプリ インストール広告のフィルタリングとフリークエンシー キャップ設定に必要なすべての情報が含まれるクラス。

カスタム オーディエンスを取得して参加する

fetchAndJoinCustomAudience API を使用すると、購入者はパートナーの MMP または SSP のデバイス上のプレゼンスを利用して、カスタム オーディエンスへの参加を委任できます。

これを実現するために、デバイス上の呼び出し元（MMP または SSP SDK）が次のような fetchAndJoinCustomAudienceRequest を作成します。

KotlinJava
/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

すべてのオプション パラメータに関する重要な注意事項: フェッチ リクエストの内部でパラメータが設定されている場合、購入者から返されたデータによってパラメータのデータをオーバーライドできないため、カスタム オーディエンスに対するデバイス上の呼び出し元の追加制御は保持されます。

fetchUri は、以下に示されている形式に一致するカスタム オーディエンス JSON オブジェクトを返すサーバー エンドポイント（購入者によって運用されているもの）を指している必要があります。

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

これを API で解決する方法について詳しくは、Join CA 委任の設計案をご覧ください。

テスト

クライアント コード内にフェッチ呼び出しを実装し、カスタム オーディエンス データを返すように DSP 側でエンドポイントを設定したら、カスタム オーディエンスへの参加の委任をテストできます。アプリを実行する前に、[テストの設定] ページでコマンドを実行する必要があります。これらのコマンドを実行すると、Fetch API を使用した呼び出しを開始できるようになります。

GitHub のプライバシー サンドボックス サンプル リポジトリにフェッチ呼び出しが追加されており、このフローの例を確認できます。

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

カスタム オーディエンスの作成と参加に必要な情報がすべて揃っている場合は、非同期の Protected Audience API 呼び出しを使用して直接作成できます。カスタム オーディエンスを直接作成または参加するには、次の操作を行います。

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

// Minimal initialization of a CustomAudience object
val audience: 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()

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

// Minimal initialization of a CustomAudience object
CustomAudience audience = 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();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() の結果を処理する

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

  • onResult() コールバックは、カスタム オーディエンスが正常に作成または更新されたことを通知します。
  • onError() コールバックは、2 つの状況を通知します。
    • JoinCustomAudienceRequest が無効な引数を指定して初期化されている場合、AdServicesException が IllegalArgumentException を原因として通知します。
    • 他のすべてのエラーでは、IllegalStateException が設定された AdServicesException を原因として受け取ります。

joinCustomAudience() の結果を処理する例を次に示します。

KotlinJava
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 オブジェクトを指定して呼び出します。
KotlinJava
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)

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() コールバックが呼び出されます。