使用 Protected Audience API 支援自訂指定目標對象

提供意見

近期更新

Protected Audience 目前為 Beta 版，可在公開裝置上測試！

您可以透過 Protected Audience 進行以下作業：

  • 根據先前的使用者動作，管理自訂目標對象。
  • 透過單一賣方或刊登序列中介服務，啟動裝置端競價。
  • 在廣告選擇完成後回報曝光。

如要開始使用，請參閱「Protected Audience 開發人員指南」。感謝您在我們持續開發 Protected Audience 的過程中分享意見回饋。

時間表

我們將在未來幾個月內推出新功能，實際發布日期視功能而定。我們會更新這個表格，並在功能可使用時提供說明文件連結。

功能 在開發人員預覽版中推出 在 Beta 版中推出
事件層級報表 2023 年第 1 季 2023 年第 3 季
刊登序列中介服務 2023 年第 1 季 2023 年第 4 季
應用程式安裝廣告篩選功能 2023 年第 2 季 2023 年第 3 季
展示頻率上限篩選功能 2023 年第 2 季 2023 年第 3 季
將內容相關廣告傳遞至廣告選擇工作流程，以便篩選 2023 年第 2 季 2023 年第 3 季
互動報表 2023 年第 2 季 2023 年第 3 季
加入自訂目標對象的委派作業 2023 年第 3 季 2023 年第 4 季
非千次曝光出價結帳服務 2023 年第 3 季 2023 年第 4 季
出價與競價服務整合 2023 年第 3 季 2023 年第 4 季
偵錯報表 2023 年第 3 季 2023 年第 4 季
Attribution Reporting 整合 不適用 2023 年第 4 季
公開出價中介服務 2023 年第 4 季 2023 年第 4 季
貨幣管理 2024 年第 1 季 2024 年第 2 季
K-anon 整合 不適用 2024 年第 2 季
匯總報表整合 2024 年第 3 季 2024 年第 4 季

總覽

在行動廣告方面，廣告主往往會根據使用者先前與自家應用程式的互動情形，向可能感興趣的使用者放送廣告。舉例來說，「SportingGoodsApp」的使用者若有商品放在購物車未結帳，該網站的開發人員可能會想放送廣告，提醒他們完成購買交易。業界通常使用「再行銷」和「自訂指定目標對象」等字詞描述這項概念。

目前碰到這類使用情境時，一般採取的做法是向廣告技術平台提供廣告顯示脈絡資訊 (例如顯示廣告的應用程式名稱) 和私人資訊 (例如目標對象名單)。廣告主可以利用這些資訊，在自家伺服器上選擇相關廣告。

Android 版 Protected Audience API (舊稱 FLEDGE) 涵蓋下列適用於廣告技術平台和廣告主的 API，在支援常見的互動式使用情境時，會限制跨應用程式分享兩者 ID，並控管提供給第三方的使用者與應用程式互動資訊：

  1. Custom Audience API：重心是「自訂目標對象」這個抽象概念。這群廣告主指定的目標對象，本身具有共同意圖。目標對象資訊會儲存在裝置端，並且可以針對目標對象和任意中繼資料 (例如出價信號) 與相關候選廣告建立關聯。這項資訊可用於決定廣告主出價、廣告篩選和廣告顯示方式。
  2. Ad Selection API：這會提供一個架構，可以管理廣告技術平台的工作流程。系統會評估儲存在本機的候選廣告，並加工處理廣告技術平台傳回裝置的候選廣告，然後使用裝置端的信號決定「勝出」廣告。
，瞭解如何調查及移除這項存取權。
Android 版 Privacy Sandbox 的自訂目標對像管理和廣告選擇工作流程圖。
，瞭解如何調查及移除這項存取權。

這項整合服務的運作方式大致如下：

  1. 如果有人將商品加入購物車，卻未在 2 天內完成交易，SportingGoodsApp 會想提醒這些使用者購買商品。因此，SportingGoodsApp 使用 Custom Audience API，將使用者新增至「購物車中有產品」的目標對象名單。該平台會負責管理這份目標對象名單並儲存在裝置上，同時限制與第三方分享這項資訊。接著 SportingGoodsApp 與廣告技術平台合作，向目標對象名單中的使用者放送廣告。廣告技術平台會管理目標對象名單的中繼資料，還會提供候選廣告，讓系統在選擇廣告時納入考量。您可以調整設定，讓該平台在背景中定期擷取最新的目標對象導向廣告。這麼做可確保目標對象導向的候選廣告清單維持在最新狀態，而且與出現廣告放送機會時傳送至第三方廣告伺服器的請求 (即內容相關廣告請求) 沒有關聯。

  2. 使用者在同一部裝置上玩 FrisbeeGame 時，可能會看到廣告提醒，請他們為 SportingGoodsApp 購物車中的商品完成購買程序。為此，包含整合式廣告 SDK 的 FrisbeeGame 可叫用 Ad Selection API，根據可能含有該使用者的任何目標對象名單 (在這個範例中為 SportingGoodsApp 建立的「購物車中有產品」自訂目標對象)，為使用者選擇勝出的廣告。廣告選擇工作流程可經過設定，將擷取自廣告技術平台伺服器的廣告納入考量，而不僅限於與自訂目標對象和其他裝置端信號相關聯的裝置端廣告。廣告技術平台和廣告 SDK 也可以自訂這項工作流程，使用自訂出價和評分邏輯來達成適當的廣告目標。這個做法可讓系統根據使用者的興趣或應用程式互動資料選擇廣告，同時限制與第三方分享這些資料的行為。

  3. 廣告放送應用程式或廣告技術平台的 SDK 顯示所選廣告。

  4. 平台會協助製作曝光和廣告選擇結果報表。這項報表功能與 Attribution Reporting API 相輔相成。廣告技術平台可根據自家報表需求來自訂。

