使用 Protected Audience 的自訂目標對象委派作業

fetchAndJoinCustomAudience API 可讓買方利用合作夥伴 MMP 或賣方平台的裝置端,委派加入自訂目標對象。

簡介

大致的運作流程,是裝置端的呼叫端 (無論是 MMP 或 SSP SDK) 會建立一個 fetchAndJoinCustomAudienceRequest,如下所示:

Kotlin

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

Java

/**
 * @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 端解決這個問題,請參閱「加入 CA 委派的設計提案」。

測試

在用戶端程式碼中導入擷取呼叫,並在 DSP 端設定端點以傳回自訂目標對象資料後,您就可以測試加入自訂目標對象的委派作業。執行應用程式之前,您必須執行下列指令,開啟 UI 並啟用 Privacy Sandbox:

adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity

UI 彈出後,請務必切換為啟用 Privacy Sandbox 功能,然後執行下列 ADB 指令,完成裝置的測試設定:

adb shell device_config set_sync_disabled_for_tests persistent
adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
adb shell device_config put adservices ppapi_app_allow_list \"\*\"
adb shell device_config put adservices adservice_system_service_enabled true
adb shell device_config put adservices adservice_enabled true
adb shell device_config put adservices adservice_enable_status true
adb shell device_config put adservices global_kill_switch false
adb shell device_config put adservices fledge_js_isolate_enforce_max_heap_size false
adb shell device_config put adservices fledge_custom_audience_service_kill_switch false
adb shell device_config put adservices fledge_select_ads_kill_switch false
adb shell device_config put adservices adid_kill_switch false
adb shell setprop debug.adservices.disable_fledge_enrollment_check true
adb shell device_config put adservices fledge_fetch_custom_audience_enabled true

執行這些指令後,您應該就能順利使用 Fetch API 發出呼叫。

我們已將擷取呼叫新增至 GitHub 上 Privacy Sandbox 範例存放區的開發人員預覽分支版本,如想瞭解擷取呼叫的示例,請按這裡