行動版歸因報表總覽

近期更新

  • 更新近期異動和已知問題清單

  • 導入精簡彈性事件層級設定，做為通往完整彈性事件層級設定的橋樑

  • 自 2023 年 9 月起，registerWebSource、registerWebTrigger、registerAppSource 和 registerAppTrigger 必須在需要數字值的欄位中 (例如 priority、source_event_id、debug_key、trigger_data、deduplication_key 等) 使用字串

  • 在 2023 年第 4 季，我們將新增 Android Attribution Reporting API 的 Google Cloud 支援，以便利用 Google Cloud 上的匯總服務產生摘要報表，更詳細的時程資訊請參閱本文。如要進一步瞭解如何透過 Google Cloud 設定匯總服務，請參閱部署指南。

  • 針對不重複目的地數量，新增隱私權保護頻率限制。

  • 回溯期觸發事件篩選器的更新功能將於 2024 年第 1 季推出，詳情請參閱附註。

總覽

如今，行動裝置的歸因和成效評估解決方案往往使用廣告 ID 等跨方 ID。Attribution Reporting API 的設計宗旨是要避免仰賴跨方使用者 ID，進一步保護使用者隱私，同時顧及重要使用情境，支援應用程式和網頁的歸因與轉換評估功能。

這個 API 具有以下結構機制，可提供有助於保護隱私的架構 (詳情請參閱本頁後續章節)：

上述機制會讓使用者身分無法在兩個不同的應用程式或網域間相互連結。

Attribution Reporting API 支援下列使用情境：

  • 製作轉換報表：為廣告客戶提供廣告活動、廣告群組和廣告素材等各個維度的轉換 (觸發) 次數與轉換 (觸發) 值，協助他們評估廣告活動的成效。
  • 進行最佳化：提供可用於訓練機器學習模型的個別曝光歸因資料，並製作成事件層級報表，協助最佳化廣告支出。
  • 偵測無效活動：提供可用於偵測及分析無效流量和廣告詐欺行為的報表。

Attribution Reporting API 的運作方式大致如下，詳情請參閱本文後續章節：

  1. 廣告技術需完成註冊程序，才能使用 Attribution Reporting API。
  2. 廣告技術使用 Attribution Reporting API 登錄歸因來源 (廣告點擊或瀏覽)。
  3. 廣告技術使用 Attribution Reporting API 登錄觸發事件 (使用者在廣告客戶應用程式或網站中進行轉換)。
  4. Attribution Reporting API 會比對觸發事件與歸因來源 (轉換歸因)，然後透過事件層級報表和可匯總報表，在裝置外部將一或多個觸發事件傳送至廣告技術。

取得 Attribution Reporting API 的存取權

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

登錄歸因來源 (點擊或瀏覽)

Attribution Reporting API 將廣告點擊和觀看次數稱為「歸因來源」。如要登錄廣告點擊或廣告瀏覽，請呼叫 registerSource()。這個 API 預期的參數如下：

  • 歸因來源 URI：平台會向這個 URI 發出要求，擷取與歸因來源相關聯的中繼資料。
  • 輸入事件：可以是 InputEvent 物件 (用於點擊事件) 或 null (用於瀏覽事件)。

當 API 向歸因來源 URI 發出要求時，廣告技術應透過新的 HTTP 標頭 Attribution-Reporting-Register-Source 回應，並提供歸因來源中繼資料，包含下列欄位：

  • 來源事件 ID：這個值代表與此歸因來源 (廣告點擊或觀看) 相關聯的事件層級資料，必須是採字串格式的 64 位元無正負號整數。
  • 目的地：發生觸發事件的 eTLD+1 或應用程式套件名稱的來源。
  • 到期時間 (選填)：以秒為單位，指定經過多少時間後應將來源從裝置中刪除。預設值為 30 天，最小值為 1 天，最大值為 30 天。系統會將這個值四捨五入為最接近的天數。格式可以是 64 位元無正負號整數或字串。
  • 事件報表回溯期 (選填)：來源登錄後，系統可能會針對此來源建立事件報表的時長 (以秒為單位)。如果事件報表回溯期已過，但到期時間還沒，那麼觸發事件仍可與來源進行比對，但系統不會針對該觸發事件傳送事件報表。回溯期時長不得大於到期時間時長。格式可以是 64 位元無正負號整數或字串。
  • 可匯總報表回溯期 (選填)：來源登錄後，系統可能會針對此來源建立可匯總報表的時長 (以秒為單位)。回溯期時長不得大於到期時間時長。格式可以是 64 位元無正負號整數或字串。
  • 來源優先序 (選填)：如果有多個歸因來源可與特定觸發事件建立關聯，系統會以這個值選取適當來源。必須是採字串格式的 64 位元帶正負號整數。

    接收到觸發事件時，API 會尋找來源優先順序值最高的相符歸因來源，並產生報表。每個廣告技術平台都可定義自己的優先順序策略。如要進一步瞭解優先順序如何影響歸因，請參閱有關優先順序範例的章節。

    值越大，表示優先順序越高。
  • 安裝和安裝後歸屬期 (選填)：用於決定安裝後事件的歸因，詳情請參閱本頁後續章節。
  • 篩選資料 (選填)：用於選擇性篩除部分觸發事件，查看資料更有效率。詳情請參閱本頁的「觸發事件篩選器」一節。
  • 匯總鍵 (選填)：指定要用於可匯總報表的區隔。

您可以視需要在歸因來源中繼資料回應內，提供「Attribution reporting redirects」標頭中的額外資料。這項資料包含重新導向網址，可讓多項廣告技術登錄一項要求。

您可以參閱開發人員指南，取得接受來源登錄的範例。

以下是範例工作流程所含的步驟：

  1. 廣告技術 SDK 呼叫 API，啟動歸因來源登錄程序，指定 API 要呼叫的 URI：

    registerSource(
    Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
    myClickEvent);

  2. API 使用以下其中一種標頭向 https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA 發出要求：

    <!-- For click events -->
Attribution-Reporting-Source-Info: navigation

<!-- For view events -->
Attribution-Reporting-Source-Info: event

  3. 廣告技術的 HTTPS 伺服器使用包含下列內容的標頭進行回應：

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "234",
    "expiry": "60000",
    "priority": "5"
}
Attribution-Reporting-Redirect:
https://adtechpartner1.example?their_ad_click_id=567
Attribution-Reporting-Redirect:
https://adtechpartner2.example?their_ad_click_id=890

  4. API 向 Attribution-Reporting-Redirect 中指定的每個網址發出要求。在這個範例中，指定的廣告技術合作夥伴網址有兩個，因此 API 分別向 https://adtechpartner1.example?their_ad_click_id=567 和 https://adtechpartner2.example?their_ad_click_id=890 發出一項要求。

  5. 廣告技術的 HTTPS 伺服器使用包含下列內容的標頭進行回應：

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "789",
    "expiry": "120000",
    "priority": "2"
}

根據上述步驟中的要求，系統會登錄三個導覽 (點擊) 歸因來源。

從 WebView 登錄歸因來源

WebView 支援應用程式在 WebView 中顯示廣告的用途。WebView 的處理方式是直接呼叫 registerSource() 做為背景要求。這項呼叫會將歸因來源與應用程式建立關聯，而非頂層來源。系統也支援從瀏覽器環境中嵌入的網頁內容登錄來源，為此 API 呼叫端和應用程式都需要調整設定。參閱「從 WebView 登錄歸因來源和觸發事件」，即可瞭解 API 呼叫端的操作說明；參閱「WebView 的歸因來源和觸事件登錄」，則可瞭解應用程式的操作說明。