取得 Android 版 Protected Audience API 的存取權

必須先註冊廣告技術平台，才能存取 Protected Audience API。詳情請參閱「註冊 Privacy Sandbox 帳戶」一文。

管理自訂目標對象

自訂目標對象

自訂目標對象是指廣告主認定具有共同意圖或興趣的一群使用者。應用程式或 SDK 可能會使用自訂目標對象來表示特定目標對象，例如「購物車中還有商品」或「已完成遊戲新手關卡」的使用者。平台負責維護目標對象資訊，並將這些資訊儲存在裝置本機上，而不會公開使用者是屬於哪一群自訂目標對象。自訂目標對象與 Chrome 的 Protected Audience 興趣群組不同，且無法在網站和應用程式上共用。這有助於限制分享使用者資訊的行為。

廣告主應用程式或整合式 SDK 可能根據各種因素 (例如應用程式中的使用者參與度)，加入或退出自訂目標對象。

自訂目標對象中繼資料

每個自訂目標對象都含有下列中繼資料：

  • 擁有者：擁有者應用程式的套件名稱。默示設定為呼叫端應用程式的套件名稱。
  • 買方：負責為這個自訂目標對象管理廣告的買方廣告聯播網。買方也代表可存取自訂目標對象並擷取相關廣告資訊的一方。請以 eTLD+1 格式指定買方。
  • 名稱：自訂目標對象的任意名稱或 ID，例如含有「中途放棄購物者」的使用者。這項屬性有多種用途，例如在廣告主的廣告活動中做為其中一項指定條件，或是做為擷取出價程式碼的網址查詢字串。
  • 啟用時間和到期時間：這些欄位定義了這個自訂目標對象的效期。平台會使用這項資訊來撤銷自訂目標對象的成員資格。為了限制自訂目標對象的效期，到期時間不得超過特定的最大時間長度。
  • 每日更新網址：平台用於擷取候選廣告，以及「使用者出價信號」和「受信任出價信號」中定義的其他中繼資料的網址欄位。詳情請參閱下方的「擷取適用於自訂目標對象的候選廣告」一節。
  • 使用者出價信號：用於再行銷廣告出價的廣告技術平台專屬信號，例如使用者的概略位置、偏好語言等。
  • 受信任的出價資料：廣告技術平台會根據即時資料來擷取廣告和評分。比方說，廣告可能預算不足，必須立即停止放送。廣告技術可定義用於擷取這項即時資料的網址端點，以及必須對其執行即時查詢作業的一組索引鍵。這項要求會由廣告技術平台管理的受信任伺服器來處理。
  • 出價邏輯網址：平台用於從需求端平台擷取出價程式碼的網址。平台會在廣告競價程序啟動時執行這個步驟。
  • 廣告：適用於自訂目標對象的候選廣告清單。其中包括廣告技術平台專屬的廣告中繼資料，以及用於顯示廣告的網址。自訂目標對象的競價程序啟動時，系統會將這份廣告中繼資料清單納入考量。如果可以的話，系統會使用每日更新網址端點重新整理這份廣告清單。基於行動裝置的資源限制，單一自訂目標對象中可儲存的廣告有數量限制。

自訂目標對象的委派作業

傳統的自訂目標對象定義和設定，通常需仰賴由代理商、廣告主客戶和合作夥伴攜手推動的伺服器端技術，以及由廣告技術驅動的整合作業。Protected Audience API 可讓您啟用自訂目標對象定義和相關設定，同時保護使用者隱私。由於「買方」廣告技術人員在應用程式中沒有 SDK，因此需要與有裝置端的廣告技術人員 (例如行動評估合作夥伴 (MMP) 和供應端平台 (SSP)) 合作，才可以加入自訂目標對象。Protected Audience API 旨在針對自訂目標對象管理事宜，提供彈性的解決方案，以便支援這些 SDK。具體方法是在裝置端啟用呼叫端，代表買方叫用自訂目標對象建立作業。這項程序稱為「自訂目標對象委派」。如要設定自訂目標對象委派作業，請按照以下步驟操作：

加入自訂目標對象

加入自訂目標對象的方法有兩種：

joinCustomAudience()

應用程式或 SDK 可以先使用預期的參數將 CustomAudience 物件例項化，然後呼叫 joinCustomAudience() 來要求加入自訂目標對象。請參考以下說明用的程式碼片段範例：

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

應用程式或 SDK 可以使用預期的參數呼叫 fetchAndJoinCustomAudience()，以便代表沒有裝置端的廣告技術提出加入自訂目標對象的要求，如以下範例所示：

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

買方擁有的網址端點會在回應主體中以 CustomAudience JSON 物件做出回應，而自訂目標對象的買方和擁有者欄位將遭到忽略 (並由 API 自動填入)。這個 API 還會強制讓每日更新網址也與買方的 eTLD+1 相符。

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

fetchAndJoinCustomAudience() API 會根據 fetchUri 的 eTLD+1 判定買方的身分。CustomAudience 買方的身分用於執行 joinCustomAudience() 所做的註冊和應用程式驗證檢查，這無法透過擷取回應變更。CustomAudience 擁有者是呼叫應用程式的套件名稱。請注意，除了 eTLD+1 檢查以外，這裡沒有其他 fetchUri 驗證，尤其沒有 k-anon 檢查。fetchAndJoinCustomAudience() API 會向 fetchUri 發出 HTTP GET 要求，並預期代表自訂目標對象的 JSON 物件。自訂目標對象物件欄位的必要/選用限制和預設值同樣都會套用至回應。如要瞭解現行的規定和限制，請參閱《開發人員指南》。

買方的任何 HTTP 錯誤回應都會導致 fetchAndJoinCustomAudience 失敗。具體來說，HTTP 狀態回應 429 (「要求數超量」) 會在待定義的時段內封鎖來自目前應用程式的要求。如果買方回應格式錯誤，API 呼叫也會失敗。系統會將失敗情形回報給 API 呼叫端，這些呼叫端的職責是在發生暫時性錯誤 (例如伺服器未回應) 時重試，或處理永久性錯誤 (例如資料驗證失敗，或與伺服器通訊時的其他非暫時性錯誤)。

有了 CustomAudienceFetchRequest 物件，API 呼叫端就能使用上述範例中的選用屬性，定義自訂目標對象的部分資訊。如果在要求中指定的話，平台收到的買方回應就無法覆寫這些值；Protected Audience API 會忽略回應中的欄位。如果沒有在要求中指定，則必須在回應中設定，因為建立自訂目標對象時會需要這些欄位。在對 fetchUri 提出 GET 要求後，由 API 呼叫端部分定義的 CustomAudience 內容會以 JSON 表示法顯示在特殊標頭 X-CUSTOM-AUDIENCE-DATA 中。為自訂目標對象指定的序列化格式資料大小上限為 8 KB。如果超過這個大小，fetchAndJoinCustomAudience API 呼叫就會失敗。

由於沒有 k-anon 檢查，因此您可以使用 fetchUri 進行買方驗證，並啟用買方和 SDK 之間的資訊分享功能。為了讓自訂目標對象順利驗證，買方可以提供驗證權杖。裝置端的 SDK 應將這個權杖納入 fetchUri 中，以利買方代管的端點擷取自訂目標對象的內容，並使用驗證權杖來驗證 fetchAndJoinCustomAudience() 作業確實對應於買方，且是由信任的裝置端合作夥伴發起。如要共用資訊，買方可以和裝置端的呼叫端達成共識，將用於建立自訂目標對象的部分資訊新增為 fetchUri 的查詢參數。這可讓買方稽核呼叫，並偵測惡意廣告技術是否已使用驗證權杖建立數個不同的自訂目標對象。

關於驗證權杖定義和儲存空間的注意事項

  • Protected Audience API 不會基於任何目的使用驗證權杖，而且您可以選擇是否提供驗證權杖。

    • 買方可能會將驗證權杖用於驗證，確保系統正代表他們建立目標對象。
    • Protected Audience API 提案既不用指定驗證權杖的格式，也不用指定將驗證權杖轉移給呼叫端的方式。舉例來說，驗證權杖可在擁有者的 SDK 或後端預先載入，擁有者的 SDK 也可以從買方的伺服器即時擷取該權杖。

退出自訂目標對象

自訂目標對象的擁有者可以呼叫 leaveCustomAudience()，選擇退出自訂目標對象，如下方說明用的程式碼片段所示：

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

為節省儲存空間和其他裝置資源的用量，在經過預先決定的一段時間後，自訂目標對象就會到期，並從裝置上的儲存空間中移除。相關設定的預設值尚待決定。擁有者可以覆寫這個預設值。

使用者控制項

  • 本提案旨在為使用者提供瀏覽已安裝應用程式清單，且建立至少一個自訂目標對象
  • 使用者可以將應用程式從這份清單中移除。這樣一來，系統會清除與應用程式相關聯的所有自訂目標對象，且應用程式將無法加入新的自訂目標對象。
  • 使用者可以徹底重設 Protected Audience API。發生這種情況時，系統會清除裝置上現有的所有自訂目標對象。
  • 使用者可以選擇完全停用 Android 版 Privacy Sandbox，包括 Protected Audience API。如果使用者已選擇不採用 Privacy Sandbox，Protected Audience API 就會失敗，且不會顯示相關通知。