由於廣告技術會在網頁和 WebView 中使用通用程式碼，WebView 會依循 HTTP 302 重新導向，並將有效登錄資料傳送至平台。我們不打算針對這個情況支援 Attribution-Reporting-Redirect 標頭，但如果您的用途受到影響，請聯絡我們。

登錄觸發事件 (轉換)

廣告技術平台可以使用 registerTrigger() 方法登錄「觸發事件」，即安裝或安裝後事件等轉換。

registerTrigger() 方法預期的參數為觸發事件 URI。API 會向這個 URI 發出要求，擷取與觸發事件相關聯的中繼資料。

API 會遵循重新導向網址。廣告技術伺服器回應應包含名為 Attribution-Reporting-Register-Trigger 的 HTTP 標頭，代表一或多個已登錄觸發事件的相關資訊。這個標頭的內容應採用 JSON 編碼，並包含下列欄位：

  • 觸發事件資料：用於識別觸發事件的資料 (點擊事件為 3 位元，觀看事件為 1 位元)，必須是採字串格式的 64 位元帶正負號整數。

  • 觸發事件優先順序 (選填)：代表在相同的歸因來源中，此觸發事件與其他觸發事件的優先順序比較。必須是採字串格式的 64 位元帶正負號整數。如要進一步瞭解優先順序如何影響報表，請參閱有關優先順序範例的章節。

  • 簡化鍵 (選填)：用於識別相同廣告技術平台為同一歸因來源重複登錄同一觸發事件的情況，必須是採字串格式的 64 位元帶正負號整數。

  • 匯總鍵 (選填)：一份字典清單，用於指定匯總鍵和應將值匯總的可匯總報表。

  • 匯總值 (選填)：為各個鍵做出貢獻的值數量清單。

  • 篩選器 (選填)：用於選擇性地篩選觸發事件或觸發事件資料。詳情請參閱本頁的「觸發事件篩選器」一節。

您可以視需要在廣告技術伺服器回應中，提供「Attribution Reporting Redirects」標頭中的額外資料。這項資料包含重新導向網址，可讓多項廣告技術登錄一項要求。

多項廣告技術可以登錄同一觸發事件，方法是使用 Attribution-Reporting-Redirect 欄位中的重新導向，或是多次呼叫 registerTrigger() 方法。建議您使用「簡化鍵」欄位，避免相同廣告技術針對同一觸發事件提供多個回應，導致報表中出現重複的觸發事件。進一步瞭解使用簡化鍵的方式和時機。

如需接受觸發事件登錄的範例，請參閱開發人員指南。

以下是範例工作流程所含的步驟：

  1. 廣告技術 SDK 呼叫 API，使用預先註冊的 URI 啟動觸發事件登錄作業。詳情請參閱「註冊 Privacy Sandbox 帳戶」一文。

    registerTrigger(
    Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));

  2. API 向 https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA 發出要求。

  3. 廣告技術的 HTTPS 伺服器使用包含下列內容的標頭進行回應：

    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{
    "trigger_data": "1122",
    // This returns 010 for click-through conversions (CTCs) and 0 for
    // view-through conversions (VTCs) in reports
    "priority": "3",
    "deduplication_key": "3344"
    }],
}
Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567

  4. API 向 Attribution-Reporting-Redirect 中指定的每個網址發出要求。這個範例只指定一個網址，因此 API 會向 https://adtechpartner.example?app_install=567 發出要求。

  5. 廣告技術的 HTTPS 伺服器使用包含下列內容的標頭進行回應：

    Attribution-Reporting-Register-Trigger: {
"event_trigger_data":[{
  "trigger_data": "5566",
  "priority": "3",
  "deduplication_key": "3344"
}]
}

    根據上述步驟中的要求，系統會登錄兩個觸發事件。

歸因功能

以下各節將說明 Attribution Reporting API 如何比對轉換觸發事件和歸因來源。

已套用來源優先歸因演算法

Attribution Reporting API 採用「來源優先歸因演算法」，將觸發事件 (轉換) 對應至歸因來源。

優先順序參數可讓您自訂來源的觸發事件歸因方式：

  • 您可以將觸發事件歸因至特定的廣告事件。舉例來說，您可以選擇著重在點擊次數而非觀看次數，或把重點放在特定廣告活動的事件。
  • 您可以設定歸因來源和觸發事件的頻率限制，當系統發現達到設置標準時，傳送過來的報表或許較能貼合個人需求。例如，您可能比較希望在報表中看到出價轉換或高價值轉換等資料。

如果有多個廣告技術登錄某一歸因來源 (詳見本頁後續章節)，系統會為每個廣告技術分別進行歸因，並將觸發事件歸因至優先順序最高的歸因來源。如果有多個歸因來源的優先順序都相同，API 會選擇最後登錄的歸因來源。其他未獲選的歸因來源都會遭到捨棄，日後無法再用於觸發事件歸因作業。

觸發條件篩選器

來源和觸發事件登錄包含額外的選用功能，可執行下列操作：

  • 選擇性篩選並可有效忽略部分觸發事件。
  • 根據來源資料選擇事件層級報表的觸發事件資料。
  • 選擇要在事件層級報表中排除的觸發事件。

如要選擇性篩選觸發事件，廣告技術可在登錄來源和觸發事件時指定篩選資料，包括鍵和值。如果您同時為來源和觸發事件指定相同的鍵，則當兩者的交集為空白時，系統就會忽略觸發事件。舉例來說，來源可指定 "product": ["1234"]，其中 product 為篩選器索引鍵，而 1234 則是值。如果觸發事件篩選器設為 "product": ["1111"]，則系統會忽略觸發事件。如果沒有符合 product 的觸發事件篩選器鍵，系統會忽略篩選器。

廣告技術平台可能希望選擇性篩選觸發事件的另一個情況，是要強制縮短過期時間。登錄觸發事件時，廣告技術可以指定從轉換發生時起的回溯期 (以秒為單位)。例如，7 天的回溯期會定義為："_lookback_window": 604800 // 7d

為了判斷篩選器是否相符，API 會先檢查回溯期。如果可以的話，自來源登錄以來的時間長度，必須小於或等於回溯期時間長度。

廣告技術平台也可以根據來源事件資料選擇觸發條件資料。舉例來說，source_type 會由 API 自動產生為 navigation 或 event。在觸發事件登錄期間，"source_type": ["navigation"] 和 "source_type": ["event"] 的 trigger_data 值可以設為不一樣。

如果發生下列任一情況，系統就會從事件層級報表中排除觸發事件：

  • 未指定 trigger_data。
  • 來源和觸發事件指定的篩選器索引鍵相同，但值不相符。請注意，在這個情況下，事件層級和可彙整報表都會忽略觸發事件。

安裝後歸因

在某些情況下，即使有其他符合資格且更近期發生的歸因來源，仍必須將安裝後觸發事件歸因至促成安裝的同一歸因來源。

為了支援這個使用情境，此 API 可讓廣告技術設定安裝後歸屬期：

  • 登錄歸因來源時，請指定預期會進行安裝的安裝歸屬期 (一般為 2 至 7 天，可接受的範圍為 1 至 30 天)。指定這個時間範圍時，應以秒數為單位。
  • 登錄歸因來源時，請指定安裝後歸因專屬期，在這個期間內，任何安裝後的觸發事件都應該要與引發安裝的歸因來源建立關聯 (一般為 7 至 30 天，可接受的範圍為 0 至 30 天)。指定這個時間範圍時，應以秒數為單位。
  • 發生應用程式安裝事件時，Attribution Reporting API 會進行驗證，並在內部將安裝事件歸因至來源優先的歸因來源。不過，該安裝事件不會傳送至廣告技術，也不會計入平台專屬的頻率限制配額。
  • 所有下載的應用程式都可以進行應用程式安裝驗證。
  • 日後如果在安裝後歸屬期內發生觸發事件，系統會將這些事件做為經過驗證的安裝事件，歸因至同一歸因來源 (前提是該歸因來源必須符合資格)。