這項功能的設計仍在開發階段，相關詳細資料將於日後更新時提供。

定期更新

先前所述的解決方案需要應用程式或廣告技術 SDK 叫用 應用程式位於前景時，API 會提供 自訂目標對象。不過，廣告主和廣告技術供應商不一定能夠在使用者使用應用程式時，即時定義使用者所屬的目標對象。

為了達成此目標，廣告技術可以呼叫 scheduleCustomAudienceUpdate() API。這個 API 可讓呼叫端指定 因此可延遲執行 API 呼叫 讓回應的廣告技術處理應用程式層級事件，並判斷哪些 使用者應加入或移除的 Protected Audience。

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

ScheduleCustomAudienceUpdateRequest 包含 註冊延遲工作，以便透過平台執行。在指定的延遲時間過後 背景工作會定期執行並傳送要求。 ScheduleCustomAudienceUpdateRequest 可包含以下資訊：

  • UpdateUri：系統會傳送 GET 呼叫以擷取更新的 URI 端點。 買家身分是從 eTLD+1 推論得出，因此不必 無法由更新回應進行變更。GET 要求預期 JSON 物件會包含一份 customAudience 物件清單， 傳回。
  • DelayTime：代表發生時間延遲， scheduleCustomAudienceUpdate() API 呼叫，藉此安排更新時間。

  • PartialCustomAudience：這個 API 也可讓裝置端 SDK 傳送清單 部分建構的自訂目標對象如此一來，應用程式內的 SDK 就能 雙重角色，包括全面控管自訂目標對像管理 實際應用的國家/地區。

    • 這也能讓這個 API 與 fetchAndJoinCustomAudience() 相容 可讓您共用類似資訊的 API。

  • ShouldReplacePendingUpdates：決定任何待處理狀態的布林值 排定的更新作業應取消，並以 目前的ScheduleCustomAudienceUpdateRequest。如果設為 false 且 導致同一位買方先前要求的更新仍待處理 相同應用程式，而使用這個例子呼叫 scheduleCustomAudienceUpdate ScheduleCustomAudienceUpdateRequest 將會失敗。預設為 false。

應用程式權限和控制項

本提案旨在讓應用程式控管自訂目標對象：

  • 應用程式可以管理與自訂目標對象的關聯。
  • 應用程式可以授權第三方廣告技術平台，允許其代表應用程式管理自訂目標對象。

這項功能的設計仍在開發階段，相關詳細資料將於日後更新時提供。

廣告技術平台控制項

本提案概述廣告技術可透過哪些方法控管自訂目標對象：

  • 廣告技術會註冊 Privacy Sandbox，並提供符合自訂目標對象所有網址的 eTLD+1 網域。
  • 廣告技術可與應用程式或 SDK 合作，提供用於驗證自訂目標對象建立作業的驗證權杖。當這項程序委派給合作夥伴時，就可以將自訂目標對象建立作業設為需要經過廣告技術確認。
  • 廣告技術可以選擇代表他們停用 joinCustomAudience 呼叫，並只允許 fetchAndJoinCustomAudience API 啟用所有呼叫自訂目標對象。控制項可在 Privacy Sandbox 註冊期間更新。請注意，這個控制項可允許/不允許所有廣告技術。由於平台限制，委派權限不得以個別廣告技術為基礎。

候選廣告和中繼資料回應

買方平台傳回的候選廣告和中繼資料應包含下列欄位：

  • 中繼資料：買方的廣告技術專屬廣告中繼資料。例如廣告活動的相關資訊，以及位置和語言等指定條件。
  • 顯示網址：用於顯示廣告素材的端點。
  • 篩選器：讓 Protected Audience API 根據裝置端資料篩選廣告的必要選用資訊。詳情請參閱「買方篩選邏輯」一節。

廣告選擇工作流程

本提案旨在導入 Ad Selection API，為廣告技術平台自動化調度管理競價執行作業，藉此加強隱私保護。

廣告技術平台目前通常只會在自家伺服器上執行出價和廣告選擇作業。在本提案中，自訂目標對象和其他敏感使用者信號 (例如可用的已安裝套件資訊) 將只能透過 Ad Selection API 存取。此外，就「再行銷」這個用途來說，系統會以跳脫脈絡的方式 (即不考慮廣告顯示情境) 擷取候選廣告。廣告技術平台必須做好準備，在裝置上部署及執行部分現行的競價和廣告選擇邏輯。廣告技術平台可考慮對廣告選擇工作流程進行下列變更：

  • 如果伺服器上沒有可用的已安裝套件資訊，廣告技術平台可考慮將多個內容相關廣告傳回裝置，並叫用廣告選擇工作流程，藉此啟用以應用程式安裝為準的篩選功能，盡可能增加顯示相關廣告的機會。
  • 由於系統會以跳脫脈絡的方式擷取再行銷廣告，因此目前的出價模式可能得經過更新。廣告技術平台可考慮建立出價子模式 (可根據雙塔模式建立)，分開處理廣告功能和比對內容訊號，並結合裝置上的子模式輸出內容來預測出價。這可受惠於伺服器端競價和任何廣告放送機會的競價。

這個方法可讓系統根據使用者的應用程式互動資料選擇廣告，同時限制與第三方分享這項資料。

廣告選擇工作流程啟動流程圖。

這個廣告選擇工作流程會依照以下順序，自動化調度管理裝置上的廣告技術所提供 JavaScript 程式碼執行作業：

  1. 執行買方出價邏輯
  2. 篩選及處理買方廣告
  3. 執行賣方決策邏輯

針對涉及自訂目標對象的廣告選擇作業，平台會根據自訂目標對象的「出價邏輯網址」中繼資料所定義的公開網址端點，擷取買方提供的 JavaScript 程式碼。系統也會將賣方決策程式碼的網址端點做為輸入內容傳遞，藉此啟動廣告選擇工作流程。

不涉及自訂目標對象的廣告選擇工作流程仍在設計中。

啟動廣告選擇工作流程

當應用程式必須顯示廣告時，廣告技術平台 SDK 可以透過呼叫 selectAds() 方法，使用預期的參數將 AdSelectionConfig 物件執行個體化，以啟動廣告選擇工作流程：

  • 賣方：賣方廣告平台的 ID，遵循 eTLD+1 格式
  • 決策邏輯網址：廣告競價流程啟動時，平台會使用這個網址從賣方平台擷取 JavaScript 程式碼，藉此為勝出的廣告評分。
  • 自訂目標對象買方：對競價有自訂目標對象需求的買方平台清單，並採用 eTLD+1 格式。
  • 廣告選擇信號：廣告大小、廣告格式等競價相關資訊。
  • 賣方信號：供應端平台專屬信號。
  • 受信任評分信號網址：賣方受信任信號的網址端點，用於擷取廣告素材專屬即時資訊。
  • 個別買方信號：參與的需求端可利用這項參數為競價提供輸入內容。舉例來說，這項參數可包含有助於決定出價的詳盡脈絡資訊。

在以下說明用程式碼片段中，廣告技術平台 SDK 會先使用 AdSelectionConfig，再叫用 selectAds 來取得勝出的廣告，然後啟動廣告選擇工作流程：

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

買方出價邏輯

出價邏輯通常是由買方平台提供。這個程式碼的用途是為候選廣告決定出價。實際上可能需要套用額外的商業邏輯才能決定出結果。

平台會使用自訂目標對象的「出價邏輯網址」中繼資料來擷取 JavaScript 程式碼，當中應包含以下函式簽章：

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

generateBid() 方法會回傳計算出的出價金額。平台會依序針對所有廣告 (內容相關廣告或再行銷廣告) 叫用這個函式。如果有多個出價邏輯提供者，系統不保證能依提供者的順序執行這項作業。

這個函式預期的參數如下：

  • 廣告：買方出價程式碼所考慮的廣告。這將是符合資格的自訂目標對象廣告
  • 競價信號：賣方平台專屬信號。
  • 個別買方信號：參與的需求端可利用這項參數為競價提供輸入內容。舉例來說，這項參數可包含有助於決定出價的詳盡脈絡資訊。
  • 受信任的出價信號：廣告技術平台會根據即時資料來協助擷取廣告和評分。比方說，廣告活動可能預算不足，必須立即停止放送。廣告技術可定義用於擷取這項即時資料的網址端點，以及必須對其執行即時查詢作業的一組索引鍵。為這項要求提供服務的廣告技術平台管理伺服器，會是廣告技術平台管理的受信任伺服器。
  • 內容相關信號：可能包含概略時間戳記或大概位置資訊，或廣告點擊的單次點擊出價。
  • 使用者信號：可能包含可用的已安裝套件等資訊。

廣告費用

除了出價之外，買方平台也可以選擇傳回單次點擊出價，做為 generateBid() 的一環。例如：

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

如果這則廣告是勝出者，基於隱私考量，adCost 會隨機四捨五入至 8 位元。接著，adCost 的四捨五入值會在曝光報表製作期間傳入 reportWin 的 contextual_signals 參數中。

買方篩選邏輯

買方平台將可根據廣告選擇階段可用的其他裝置端信號來篩選廣告。舉例來說，廣告技術平台可導入展示頻率上限。如果有多個篩選提供者，系統不保證能依提供者的順序執行這項作業。

傳回特定廣告的出價值 0，即可導入買方篩選邏輯做為出價邏輯的一部分。

此外，買方平台將可指出應根據 Protected Audience 可用的其他裝置端信號篩選特定廣告，並指出該廣告不會離開裝置。隨著我們強化其他篩選邏輯的設計，買方平台將遵循相同的結構，表明應套用篩選功能。

賣方評分邏輯