未來我們可能會嘗試延伸這項設計，支援更進階的歸因模式。

下表舉例說明廣告技術可能會如何使用安裝後歸因。這裡假設所有歸因來源和觸發事件都是由相同的廣告技術聯播網登錄，且所有優先順序都相同。

事件 事件發生日期 附註
點擊 1 1 install_attribution_window 設為 172800 (2 天)，而 post_install_exclusivity_window 設為 864000 (10 天)
已驗證的安裝行為 2 API 會在內部歸因已驗證安裝行為，但這些安裝行為不會視為觸發事件；所以此時不會傳送任何報表。
觸發事件 1 (初次開啟) 2 由廣告技術登錄的第一個觸發事件。在本範例中，這代表初次開啟，但可以是任何觸發事件類型。
歸因至點擊 1 (與已驗證安裝行為的歸屬功能相符)。
點擊 2 4 install_attribution_window 和 post_install_exclusivity_window 使用與點擊 1 相同的值
觸發事件 2 (安裝後) 5 由廣告技術登錄的第二個觸發事件。在本範例中，這代表安裝後轉換 (例如購買)。
歸因至點擊 1 (與已驗證安裝行為的歸屬功能相符)。
點擊 2 會遭到捨棄，且無法做為日後的歸因選項。

下列清單說明安裝後歸因的其他注意事項：

  • 如果沒有在 install_attribution_window 指定的天數內完成已驗證的安裝行為，系統就不會套用安裝後歸因。
  • 已驗證的安裝行為不會由廣告技術登錄，不會傳送至報表中，也不會計入廣告技術的頻率限制配額。已驗證的安裝行為只能用來識別安裝事件的歸因來源。
  • 在上表的範例中，觸發事件 1 和觸發事件 2 分別代表初次開啟和安裝後轉換。然而，廣告技術平台可登錄任何類型的觸發事件。換句話說，第一個觸發事件不一定要是初次開啟的觸發事件。
  • 如果在 post_install_exclusivity_window 到期後登錄更多觸發事件，則點擊 1 在尚未過期且未達頻率限制的情況下，仍然符合歸因的資格。
    • 如果登錄優先順序較高的歸因來源，則點擊 1 可能仍會遺失或捨棄。
  • 如果廣告客戶應用程式解除安裝後又再度重新安裝，這個重新安裝動作就會計為一次新的已驗證安裝行為。
  • 但如果點擊 1 是瀏覽事件，則「初次開啟」和安裝後觸發事件仍會歸因於該事件。API 會將歸因限制為每次瀏覽一個觸發事件，但安裝後歸因則可允許每次瀏覽最多兩個觸發事件。在安裝後歸因的情況下，廣告技術可能會收到 2 個不同的報表回溯期 (2 天或來源到期時)。

支援所有應用程式和網頁式觸發路徑組合

Attribution Reporting API 可讓系統歸因在單一 Android 裝置上依下列觸發路徑發生的事件：

  • 應用程式至應用程式：使用者在應用程式中看到廣告，然後在該應用程式或其他已安裝的應用程式中完成轉換。
  • 應用程式至網頁：使用者在應用程式中看到廣告，然後在行動瀏覽器或應用程式瀏覽器中完成轉換。
  • 網頁至應用程式：使用者在行動瀏覽器或應用程式瀏覽器中看到廣告，然後在應用程式中完成轉換。
  • 網頁至網頁：使用者在行動瀏覽器或應用程式瀏覽器中看到廣告，然後在同一裝置上的相同瀏覽器或其他瀏覽器中完成轉換。

我們允許網路瀏覽器支援新的網頁曝光功能，例如與網頁版 Privacy Sandbox 的 Attribution Reporting API 類似的功能，這個 API 可呼叫 Android API 進行跨應用程式/跨網頁歸因作業。

瞭解廣告技術和應用程式必須做出哪些變更，才能支援跨應用程式和網頁成效評估的觸發路徑。

針對單一歸因來源優先處理多個觸發事件

單一歸因來源可能會產生多個觸發事件。舉例來說，單一購買流程可能牽涉到一個「應用程式安裝」觸發事件、一或多個「加入購物車」觸發事件，以及一個和「購買」觸發事件。根據來源優先歸因演算法，每個觸發事件都會歸因至一或多個歸因來源，詳情請參閱本頁後續內容。

可歸因至單一歸因來源的觸發事件有數量限制。詳情請參閱下方的「在歸因報表中查看評估資料」一節。

如果觸發事件的數量超過限制，建議導入優先順序邏輯，取得最有價值的觸發事件。舉例來說，廣告技術的開發人員可能希望讓「購買」觸發事件的優先順序高於「加入購物車」觸發事件。

如要支援這個邏輯，可以為觸發事件另外設定優先順序欄位。這樣一來，系統就會在指定報表回溯期內選擇優先順序最高的觸發事件，然後再套用限制。

允許多項廣告技術登錄歸因來源或觸發事件

多項廣告技術收到歸因報表的情況並不罕見，通常是為了執行跨聯播網簡化作業。因此，這個 API 可讓多項廣告技術登錄相同的歸因來源或觸發事件。廣告技術必須同時登錄歸因來源和觸發事件，才能接收來自 API 的回傳，而系統則會依據廣告技術使用該 API 登錄的歸因來源和觸發事件完成歸因作業。

如果廣告客戶想透過第三方執行跨聯播網簡化作業，可使用類似於下述內容的技巧繼續執行這項作業：

  • 設定內部伺服器以登錄及接收來自 API 的報表。
  • 繼續使用現有的行動裝置測量服務合作夥伴。

歸因來源

registerSource() 方法支援歸因來源重新導向：

  1. 呼叫 registerSource() 方法的廣告技術可在回應中提供額外的 Attribution-Reporting-Redirect 欄位，代表合作夥伴廣告技術的重新導向網址組合。
  2. 接著，API 會呼叫重新導向網址，讓合作夥伴的廣告技術能夠登錄歸因來源。

Attribution-Reporting-Redirect 欄位中可以列出多個合作夥伴廣告技術網址，且合作夥伴廣告技術不得指定自己的 Attribution-Reporting-Redirect 欄位。

這個 API 也可讓不同的廣告技術各自呼叫 registerSource()。

觸發事件

系統支援第三方透過類似的方法登錄觸發事件：廣告技術可以使用額外的 Attribution-Reporting-Redirect 欄位，也可以各自呼叫 registerTrigger() 方法。

如果廣告客戶使用多項廣告技術登錄同一觸發事件，則應使用「簡化鍵」。簡化鍵的作用，是針對由相同廣告技術平台登錄的相同事件，區分重複的回報記錄。舉例來說，廣告技術可讓 SDK 直接呼叫 API 來登錄觸發事件，並在另一個廣告技術呼叫的重新導向欄位中顯示其網址。如未提供簡化鍵，系統可能會將重複的觸發事件當做不重複事件回報給各項廣告技術。

處理重複的觸發事件