評分邏輯通常是由賣方平台提供。這個程式碼的用途是根據出價邏輯輸出結果決定勝出的廣告。實際上可能需要套用額外的商業邏輯才能決定出結果。如果有多個決策邏輯提供者，系統不保證能依提供者的順序執行這項作業。平台會使用 selectAds() API 的「決策邏輯網址」輸入中繼資料來擷取 JavaScript 程式碼，當中應包含以下函式簽章：

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

這個函式預期的參數如下：

  • 廣告：接受評估的廣告；generateBid() 函式的輸出結果。
  • 出價：generateBid()函式的出價金額輸出結果。
  • 競價設定：selectAds() 方法的輸入參數。
  • 受信任的評分信號：廣告技術平台會根據即時資料來篩選廣告和評分。舉例來說，應用程式發布者可能會禁止廣告活動在應用程式中顯示廣告。系統會透過競價設定的受信任評分信號網址參數擷取這項資料。這項要求應由廣告技術管理的受信任伺服器處理。
  • 情境脈絡信號：這可能包含概略時間戳記或大概位置資訊。
  • 使用者信號：這可能包含啟動應用程式安裝事件的應用程式商店等資訊。
  • 自訂目標對象信號：如果接受評分的廣告來自裝置上自訂目標對象，這會包含讀取者和自訂目標對象名稱等資訊。

廣告選擇程式碼執行階段

在本提案中，系統會從可設定的網址端點擷取廣告技術平台提供的競價程式碼，並在裝置上執行。基於行動裝置的資源限制，競價程式碼應遵循下列規範：

  • 程式碼應在預先定義的時間內執行完畢。這項限制將統一套用到所有買方廣告聯播網，相關詳細資料將於日後更新時提供。
  • 程式碼必須為獨立性質，沒有任何外部依附元件。

競價程式碼 (例如出價邏輯) 可能需要存取使用者私人資料 (例如應用程式安裝來源)，因此執行階段不會提供網路或儲存空間的存取權。

程式設計語言

廣告技術平台提供的競價程式碼應以 JavaScript 編寫。這項規定有許多目的，例如讓廣告技術平台可在支援 Privacy Sandbox 的各個平台上共用出價程式碼。

顯示勝出的廣告

得分最高的廣告即為競價勝出者。在本初始提案中，勝出的廣告會傳遞至 SDK 以便顯示。

我們打算改進這項解決方案，確保應用程式或 SDK 無法透過勝出廣告的相關資訊，判斷使用者的自訂目標對象成員資格或應用程式互動記錄 (類似 Chrome 的圍欄頁框提案)。

曝光與事件報表

廣告向使用者顯示後，系統就能向參與的買方和賣方平台回報勝出曝光。如此一來，買方和賣方就能納入出價或自訂目標對象名稱等競價資訊，以及勝出曝光報表。此外，賣方和得標買方平台將有資格收到其他有關勝出廣告的事件層級報表。這樣就能納入出價、自訂目標對象名稱等競價資訊，以及點擊、觀看和其他廣告事件。平台會以下列順序叫用報表邏輯：

  1. 賣方報表
  2. 買方報表

這可讓買方和賣方平台將重要的裝置端資訊傳回伺服器，提供即時預算、出價模式更新和精確計費工作流程等功能。這項曝光報表支援功能與 Attribution Reporting API 相輔相成。

如要支援事件報表，必須採取兩個步驟：賣方和買方 JavaScript 需要註冊事件報表應接收的事件類型，然後賣方負責回報事件層級資訊。

Protected Audience 提供註冊信標的機制，可用來訂閱與勝出競價相關的未來事件。在賣方的 reportResult() JavaScript 函式中，賣方平台可使用平台的 registerAdBeacon() 函式註冊信標。同樣地，買方平台可以從 reportWin() JavaScript 函式呼叫 registerAdBeacon() 方法。

registerAdBeacon(beacons)

輸入內容：

  • event_key：用來表示要註冊哪個互動類型的字串。此字串可當做查詢平台連線偵測 (ping) 端點的鍵，同時回報競價結果。
  • reporting_url：處理事件的廣告技術平台所擁有的網址。

事件鍵是負責回報競價結果的賣方 SDK 所擁有的字串 ID。如要發出回呼，廣告技術會註冊信標，且該信標的鍵需符合賣方回報事件時所使用的鍵。這類項目不必進行 k 匿名化，不過系統會限制指定自訂目標對象可註冊的鍵數量和長度。如果呼叫 reportEvent()，則執行競價的賣方平台一律有資格收到這類事件報表。只有得標買方平台有資格接收這類報表。

賣方報表

平台會在供應端提供的程式碼中，為 selectAds() API 叫用 reportResult() JavaScript 函式。該程式碼是從賣方的決策邏輯網址參數下載：

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

輸出內容：JSON 物件，其中包含

  • 狀態：0 代表成功，任何其他值則代表失敗。
  • 報表網址：平台會叫用函式傳回的這個網址。
  • 給買方的信號：要傳遞至買方 reportWin 函式的 JSON 物件。

供應端可以將相關信號編碼至報表網址中，取得有關競價和勝出廣告的深入分析資訊。比方說，網址中可包含以下信號：

  • 廣告顯示網址
  • 勝出出價金額
  • 應用程式名稱
  • 查詢 ID
  • 買方信號：為了讓供應端和需求端互相分享資料，平台會將這個回傳值做為輸入參數傳遞給需求端報表程式碼。

買方報表

平台會在需求端提供的程式碼中叫用 reportWin() JavaScript 函式。與競價相關聯的自訂目標對象擁有出價邏輯網址中繼資料，上述程式碼會從該中繼資料下載。

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

輸入內容：

  • auction_signals 和 per_buyer_signals 是從 AuctionConfig 擷取。買方平台必須傳遞至報表網址的所有資訊都可能來自這些資料。
  • signals_for_buyer 是賣方 reportResult 的輸出內容。這可讓賣方平台有機會與買方平台分享資料，以便製作報表。
  • contextual_signals 包含應用程式名稱等資訊，custom_audience_signals 則包含自訂目標對象資訊。日後可能會再加入其他資訊。

輸出內容：

  • 狀態：0 代表成功，任何其他值則代表失敗。
  • 報表網址：平台會叫用函式傳回的這個網址。

回報事件

只有在競價的曝光報表完成後，系統才會回報事件。賣方 SDK 需負責回報所有事件。平台公開的 API 可使用 ReportEventRequest，這個項目可指定最近執行的競價、回報的事件索引鍵、與該鍵相關聯的資料、是否應將報表傳送給買方和/或賣方，以及廣告事件的選用輸入事件。用戶端會定義要回報的事件索引鍵和資料收集內容。

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

輸入內容：

  • ad_selection_id 需為擷取自 AdSelectionOutcome 最近所執行競價的 AdSelectionId。
  • event_key 是賣方定義的字串，用來說明互動事件。
  • event_data 字串代表與 event_key 相關聯的資料。
  • reporting_destinations 是位元遮罩組合，會使用平台提供的標記。可能是 FLAG_REPORTING_DESTINATION_SELLER 和/或 FLAG_REPORTING_DESTINATION_BUYER。
  • input_event (選用) 用於與 Attribution Reporting API 整合。可以是 InputEvent 物件 (用於點擊事件) 或空值 (用於瀏覽事件)。如要進一步瞭解這個參數，請參閱「Attribution Reporting API 整合」。

賣方 SDK 叫用 reportEvent 後，平台會依據 reporting_destinations 標記，嘗試比對 event_key 與買方和賣方在 reportWin 和 reportResult JavaScript 函式中註冊的鍵。如果比對相符，平台會以 POST 的方式將 event_data 發布至相關聯的 reporting_url。要求的內容類型為純文字，主體為 event_data。系統會盡量執行這項要求，如果出現網路錯誤、伺服器錯誤回應，或是找不到相符的鍵，則這項要求會失敗，而且不會顯示相關通知。

Attribution Reporting API 整合

為了替參與 Protected Audience 競價的買方提供支援，我們在 Protected Audience 和 Attribution Reporting API (ARA) 間推出了跨 API 功能。此功能可讓廣告技術評估各種再行銷策略的歸因成效，瞭解哪些類型的目標對象能帶來最高的投資報酬率。

透過這項跨 API 整合，廣告技術可以：

  • 建立用於 1) 廣告互動報表和 2) 來源登錄的 URI 鍵/值對應。
  • 將 Protected Audience 競價的競價資料納入其來源端的鍵對應中，以便取得匯總摘要報表 (使用 Attribution Reporting API)。詳情請參閱 ARA 設計提案。

使用者查看或點擊廣告時：

  • 透過 Protected Audience 回報這些事件互動時所用的網址，也會提供必要資料給買方，以便買方利用 Attribution Reporting API 將觀看或點擊登錄為符合條件的來源。
  • 廣告技術可以選擇使用該網址傳遞 CustomAudience (或其他廣告相關的背景資訊，例如廣告刊登位置或觀看時間長度)，以便在廣告技術正在查看匯總廣告活動成效時，將這項中繼資料向下傳遞至摘要報告。

啟用來源登錄功能

reportEvent() 接受新的選用參數 InputEvent。凡是會登錄廣告信標的勝出買方，都可以選擇要利用 Attribution Reporting API，將哪些 reportEvent 報表登錄為登錄來源。「Attribution-Reporting-Eligible」要求標頭會加到從 reportEvent() 傳送的所有事件報表要求中。剖析任何含有適當 ARA 標頭的回應時，方法與所有其他一般 ARA 來源登錄回應相同。如要瞭解如何登錄來源網址，請參閱 Attribution Reporting API 說明。

由於 Android 上的 ARA 支援瀏覽和點擊事件，因此 InputEvents 可用來區分這兩種類型。就像在 ARA 來源登錄中一樣，reportEvent() API 會將平台驗證的 InputEvent 解讀為點擊事件。如果 InputEvent 遺失、屬於空值或無效，系統會將來源登錄作業視為瀏覽事件。