廣告技術可能會透過 API 多次登錄相同的觸發事件。這類情況包括：

  • 使用者多次執行相同動作 (觸發條件)。例如，使用者在相同報表期間多次瀏覽同一產品。
  • 廣告客戶應用程式使用多個 SDK 進行轉換評估，且全部重新導向至同一個廣告技術。舉例來說，廣告客戶應用程式使用了兩個成效評估合作夥伴 (以下稱為 MMP #1 和 MMP #2)，兩個 MMP 都會重新導向至廣告技術 #3。當觸發事件發生時，兩個 MMP 都會透過 Attribution Reporting API 登錄這個觸發事件。這樣一來，廣告技術 #3 就會從同一個觸發事件收到兩個不同的重新導向，分別來自 MMP #1 和 MMP #2。

在上述情況下，您可以透過幾種方式隱藏重複觸發事件的事件層級報表，降低超過事件層級報表適用頻率限制的可能性。建議的做法是使用簡化鍵。

建議做法：簡化鍵

建議做法是由廣告客戶應用程式將專屬的簡化鍵，傳遞給用於轉換評估的廣告技術或 SDK。轉換發生時，應用程式會將簡化鍵傳送至廣告技術或 SDK。接著，這些廣告技術或 SDK 會使用 Attribution-Reporting-Redirect 所指定網址的參數，將簡化鍵傳遞至重新導向。

廣告技術可以選擇只登錄第一個含有指定簡化鍵的觸發事件，也可以選擇登錄多個或所有觸發事件。廣告技術可以在登錄重複的觸發事件時指定 deduplication_key。

如果廣告技術使用相同的簡化鍵和歸因來源登錄多個觸發事件，系統只會將第一個登錄的觸發事件傳送至事件層級報表。重複的觸發事件仍會傳送至已加密的可匯總報表。

替代方法：廣告技術同意為個別廣告主採用不同觸發條件類型

如果廣告技術不希望使用簡化鍵，或者廣告客戶應用程式無法傳遞簡化鍵，系統會提供替代選項。為特定廣告客戶評估轉換的所有廣告技術必須一起合作，為每個廣告客戶定義不同的觸發事件類型。

啟動觸發事件登錄呼叫的廣告技術 (例如 SDK) 會在 Attribution-Reporting-Redirect 所指定網址中加入參數，例如 duplicate_trigger_id。這個 duplicate_trigger_id 參數可以包含 SDK 名稱和該廣告客戶的觸發條件類型等資訊。這樣一來，廣告技術就能將一部分的重複觸發事件傳送到事件層級報表。廣告技術也可以在匯總鍵中加入這個 duplicate_trigger_id。

跨聯播網歸因範例

在本節所述的範例中，廣告客戶使用了兩個廣告放送技術平台 (廣告技術 A 和廣告技術 B) 和一個成效評估合作夥伴 (MMP)。

首先，廣告技術 A、廣告技術 B 和 MMP 都必須完成註冊，才能使用 Attribution Reporting API。詳情請參閱「註冊 Privacy Sandbox 帳戶」一文。

下列清單提供了一系列假設的使用者動作 (每天發生一個)，以及 Attribution Reporting API 如何處理廣告技術 A、廣告技術 B 和 MMP 的此類動作：

第 1 天：使用者點選廣告技術 A 放送的廣告

廣告技術 A 使用自己的 URI 呼叫 registerSource()。API 向 URI 發出要求，系統使用廣告技術 A 伺服器回應的中繼資料登錄該點擊事件。

廣告技術 A 也在 Attribution-Reporting-Redirect 標頭中加入 MMP 的 URI。API 向 MMP 的 URI 發出要求，系統使用 MMP 伺服器回應的中繼資料登錄該點擊事件。

第 2 天：使用者點選廣告技術 B 放送的廣告

廣告技術 B 使用自己的 URI 呼叫 registerSource()。API 向 URI 發出要求，系統使用廣告技術 B 伺服器回應的中繼資料登錄該點擊事件。

與廣告技術 A 一樣，廣告技術 B 也在 Attribution-Reporting-Redirect 標頭中加入 MMP 的 URI。API 向 MMP 的 URI 發出要求，系統使用 MMP 伺服器回應的中繼資料登錄該點擊事件。

第 3 天：使用者瀏覽廣告技術 A 放送的廣告

API 的回應方式與第 1 天相同，唯一差別在於系統登錄了廣告技術 A 和 MMP 兩者的瀏覽事件。

第 4 天：使用者安裝應用程式，該應用程式使用 MMP 進行轉換評估

MMP 使用自己的 URI 呼叫 registerTrigger()。API 向網址發出要求，系統使用 MMP 伺服器回應的中繼資料登錄該轉換事件。

MMP 也在 Attribution-Reporting-Redirect 標頭中加入廣告技術 A 和廣告技術 B 的 URI。API 向廣告技術 A 和廣告技術 B 的伺服器發出要求，系統使用伺服器回應的中繼資料相應地登錄該轉換事件。

下圖說明上述清單所述的程序：

示例：Attribution Reporting API 如何回應一系列使用者動作。

歸因的運作方式如下：

  • 廣告技術 A 將點擊動作的優先順序設為高於瀏覽動作，因此將安裝事件歸因於第 1 天的點擊。
  • 廣告技術 B 將安裝事件歸因於第 2 天的點擊。
  • MMP 將點擊動作的優先順序設為高於瀏覽動作，將安裝事件歸因於第 2 天的點擊。第 2 天的點擊是優先級最高、最近期的廣告事件。

不含重新導向的跨聯播網歸因

雖然我們建議利用重新導向讓多個廣告技術登錄歸因來源和觸發事件，但在某些情況下，重新導向功能會無法使用。本節將詳細說明如何在不重新導向的情況下，支援跨聯播網歸因。

高階流程

  1. 登錄來源時，廣告放送技術聯播網會共用來源匯總鍵。
  2. 登錄觸發事件時，廣告客戶或評估服務合作夥伴會選擇要使用的來源端鍵，並指定其歸因設定。
  3. 歸因取決於歸因設定、共用鍵，以及由該廣告客戶或評估服務合作夥伴實際登錄的任何來源 (例如其他已啟用重新導向功能的廣告放送技術聯播網)。
  4. 如果觸發條件是來自非重新導向廣告放送技術的來源，廣告客戶或評估服務合作夥伴就能收到可匯總報表，其中結合了步驟 2 中定義的來源和觸發條件鍵。

登錄來源

登錄來源時，廣告放送技術聯播網可以選擇共用全部或部分的來源匯總鍵，而非使用重新導向。廣告放送廣告技術不必在自己的可匯總報表中實際使用這些來源鍵，也只能代表廣告客戶或成效評估合作夥伴宣告這些來源鍵 (如有需要)。

向同一廣告客戶登錄觸發事件的所有廣告技術都能使用共用匯總鍵，但廣告放送技術和觸發評估廣告技術將一同決定需要哪些類型的匯總鍵、名稱，以及如何將匯總鍵解碼為可讀取的維度。

登錄觸發事件

登錄觸發事件時，成效評估廣告技術會選擇要為各觸發鍵套用哪些來源端鍵，包括透過廣告放送技術共用的任何來源鍵。

此外，成效評估廣告技術也必須透過新的歸因分析設定 API 呼叫，指定刊登序列歸因邏輯。在此設定中，廣告技術可以指定來源優先順序、到期時間，以及廣告技術無法查看的來源 (例如未使用重新導向的來源) 所要採用的篩選器。

歸因

Attribution Reporting API 會根據歸因設定、共用鍵及所登錄的來源，為成效評估廣告技術執行來源優先的最終接觸歸因。例如：

  • 使用者點選廣告技術 A、B、C 和 D 放送的廣告。接著，使用者安裝了廣告客戶的應用程式，該應用程式使用成效評估廣告技術合作夥伴 (MMP)。
  • 廣告技術 A 將來源重新導向到 MMP。
  • 廣告技術 B 和 C 不會重新導向，而是共用匯總鍵。
  • 廣告技術 D 並未重新導向，也不共用匯總鍵。

MMP 會登錄廣告技術 A 的來源，並定義包含廣告技術 B 和廣告技術 D 的歸因設定。

MMP 的歸因分析現在包含以下廣告技術：

  • 廣告技術 A，因為 MMP 已登錄該廣告技術重新導向的來源。
  • 廣告技術 B，因為廣告技術 B 共用鍵，MMP 也已將廣告技術 B 納入歸因設定。

MMP 的歸因分析不含以下廣告技術：

  • 廣告技術 C，因為 MMP 並未在歸因設定中納入這個廣告技術。
  • 廣告技術 D，因為此廣告技術並未重新導向，也未共用匯總鍵。

偵錯

為了在不重新導向的情況下支援跨聯播網歸因偵錯，廣告技術可以在來源登錄時設定額外欄位 shared_debug_key。如果在原始來源登錄時設定該欄位，那麼系統也會在觸發事件登錄期間，在相應的衍生來源上將此欄位設為 debug_key，藉此支援不含重新導向的跨聯播網歸因。這個偵錯金鑰會以 source_debug_key 的形式附加在事件和匯總報表中。

這項偵錯功能必須要在下列情況中，才適用於不含重新導向的跨聯播網歸因：

  • 應用程式至應用程式的成效評估 (廣告 ID 獲得允許)
  • 應用程式至網頁的成效評估 (廣告 ID 得允許，且同時在應用程式來源和網頁觸發事件間比對)
  • 網頁至網頁的成效評估 (在同一個瀏覽器應用程式中；來源和觸發事件都含有 ar_debug`

索引鍵探索功能 (適用於不含重新導向的跨聯播網歸因)

索引鍵探索功能旨在提供簡化的方式，讓廣告技術人員 (通常是 MMP) 實作自身的屬性設定，以利在一或多個廣告放送技術人員使用共用匯總鍵時支援跨聯播網歸因 (如上方「不含重新導向的跨聯播網歸因」所述)。

如果 MMP 查詢匯總服務，針對包含衍生來源的廣告活動產生摘要報表，匯總服務就會要求 MMP 將可能的索引鍵清單指定為匯總工作的輸入內容。在某些情況下，潛在來源匯總鍵清單的大小可能非常大，也可能無從得知。大型的潛在鍵清單會很難追蹤，處理起來可能相當複雜且成本高昂。請參考以下例子：

  • 如果所有潛在鍵清單的大小都很大：
    • 廣告放送聯播網會執行複雜的獲客計畫，例如含有 20 個廣告活動，底下各有 10 個廣告群組，且每個廣告群組都有 5 個廣告素材，每週會根據成效更新。
  • 如果所有潛在鍵清單的大小都無從得知：
    • 廣告放送聯播網會在多個行動應用程式中放送廣告，但發布商應用程式 ID 的完整清單在廣告活動發布時仍無從得知。
    • 廣告主會在數個廣告放送聯播網上工作，這些廣告放送聯播網在來源登錄時不會重新導向至 MMP，但都各有不同的鍵結構和值，這些值可能不會事先與 MMP 共用。

有了索引鍵探索功能後：

  • 匯總服務不再需要完整列舉潛在的匯總鍵。
  • MMP 不必指定潛在鍵的完整清單，可改為建立一個空白 (或部分空白) 的鍵集並設定閾值，讓輸出內容中僅包含值超過閾值的 (未預先宣告) 鍵。
  • MMP 會收到摘要報表，其中含有貢獻值大於設定閾值的鍵雜訊值。報表中也可能包含沒有相關實際使用者貢獻、且純粹為雜訊的鍵。
  • MMP 會在觸發事件登錄時使用 x_network_bit_mapping 欄位，藉此判斷哪個廣告技術人員對應至哪個鍵。
  • 接著，MMP 即可與適當的廣告放送技術人員聯絡，瞭解來源鍵中的值。

簡單來說，索引鍵探索功能可讓 MMP 不必事先得知匯總鍵就能取得，避免因處理大量來源鍵而產生額外雜訊。

串連重新導向

廣告技術可以在來源或觸發事件登錄 HTTPS 伺服器回應中提供多個 Attribution-Reporting-Redirect 標頭，藉此使用歸因報表 API 透過單一登錄 API 呼叫執行多個來源和觸發事件登錄作業。

在伺服器回應中，廣告技術也可以包含單一 Location (302 重新導向) 標頭，其中包含網址，進而導向至其他登錄，最多可達設定的限制。

這兩種標頭皆為選用項目，如果不需要重新導向，則可以不提供。您可以提供其中一種或兩種標頭。來源和觸發事件登錄要求 (包括重新導向) 會在網路發生錯誤時重試。為避免對裝置造成重大影響，每項要求的重試次數都會限制在固定數字。

瀏覽器使用的 registerWebSource 和 registerWebTrigger 不接受重新導向。詳情請參閱跨網站和應用程式導入指南。

在歸因報表中查看評估資料

Attribution Reporting API 可支援產生下列類型的報表 (詳情請參閱本頁後續章節)：

  • 事件層級報表：將特定歸因來源 (點擊或瀏覽) 與有限位元的高精確度觸發事件資料建立關聯。
  • 可匯總報表：不一定與特定歸因來源有關聯。相較於事件層級報表，這類報表提供更豐富、更精確的觸發事件資料，但這些資料只會以匯總形式提供。

這兩種報表相輔相成，並可同時使用。

事件層級報表

將某個觸發事件歸因至歸因來源後，系統就會產生事件層級報表，並將報表儲存在裝置上，直到可在其中一個報表傳送期 (詳見本頁後續章節)，將報表回傳至各廣告技術的回傳網址。

如果只需要少量的觸發事件相關資訊，事件層級報表會相當實用。事件層級觸發事件資料有大小上限。如果是點擊 (也就是說，觸發事件可獲派八個類別的其中一類)，上限為 3 位元；如果是瀏覽，則為 1 位元。此外，事件層級報表不支援將高精確度觸發事件端資料 (例如特定價格或觸發時間) 進行編碼。由於歸因發生在裝置端，因此事件層級報表無法支援跨裝置分析作業。

事件層級報表包含多種資料，例如：

  • 目的地：發生觸發事件的廣告客戶應用程式套件名稱或 eTLD+1
  • 歸因來源 ID：用於登錄歸因來源的歸因來源 ID
  • 觸發條件類型：1 或 3 位元的低精確度觸發條件資料 (視歸因來源類型而定)

適用於所有報表的隱私保護機制

系統會先考量歸因來源和觸發事件的優先順序，再套用下列限制。

廣告技術數量限制

可透過 API 登錄或接收報表的廣告技術有數量限制，目前的提案如下：

  • {每個來源應用程式、每個目的地應用程式、每 30 天、每部裝置} 100 個含有歸因來源的廣告技術。
  • {每個來源應用程式、每個目的地應用程式、每 30 天、每部裝置} 10 個含有已歸因觸發事件的廣告技術。
  • 20 個可透過 Attribution-Reporting-Redirect 登錄單一歸因來源或觸發事件的廣告技術。

不重複目的地的數量限制

這些限制會查詢大量應用程式，瞭解特定使用者的應用程式使用行為，避免一系列廣告技術輕易共謀。

  • 針對所有已註冊的來源，以及所有廣告技術，API 每分鐘對每個來源應用程式最多支援 200 個不重複目的地。
  • 針對所有已註冊的來源，以及單一廣告技術，API 每分鐘對每個來源應用程式最多支援 50 個不重複目的地。這項限制可避免單一廣告技術用盡前述頻率限制中的全部預算。

過期的來源不會計入頻率限制。

每天每個來源應用程式只能有一個報表來源

在同一天內對指定裝置而言，指定的廣告技術平台只能利用單一報表來源在發布商應用程式上登錄來源。這項頻率限制可避免廣告技術濫用多個報表來源，而存取額外的隱私預算。

不妨設想以下情況：單一廣告技術想要使用多個報表來源，為單一裝置在發布商應用程式中登錄來源。

  1. 廣告技術 A 的報表來源 1 在應用程式 B 上登錄了來源
  2. 12 小時後，廣告技術 A 的報表來源 2 嘗試在應用程式 B 上登錄來源

第二個來源 (廣告技術 A 的報表來源 2) 會遭到 API 拒絕。廣告技術 A 的報表來源 2 必須等到隔天，才能在相同裝置的應用程式 B 上成功登錄來源。

等待期和頻率限制

為限制 {來源、目的地} 配對之間的使用者身分洩漏數量，API 會限制在指定時間範圍內傳送的使用者資訊總量。

在目前的提案中，每項廣告技術的限制為 {每個來源應用程式、每個目的地應用程式、每 30 天、每部裝置} 100 個已歸因觸發事件。

不重複目的地數量

API 會限制廣告技術可評估的目的地數量。此限制越低，廣告技術就越難使用 API 評估與所顯示廣告無關的使用者瀏覽活動。

在目前的提案中，每個廣告技術可根據每個來源應用程式，擁有最多 100 個具有未過期來源的不重覆目的地。

適用於事件層級報表的隱私權保護機制

觸發條件資料的受限精確度

這個 API 提供 1 位元的瀏覽後轉換觸發事件資料和 3 位元的點閱觸發事件資料。歸因來源仍繼續支援完整的 64 位元中繼資料。

為了配合事件層級報表的可用位元數限制，請評估是否要減少觸發事件所透露的資訊量，以及實際的減少方式。

差異化隱私雜訊架構

這個 API 的目標之一，是要使用經過 k 隨機化的回應，為每個來源事件產生加入了雜訊的輸出結果，藉此讓事件層級評估作業符合地方的差異化隱私規範。

無論是否有如實回報歸因來源事件，系統都會套用雜訊。系統在裝置上登錄歸因來源時，有 $ p $ 的機率會以正常的方式登錄，並有 $ 1-p $ 的機率會由裝置從所有可能的 API 輸出狀態中隨機選擇 (包括完全不回報任何內容，或是回報多個假內容)。

k 隨機化回應是一種演算法，在滿足以下等式時具有「ε 差異化隱私」特性：

\[ p = \frac{k}{k + e^ε - 1} \]

如果 ε 的值較低，實際輸出結果會受到 k 隨機化回應機制保護。確切的雜訊參數尚未定案，我們日後會再根據反饋以及以下現行提案內容進行調整：

  • 導航來源 p=0.24%
  • 事件來源 p=0.00025%

可用觸發事件 (轉換) 的相關限制

每個歸因來源的觸發事件有數量限制，目前的提案如下：

  • 廣告瀏覽歸因來源為 1 至 2 個觸發事件 (只有在安裝後歸因的情況下才能有 2 個觸發事件)
  • 點擊廣告歸因來源為 3 個觸發事件

特定的報表傳送期 (預設行為)

廣告瀏覽歸因來源的事件層級報表會在來源到期時間的 1 小時後傳送。到期日可自行設定，但不能短於 1 天或超過 30 天。如果兩個觸發事件都歸因至廣告瀏覽歸因來源 (透過安裝後歸因)，系統可能會按照下方指定的報表回溯期間隔傳送事件層級報表。

廣告點擊歸因來源的事件層級報表無法自行設定，並會於來源到期前或到期時，在與來源登錄時間相對的指定時間點傳送。歸因來源和到期日之間的時間會分成多個報表回溯期。每個報表回溯期都有期限 (從歸因來源時間開始)。在每個報表回溯期結束時，裝置會收集自上一個報表回溯期起發生的所有觸發事件，並傳送已排定的報表。這個 API 支援下列報表回溯期：

  • 2 天：裝置會收集歸因來源登錄後最多 2 天內發生的所有觸發事件。報表會在歸因來源登錄時間的 2 天又 1 小時後傳送。
  • 7 天：裝置會收集歸因來源登錄後 2 到 7 天內發生的所有觸發事件。報表會在歸因來源登錄時間的 7 天又 1 小時後傳送。
  • 自訂時間長度：由歸因來源的「到期時間」屬性定義。報表會在指定到期時間的 1 小時後傳送。這個值不得短於 1 天或超過 30 天。

彈性事件層級設定

所謂事件層級報表的預設設定，是指廣告技術展開實用性測試時，建議開始使用的設定，但此預設設定不一定適合所有用途。Attribution Reporting API 支援更為彈性的選用設定，讓廣告技術人員能進一步掌控事件層級報表的結構，並盡可能提高資料的實用性。

Attribution Reporting API 將分兩階段導入此額外的彈性特質：

  • 第 1 階段：精簡彈性事件層級設定
    • 這個版本提供完整功能的子集，且可在第 2 階段外獨立使用。
  • 第 2 階段：彈性事件層級設定的完整版本

第 1 階段 (精簡彈性事件層級) 的用途如下：

  • 指定報表回溯期的數量，藉此更動回報頻率
  • 更動每項來源登錄作業的歸因數量
  • 減少上述參數，降低雜訊總量
  • 設定報表回溯期，而非使用預設設定

第 2 階段 (完整彈性事件層級) 可用於執行第 1 階段中的所有功能，以及：

  • 在報表中更改觸發事件資料基數
  • 減少觸發事件資料基數，降低雜訊總量

減少預設設定的一個維度，可讓廣告技術增加另一個維度。或者，您可以減少上述參數的淨額，這樣事件層級報表中的雜訊總量或許也能降低。

除了可根據廣告技術人員選取的設定，以動態方式指定雜訊層級，我們也會設定一些參數限制，避免運算成本過高並帶來輸出狀態過多 (雜訊會大量增加) 的設定。以下提供一組限制範例。歡迎您對 [設計提案][50]提供意見：

  • 全域和個別 trigger_data 的報表總數不得超過 20 份
  • 每個 trigger_data 的報表回溯期不得超過 5 個
  • 觸發事件資料基數不得超過 32 個 (不適用於第 1 階段：精簡彈性事件層級)

廣告技術人員開始使用這項功能時，請注意使用上述極值可能產生大量雜訊，也可能無法在不符隱私權層級的情況下登錄。

可匯總報表

使用可匯總報表之前，請務必先設定您的雲端帳戶並開始接收可匯總報表。

可匯總報表也能提供裝置收集到的觸發事件資料，但精確度更高、速度更快，涵蓋內容也比事件層級報表更多。這類高精確度資料只能透過「匯總」提供，且不會與特定觸發事件或使用者建立關聯。匯總鍵的大小上限為 128 位元；這讓可匯總報表能夠支援多種報表使用情境，例如：

  • 製作觸發事件值 (例如收益) 報表
  • 處理更多觸發事件類型

此外，可匯總報表會使用與事件層級報表相同的來源優先歸因邏輯，但支援將多筆轉換歸因於單一點擊或瀏覽。

Attribution Reporting API 準備及傳送可匯總報表方式的整體設計如下 (如圖所示)：

  1. 裝置將已加密的可匯總報表傳送至廣告技術。在實際工作環境中，廣告技術無法直接使用這些報表。
  2. 廣告技術傳送一批可匯總報表至匯總服務進行匯總。
  3. 匯總服務讀取一批可匯總報表、解密內容並進行匯總。
  4. 最終匯總結果將以匯總報表的形式傳回廣告技術。
Attribution Reporting API 準備及傳送可匯總報表的流程。

可匯總報表包含下列歸因來源相關資料：

  • 目的地：發生觸發事件的應用程式套件名稱或 eTLD+1 網址。
  • 日期：歸因來源所代表事件的發生日期。
  • 酬載：以經過加密的鍵/值組合形式收集的觸發事件值，用於在受信任的匯總服務中計算匯總結果。

匯總服務

下列服務提供資料匯總功能，並可防範不當的匯總資料存取行為。

這些服務是由各方管理，詳情請參閱本頁後續內容：

  • 廣告技術只應部署匯總服務。
  • 金鑰管理服務和可匯總報表計算服務是由稱為「協調者」的受信任方執行。這些協調者會驗證用於執行匯總服務的程式碼是否為 Google 提供的公開程式碼，且所有匯總服務使用者都套用相同的金鑰和可匯總報表計算服務。
匯總服務

廣告技術平台必須預先部署以 Google 提供的二進位檔為基礎的「匯總服務」。

這項匯總服務會在雲端代管的受信任執行環境 (TEE) 中運作。TEE 可提供下列安全性優點：

  • 確保在 TEE 中執行的程式碼是 Google 提供的特定二進位檔。除非符合這項條件，否則匯總服務無法存取運作所需的解密鍵。
  • 可確保執行程序安全無虞，不受外部監控或竄改。

上述安全性優勢可讓匯總服務更安全地執行敏感作業，例如存取加密資料。

如要進一步瞭解匯總服務的設計、工作流程和安全性注意事項，請參閱 GitHub 的匯總服務文件。

金鑰管理服務

這項服務會驗證匯總服務執行的是否為獲得核准的二進位檔版本，然後在廣告技術中為匯總服務提供針對觸發事件資料的正確解密金鑰。

可匯總報表計算

這項服務會追蹤廣告技術的匯總服務存取特定觸發事件 (可能包含多個匯總鍵) 的頻率，並設下適當的解密次數限制。詳情請參閱「Attribution Reporting API 匯總服務」設計提案。

Aggregatable Reports API

這個 API 會為可匯總報表提供內容，並使用為事件層級報表登錄歸因來源時所用的相同基礎 API。以下各節說明這個 API 的延伸功能。

登錄可匯總來源資料

當 API 向歸因來源 URI 發出要求時，廣告技術可登錄名稱為 histogram_contributions 的匯總鍵清單，以 HTTP 標頭 Attribution-Reporting-Register-Source 中稱為 aggregation_keys 的新欄位 (鍵為 key_name，值為 key_piece) 進行回應：

  • (鍵) 鍵名稱：鍵名稱的字串。可做為合併鍵與觸發事件端鍵結合，藉此形成最終鍵。
  • 值索引鍵：索引鍵的位元字串值。

對這些觸發條件和觸發條件端項目執行二進位或運算時，最終直方圖區塊鍵會於觸發時間完整定義。

最終鍵的上限為 128 位元，超過的部分會遭到截斷。這表示 JSON 中的十六進位字串上限應為 32 位數字。

進一步瞭解匯總鍵的結構，以及如何設定匯總鍵。

在以下範例中，廣告技術會使用這個 API 收集下列資訊：

  • 廣告活動層級的匯總轉換次數
  • 地理區域層級的匯總購物價值
// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

登錄可匯總觸發事件

登錄觸發事件時要提供兩個額外欄位。

第一個欄位是用來在觸發事件端登錄匯總鍵清單。廣告技術應以 HTTP 標頭 Attribution-Reporting-Register-Trigger 中的 aggregatable_trigger_data 欄位回應，並為清單中的每個匯總鍵填入以下欄位：

  • 鍵：鍵的位元字串值。
  • 來源索引鍵：包含歸因來源端索引鍵名稱的字串清單，這些索引鍵應與觸發事件索引鍵結合，以形成最終索引鍵。

第二個欄位是用來登錄應為各個鍵做出貢獻的值清單。廣告技術應以 HTTP 標頭 Attribution-Reporting-Register-Trigger 中的 aggregatable_values 欄位回應。第二個欄位是用來登錄應為各個鍵做出貢獻的值清單，每個鍵可以是介於 $ [1, 2^{16}] $ 範圍內的整數。

每個觸發事件都可為可匯總報表貢獻多次。任何指定來源事件的貢獻總數會受到 $ L1 $ 參數的限制，該參數為特定來源的所有匯總鍵貢獻 (值) 總和上限。$ L1 $ 是指每個來源事件的直方圖貢獻 L1 敏感度度或範數。如果超過限制，系統就會自動捨棄後續貢獻。初始提案是將 $ L1 $ 設為 $ 2^{16} $ (65536)。

匯總服務中的雜訊會與這項參數成比例增加。因此，建議您根據分配到的 $ L1 $ 預算比例，妥善調整針對特定匯總鍵回報的值。這個做法可讓匯總報表在套用雜訊後盡可能保有高精確度。這項機制相當具有彈性，可支援許多匯總策略。

在以下範例中，系統會將 $ L1 $ 的貢獻分給 campaignCounts 和 geoValue，平均分配隱私預算：

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

上述範例會產生下列直方圖貢獻：

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

您可以反轉縮放比例係數，藉此取得正確的值，對套用的雜訊進行模數運算：

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

差異化隱私

這個 API 的一個目標，是提供可支援差異化隱私匯總評估作業的架構，實際做法為加入與 $ L1 $ 預算成比例的雜訊，例如採以下分布方式的雜訊：

\[ Laplace(\frac{L1}{ε}) \]

Protected Audience API 與 Attribution Reporting API 整合

藉由 Protected Audience 和 Attribution Reporting API 的跨 API 整合，廣告技術可評估各種再行銷策略的歸因成效，瞭解哪些類型的目標對象能帶來最高的投資報酬率。

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

  • 建立用於 1) 互動報表和 2) 來源登錄的 URI 鍵/值對應。
  • 在其來源端的鍵對應中加入 CustomAudience，取得匯總摘要報表 (使用 Attribution Reporting API)。

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

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

如要進一步瞭解如何在 Protected Audience 中啟用這項功能，請參閱「Protected Audience API 說明」中的相關章節。

登錄優先順序、歸因和報表範例

此範例說明一組使用者互動，以及廣告技術定義的歸因來源和觸發事件優先順序對歸因報表有何影響。在本範例中，假設有以下條件：

  • 所有歸因來源和觸發事件都是由相同的廣告客戶使用相同的廣告技術登錄。
  • 所有歸因來源和觸發事件皆發生於第一個事件報表回溯期內，即初次在發布商應用程式中顯示廣告後的 2 天內。

假設使用者執行以下操作：

  1. 使用者看到廣告。廣告技術使用 API 登錄歸因來源，優先順序為 0 (瀏覽 #1)。
  2. 使用者看到廣告，登錄的優先順序為 0 (瀏覽 #2)。
  3. 使用者點選廣告，登錄的優先順序為 1 (點擊 #1)。
  4. 使用者在廣告客戶應用程式中轉換 (抵達到達網頁)。廣告技術使用 API 登錄觸發事件，優先順序為 0 (轉換 #1)。
    • 登錄觸發事件後，API 會先執行歸因作業，再產生報表。
    • 目前有 3 個歸因來源可用：瀏覽 #1、瀏覽 #2 和點擊 #1。API 會將此觸發事件歸因至點擊 #1，因為這是最高的優先順序，時間也最近。
    • 系統會捨棄瀏覽 #1 和瀏覽 #2，並且日後也不再符合歸因的資格。
  5. 使用者在廣告客戶應用程式的購物車中加入一件商品，系統以 1 的優先順序登錄 (轉換 #2)。
    • 點擊 #1 是唯一符合資格的歸因來源。API 會將此觸發事件歸因於點擊 #1。
  6. 使用者在廣告客戶的應用程式中加入了一件商品，並以 1 的優先順序登錄 (轉換 #3)。
    • 點擊 #1 是唯一符合資格的歸因來源。API 會將此觸發事件歸因於點擊 #1。
  7. 使用者在廣告主應用程式的購物車中加入一件商品，系統以 1 的優先順序登錄 (轉換 #4)。
    • 點擊 #1 是唯一符合資格的歸因來源。API 會將此觸發事件歸因於點擊 #1。
  8. 使用者在廣告客戶應用程式中進行購買，並以 2 的優先順序登錄 (轉換 #5)。
    • 點擊 #1 是唯一符合資格的歸因來源。API 會將此觸發事件歸因於點擊 #1。

事件層級報表具有以下特點：

  • 根據預設，前 3 個歸因於點擊和第一個歸因於瀏覽的觸發事件，都會在適用的報表回溯期之後傳送。
  • 在報表回溯期內，如果登錄的觸發事件優先順序較高，系統會優先採用這些觸發事件，並取代最新的觸發事件。
  • 就上述範例而言，廣告技術會在 2 天的報表回溯期後收到的 3 個事件報表，分別來自轉換 #2、轉換 #3 和轉換 #5。
    • 這 5 個觸發事件都歸因於點擊 #1。根據預設，API 會傳送前 3 個觸發事件的報表：轉換 #1、轉換 #2 和轉換 #3。
    • 但轉換 #4 的優先順序 (1) 比轉換 #1 (0) 高。於是轉換 #4 的事件報表便取代轉換 #1 的事件報表並送出。
    • 此外，轉換 #5 的優先順序 (2) 比任何其他觸發事件都要來得高。轉換 #5 的事件報表便取代了轉換 #4 的報表。

可匯總報表具有以下特性：

  • 系統會在登錄觸發事件的幾個小時內，待可匯總報表處理完畢後，立即將已加密的報表傳送給廣告技術。

    廣告技術可以根據可匯總報表中未加密的資訊建立批次。這些資訊包含在可匯總報表的 shared_info 欄位中，包括時間戳記和報表來源。您無法依據匯總鍵/值組合中的任何加密資訊進行批次處理。您可以採用一些簡單策略，每天或每週為報表執行批次作業。在理想情況下，批次應至少包含 100 份報表。

  • 可匯總報表執行批次作業及傳送至匯總服務的時機和方式，取決於廣告技術。

  • 與事件層級報表相比，經過加密的可匯總報表可將更多觸發事件歸因至單一來源。

  • 在上述範例中，系統會傳送 5 份可匯總報表，每個已登錄的觸發事件各一份。

轉換偵錯報表

如要在不使用跨應用程式 ID 的情況下進行歸因評估，Attribution Reporting API 是相當複雜的新方法。有鑑於此，我們支援一種轉換機制，讓您在「廣告 ID 可用」時 (例如使用者未透過廣告 ID 選擇停用個人化功能，而發布商或廣告客戶應用程式已宣告廣告 ID 權限) 進一步瞭解歸因報表。這可確保 API 在推出過程中能獲得充分瞭解、協助清除任何錯誤，並更輕鬆地與廣告 ID 型替代方案比較成效。偵錯報表有兩種，分別是歸因成功報表和詳細報表。

請參閱轉換偵錯報表指南，進一步瞭解採用「應用程式至網頁」和「網頁至應用程式」評估結果的偵錯報表。

歸因成功偵錯報表

來源和觸發事件登錄作業都會接受新的 64 位元 debug_key 欄位 (格式為字串)，並由廣告技術人員填入資料。source_debug_key 和 trigger_debug_key 在傳遞至事件層級和匯總報表時皆維持不變。

如果同時透過來源和觸發偵錯金鑰建立報表，重複的偵錯報表會在有限的延遲時間內傳送至 .well-known/attribution-reporting/debug/report-event-attribution 端點。偵錯報表與一般報表相同，包含兩個偵錯金鑰欄位。在這兩份報表中加入這些金鑰，可將一般報表與獨立的偵錯報表串流彙整在一起。

  • 針對事件層級報表：
    • 重複的偵錯報表會在有限的延遲時間內傳送，因此不受可用觸發事件的限制所阻斷，可讓廣告技術瞭解這些限制對事件層級報表的影響。
    • 與假觸發事件相關聯的事件層級報表不會有 trigger_debug_key。如此一來，廣告技術就能進一步瞭解 API 套用雜訊的方式。
  • 針對可匯總報表：
    • 只有在 source_debug_key 和 trigger_debug_key 皆已設定的情況下，我們才會支援新的 debug_cleartext_payload 欄位 (其中包含已解密的酬載)。

詳細偵錯報表

開發人員可以使用詳細偵錯報表，監控歸因來源或觸發事件登錄作業中的特定失敗情形。等到歸因來源或觸發事件登錄之後，這些偵錯報表會在有限的延遲時間內傳送至 well-known/attribution-reporting/debug/verbose 端點。

每份詳細報表都包含以下欄位：

  • 類型：產生報表的原因。請參閱詳細報表類型的完整清單。
    • 一般而言，會有來源詳細報表和觸發事件詳細報表。
    • 系統必須要有廣告 ID，才能為發布商應用程式提供來源詳細報表，也才能為廣告客戶應用程式提供觸發事件詳細報表。
    • 觸發事件詳細報表 (trigger-no-matching-source 除外) 可以視需要加入 source_debug_key。只有在發布商應用程式也有可用的廣告 ID 時，才能加入此鍵。
  • 主體：報表的主體，視報表類型而定。

廣告技術需要透過 Attribution-Reporting-Register_Source 和 Attribution-Reporting-Register-Trigger 標頭中的新 debug_reporting 字典欄位，選擇接收詳細偵錯報表。

  • 來源詳細報表只需要選擇啟用來源登錄標頭。
  • 觸發事件偵錯報表只需要選擇啟用觸發事件登錄標頭。

如何使用偵錯報表

如果發生轉換 (根據現有的評估系統)，且您收到該轉換的偵錯報表，就表示觸發事件已成功登錄。

查看每個偵錯歸因報表，確認您收到的一般歸因報表是否與兩個偵錯鍵相符。

如果未能達成比對，可能的原因有很多。

按預期方式運作：

  • 保護隱私權的 API 行為：
    • 使用者達到報表頻率上限，導致所有後續報表無法在這段時間內傳送；或是因為待處理目的地限製而移除來源。
    • 事件層級報表：這份報表必須採用隨機回應 (雜訊) 並隱藏，或您可能會收到隨機報表。
    • 事件層級報表：已達數量上限三個 (點擊) 或一個 (觀看) 報表，且後續報表未設定明確優先順序，或是低於現有報表的優先順序。
    • 可匯總報表的貢獻數量已超過上限。
  • 廣告技術定義的商業邏輯：
    • 系統會運用篩選器或優先順序規則篩除觸發事件。
  • 時間延遲或與網路可用性的互動 (例如使用者長時間關閉裝置)。

非預期的原因：

  • 實作問題：
    • 來源標頭設定有誤。
    • 觸發事件標頭設定有誤。
    • 其他設定問題。
  • 裝置或網路問題：
    • 因網路狀況而失敗。
    • 來源或觸發事件的登錄回應未觸及用戶端。
    • API 錯誤。

未來的考量，以及需要大家集思廣益的問題

Attribution Reporting API 目前仍在開發階段。我們也在探索日後有可能支援的功能，例如非最終點擊歸因模式和跨裝置評估使用情境。

此外，我們也希望針對以下幾個問題，向社群徵求意見：

  1. 您是否希望 API 針對已驗證的安裝事件傳送報表？這些報表會計入廣告技術平台各自的頻率限制。
  2. 您認為將 InputEvent 從應用程式傳遞到廣告技術，以執行來源登錄作業時，是否會遇到困難？
  3. 針對預先載入或重新安裝的應用程式，您是否有任何特殊的歸因使用情境？