請注意，競價後的 eventData 可能包含機密資訊，因此平台會在重新導向的來源登錄要求中捨棄 eventData。

參與度和轉換報表範例

在本例中，買方有意一起將競價、所示廣告和轉換應用程式的資料建立關聯，我們會從這個角度來思考。

此工作流程中，買方會與賣方協調，以便傳送專屬 ID 參與競價。在競價期間，買方會透過競價資料傳送該專屬 ID。而在顯示和轉換期間，所示廣告的資料也會以相同的專屬 ID 送出。之後，專屬 ID 就能用來建立這些報表的關聯。

工作流程：在競價開始之前，買方會在程式輔助即時出價 (「RTB」) 的出價回應中，傳送專屬 ID 給賣方。ID 可設為 auctionId 等變數，會以 perBuyerSignals 的形式在 auctionConfig 中傳入，並用於買方的出價邏輯中。

  1. 在 reportWin 執行期間，買方可以登錄廣告信標，以便在廣告顯示或特定互動事件 (registerAdBeacon()) 發生時觸發。如要為廣告事件的競價信號建立關聯，請將 auctionId 設為信標網址的查詢參數。
  2. 在廣告顯示期間，您可以透過事件層級資料觸發或加強競價期間註冊的信標。賣方必須觸發 reportEvent() 並傳入事件層級資料。平台會連線偵測 (ping) 買方登錄的廣告信標網址，該網址與已觸發的 reportEvent() 有所關聯。
  3. 買方會利用 Attribution-Reporting-Register-Source 標頭回應廣告信標要求，以便使用 Attribution Reporting API 登錄廣告。如要為轉換事件的競價信號建立關聯，請在「登錄來源網址」中設定 auctionId。

完成上述流程後，買方將取得競價報表、互動報表和轉換報表，這些報保可透過專屬 ID 建立關聯。

如果賣方需要存取歸因資料，則適用類似的工作流程，而賣方也可以使用以 registerAdBeacon() 傳送的專屬 ID。reportEvent() 呼叫包含目的地屬性，可用來將報表同時傳送給買方和賣方。

廣告技術平台管理的受信任伺服器

目前廣告選擇邏輯必須使用即時資訊 (例如預算使用狀態)，才能判斷是否應選擇特定候選廣告進行競價。買方和賣方平台都能從用於維持運作的伺服器取得這項資訊。為了盡可能避免透過這些伺服器洩漏任何機密資訊，本提案設有下列限制：

  • 這些伺服器的行為 (如本節下方內容所述) 不得洩漏使用者資訊。
  • 伺服器不得根據讀取到的資料建立匿名個人資料，即伺服器必須「受信任」。

買方：當買方啟動買方出價邏輯時，平台就會執行 HTTP 擷取作業，從受信任的伺服器擷取受信任的出價資料。這個網址的組成方式，是擷取所處理自訂目標對象的受信任出價信號中繼資料，然後附加當中包含的網址和鍵。系統只會在處理裝置上自訂目標對象的廣告時執行這項擷取作業。在這個階段，買方可以強制執行預算、檢查廣告活動暫停/取消暫停狀態、指定目標及執行其他操作。

以下是用於擷取受信任出價資料的範例網址 (以自訂目標對象的受信任出價信號中繼資料為依據)：

https://www.kv-server.example/getvalues?keys=key1,key2

伺服器的回應應為 JSON 物件，該物件的鍵為 key1、key2 等，值則會提供給買方的出價函式。

賣方：與上述的買方流程類似，賣方可能會想針對系統在競價時考慮的廣告素材擷取相關資訊。舉例來說，發布商可能會想基於品牌安全考量，禁止特定廣告素材顯示在其應用程式中。系統可以擷取這項資訊並提供給賣方競價邏輯。與買方受信任伺服器查詢作業類似，賣方受信任伺服器查詢作業也是透過 HTTP 擷取執行。這個網址的組成方式，是針對必須擷取相關資料的廣告素材取得顯示網址，並將該顯示網址附加到受信任評分信號網址。

以下提供一個範例網址，用於針對系統在競價時考慮的廣告素材擷取相關資訊 (以廣告素材顯示網址為依據)：

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

伺服器的回應應為 JSON 物件，該物件的鍵為要求中傳送的顯示網址。

這些伺服器會以受信任的方式運作，提供多項安全性和隱私方面的優點：

  • 伺服器的各鍵傳回值保證完全以該鍵為依據。
  • 伺服器不會執行事件層級記錄作業。
  • 伺服器不會根據這些要求出現其他副作用。

目前買方和賣方可從任何伺服器 (包括自己營運的伺服器) 擷取這些出價信號，但這是暫時性的機制。在發布版本中，要求只會傳送至受信任的鍵/值類型伺服器。

如果平台與 Android 版和網頁版 Privacy Sandbox 相容，買方和賣方就能使用常見的受信任鍵/值類型伺服器。