Attribution Reporting API 可讓系統根據來源進行跨應用程式和網站歸因 以及觸發同一部裝置的觸發條件瀏覽器,例如 Chrome 可以將來源和觸發事件登錄作業委派給歸因報表 API,而不是在瀏覽器中處理註冊。 這樣一來,Android 就能比對網站和應用程式的來源和觸發條件。
本指南說明如何設定跨應用程式和網站歸因功能。
設定跨應用程式和網站歸因時,強烈建議您一併 熟悉可用的偵錯解決方案,確保 確保設定正常運作。
透過 Android OS 登錄來源和觸發條件
只有採用歸因分析時,才能使用跨應用程式和網站歸因 瀏覽器和 Android 作業系統必須相同,才能啟用 Reporting API 裝置。傳送 Android Attribution Reporting API 的可用性 標示「Attribution-Reporting-Support」標頭。這個標頭會傳回 os 網路,或兩者並用取決於裝置可存取的內容。如果兩者皆是 可用的資源,廣告技術就能選擇登錄網頁來源和網頁 透過瀏覽器或作業系統觸發
廣告技術需決定是否登錄網頁來源或網站觸發條件 瀏覽器或作業系統
- 如果是僅限網站的廣告活動,廣告技術仍可同時登錄來源和觸發條件 或是使用 Chrome 的 Attribution Reporting API 或選擇委派給作業系統。 針對可能發生來源或觸發事件的純網頁廣告活動, WebView、廣告技術必須將來源和觸發事件登錄作業委派給 作業系統詳情請參閱 WebView 相關章節。
- 廣告技術應避免同時使用 Chrome 登錄來源和觸發條件 和 Android API,以免發生重複歸因 報表。
- 歸因程序會分別針對瀏覽器和作業系統進行。如果來源是 向瀏覽器註冊,但藉由 OS 登錄觸發事件, 而無法比對,反之亦然
- 如果來源可能促成應用程式或網頁觸發條件,這種問題就極為重要 根據建議,廣告技術將網路來源和觸發條件登錄 Android Attribution Reporting API
- 如果觸發事件可能是由應用程式型來源促成,廣告技術可以 選擇將網站觸發事件登錄作業委派給 Android 歸因報表 也能使用 Google Cloud CLI 或 Compute Engine API
- 如果廣告活動同時發生來源和觸發條件在應用程式中,兩者都會觸發 必須向 OS Attribution Reporting API 註冊。
登錄應用程式來源和網站觸發條件
對部分廣告活動來說,來源可能是在應用程式中,而觸發條件是 造訪網頁。
範例
使用者在喜愛的新聞應用程式中閱讀文章。他看到「平價」廣告 飛往巴黎的班機,也興奮地點擊預訂。廣告技術在 新聞應用程式使用 Android Attribution Reporting API 登錄點擊來源。 系統會將使用者導向廣告客戶在 Chrome 中的網頁,以便他們存取 轉換。廣告客戶網站上的廣告技術會檢查 OS 層級 API 是否 而且可供使用廣告技術記錄轉換觸發事件的方式如下: 指示 Chrome 將註冊委派給 OS 而非註冊 直接使用 Chrome 的 Attribution Reporting APIOS 層級的歸因分析 如此一來,Reporting API 就能比對應用程式來源和網頁觸發條件並傳出 你就能查看相關報表
![應用程式至網頁歸因流程](https://developers.google.cn/static/privacy-sandbox/private-advertising/attribution-reporting/cross-web-app/a2w_diagram.png?hl=zh-tw)
應用程式來源登錄:
每日新聞 Android 應用程式中的廣告技術 SDK 使用
registerSource()
Android 版 Attribution Reporting API 將要求傳送至廣告技術伺服器 提供給
registerSource()
的網址廣告技術伺服器使用 Attribution-Reporting-Register-Source 回應 完成來源登錄程序的標頭
網站觸發條件登錄:
廣告技術會登錄觸發事件,並在 Attribution Reporting API
網頁 ARA 會傳回支援的平台相關資訊
OS-Trigger
標頭會指示網頁 ARA API 呼叫 OS ARA APIregisterWebTrigger()
函式對
registerWebTrigger()
的呼叫會在背景執行 不需要直接使用 OS 呼叫registerWebTrigger()
OS ARA 接手,並向
Attribution-Reporting-Register-OS-Trigger
標頭廣告技術會使用 OS API 完成觸發事件登錄作業
OS ARA 會根據套用的邏輯 應用程式<>應用程式歸因並傳送相同的報表
工作流程
下列步驟會進一步說明如何完成這項工作:
應用程式的廣告技術透過 Android 的歸因分析登錄來源 Reporting API,其中包含下列調整項:
- 如要登錄預期在網站上完成轉換的應用程式來源,請
Attribution-Reporting-Register-Source
回應標頭應包含網站 而非應用程式目的地。
Attribution-Reporting-Register-Source: { "web_destination": "https://advertiser.example", ... }
- 敬上
- 部分廣告客戶可能會使用多家評估服務供應商 (例如, 第三方成效評估工具或數據分析工具)。 在某些情況下,Attribution Reporting API 會追蹤重新導向路徑 會在背景中列在 Attribution-Reporting-Redirect 標頭中指定的位置,然後 也就是 302 重新導向路徑在前景執行的時間 導航要求這些要求會傳送至同一個網址,且可能會導致 第三方評估服務供應商是否重複計算註冊次數。目的地: 可避免重複計算註冊,廣告技術可以修改重新導向行為 將 Attribution Reporting API 登錄傳送至替代方案 確定性網址
如要啟用這項行為,廣告技術必須在符合以下情況時加入新的 HTTP 標頭: 回應註冊要求:
- 標題為「
Attribution-Reporting-Redirect-Config
」 - 標頭的值應為重新導向-302-to-well-known
"Attribution-Reporting-Redirect-Config": "redirect-302-to-well-known"
- 標題為「
來源註冊程序的其餘部分與標準相同 應用程式對應用程式的來源登錄作業。
- 如要登錄預期在網站上完成轉換的應用程式來源,請
廣告客戶網站上的廣告技術要求取得觸發事件,方法是要求 Chrome 將註冊委派給 Android Attribution Reporting API:
使用者在網站上完成轉換後,廣告技術 要求透過 Chrome 登錄觸發事件
像素或
fetch()
要求可用來提出要求 觸發Chrome 傳回
Attribution-Reporting-Support
要求標頭 廣告技術如果 Chrome 瀏覽器和 Android 裝置,標頭將傳回os, web
"Attribution-Reporting-Support": "os, web"
接著,廣告技術應指示 Chrome 使用
Attribution-Reporting-Register-OS-Trigger
標頭:指示 Chrome 將註冊委派給 OS
Chrome 會呼叫 OS API 函式,將註冊委派給 OS
registerWebTrigger()
- 在內部呼叫
registerWebTrigger()
時,廣告技術 不需要直接呼叫registerWebTrigger()
- 在內部呼叫
OS API 會向傳遞的廣告技術 URI 發出次要 API 呼叫 透過瀏覽器
"Attribution-Reporting-Register-OS-Trigger": "https://adtech.example/register-trigger", "https://other-adtech.example/register-trigger"
在某些情況下,
Attribution-Reporting-Support
標頭將無法使用, 無法傳送訊息在這種情況下,廣告技術仍可設定偏好的 處理觸發事件登錄作業的平台,方法是加入Attribution-Reporting-Info
標頭。金鑰為偏好的平台 允許的值為os
和web
。瀏覽器會使用偏好的平台 視情況而定,且 OS 接聽後會改回使用網路平台 無法使用。
Attribution-Reporting-Info: preferred-platform=os
- 如要完成觸發事件登錄程序,廣告技術的端點應回應 傳送至 Android Attribution Reporting API 請求。
Attribution-Reporting-Register-Trigger { "event_trigger_data": [{"trigger_data":"1"}], "aggregatable_trigger_data": [ {"key_piece":"0x400","source_keys":["campaignCounts"]}, {"key_piece":"0xA80","source_keys":["geoValue"]} ], ... }
- 觸發事件登錄的其餘部分將維持不變。
登錄網頁來源和應用程式觸發條件
就某些廣告活動而言,來源可能是在行動瀏覽器中的網站,但 觸發事件的發生頻率
範例
使用者透過 Android 手機的 Chrome 瀏覽器瀏覽網頁。 他看到自己喜愛的商店之一的毛衣廣告。他點選 系統就會將使用者帶往已經下載的應用程式。「廣告技術」 藉由指示 Chrome,在放送廣告的網站中登錄點擊來源 而不是委派給 Android Attribution Reporting API 的登錄 使用 Attribution Reporting API。使用者購買了毛衣 購物應用程式接著,廣告客戶應用程式中的廣告技術會登錄 轉換觸發條件。OS 層級 Attribution Reporting API 能夠比對網頁來源和應用程式觸發條件, 寄出相關報表
![網頁到應用程式歸因流程](https://developers.google.cn/static/privacy-sandbox/private-advertising/attribution-reporting/cross-web-app/w2a_diagram.png?hl=zh-tw)
網站來源登錄:
廣告技術會登錄來源,並在 Attribution Reporting API
網頁 ARA 會傳回支援的平台相關資訊
OS-Source
標頭會指示網頁 ARA API 呼叫 OS ARA APIregisterWebSource()
函式對
registerWebSource()
的呼叫會在背景中發生,開發人員 無需直接透過 OS 呼叫registerWebSource()
OS ARA 接手並傳送要求至提供的廣告技術伺服器網址 依據
Attribution-Reporting-Register-OS-Source
標頭廣告技術會使用 OS API 完成來源登錄
應用程式觸發事件登錄:
Android 服飾商店中的廣告技術 SDK 登錄觸發事件的方法: OS ARA
Android 版 Attribution Reporting API 將要求傳送至廣告技術伺服器 提供給
registerTrigger()
的網址廣告技術伺服器以
Attribution-Reporting-Register-Trigger
回應 完成觸發條件登錄程序的標題OS ARA 會根據套用的邏輯 應用程式<>應用程式歸因,並傳送相同的報表
工作流程
下列步驟會進一步說明如何完成這項工作:
發布商網站上的廣告技術指示,登錄來源 Chrome 將註冊委派給 Android Attribution Reporting API:
- 如果是網頁至應用程式用途,登錄來源時,歸因
您必須使用
attributionsrc
標記或使用 JavaScript 註冊 - 以下範例使用
attributionsrc
標記指定 來源參數:
<img src="https://adtech.example/conversionpixel" attributionsrc="https://adtech.example/register-source?purchase=12">
- 如果是網頁至應用程式用途,登錄來源時,歸因
您必須使用
Chrome 會將
Attribution-Reporting-Support
要求標頭傳回給 廣告技術如果 Chrome 瀏覽器和 Android 裝置都啟用這個 API, 標頭將傳回os, web
。"Attribution-Reporting-Support": "os, web"
廣告技術應指示 Chrome 使用
Attribution-Reporting-Register-OS-Source
標頭:- 指示 Chrome 將註冊委派給 OS
- Chrome 會呼叫 OS API 函式,將註冊委派給 OS
registerWebSource()
- 對
registerWebSource()
的呼叫會在背景進行 不需要直接呼叫registerWebSource()
- OS API 會向傳入的廣告技術 URI 發出次要 API 呼叫 瀏覽器
"Attribution-Reporting-Register-OS-Source": "https://adtech.example/register-source"
- 在某些情況下,
Attribution-Reporting-Support
標頭會無法使用。 在此情況下,廣告技術仍可設定偏好的平台來處理 加入Attribution-Reporting-Info
標頭來註冊來源。 鍵為偏好平台,允許的值為os
和web
。 瀏覽器會使用偏好的平台 (如果有的話),並做為備用 網路平台。
Attribution-Reporting-Info: preferred-platform=os
- 為了完成來源登錄,廣告技術的端點應回應
傳送給 Android Attribution Reporting API 要求,並傳回回應標頭
Attribution-Reporting-Register-Source
。回應也應指定 應用程式目的地。
Attribution-Reporting-Register-Source { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", ... }
廣告客戶應用程式中的廣告技術會透過 Android 系統登錄觸發事件 Attribution Reporting API:
廣告活動同時包含應用程式和網站可能的目的地
設定雙重目的地
- 有些廣告活動可能是設定在廣告客戶的應用程式中完成轉換, 取決於使用者 已安裝應用程式。
- 在這種情況下,建議將來源登錄委派給 盡可能正確歸因來源的作業系統 觸發動作的位置向 OS 註冊來源時, 您可以在各個參數中指定應用程式和網站目的地。
- 應用程式目的地應在
destination
欄位中 - 網站目的地應在「
web_destination
」欄位中 - Chrome 開發人員應注意 OS 的「
destination
」欄位 Attribution Reporting API 必須是應用程式套件,而不是網址。
Attribution-Reporting-Register-Source { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", "web_destination": "https://example.advertiser" ... }
- 下一節將介紹如何使用雙重到達網頁 可能會影響報表中的雜訊
使用概略報告功能,減少雙重事件層級報表的雜訊 目的地來源:
- 如果來源中同時指定了 OS (應用程式) 和網站目的地 事件層級報表會指出觸發事件是否發生 到達網頁或應用程式目的地中的到達網頁不過, 隱私權限制,這些報表將會加入額外的噪音。
- 廣告技術可以在
coarse_event_report_destinations
「Attribution-Reporting-Register-Source
」標頭即可開啟粗略回報功能 進而減少雜訊如果來源包含coarse_event_report_destinations
欄位贏得歸因,產生的報表就會同時包含 以及實際觸發事件位置不一 但產生的雜訊比應用程式或網頁目的地報表少 。 - 匯總報表則維持不變。
使用 Chrome 自訂分頁的應用程式
部分應用程式可能會使用自訂分頁來轉譯網路內容。自訂分頁的運作方式 類似於一般網頁來評估應用程式和行動網站。
- 登錄應用程式來源和 Custom Tab 觸發條件:
- 按照操作說明登錄應用程式來源和網頁觸發條件。
- 登錄自訂分頁來源和應用程式觸發條件:
- 按照操作說明登錄網頁來源和應用程式觸發條件。
- 登錄 CCT 來源和 CCT 觸發條件
- 這與 Chrome 任何網站對網站歸因的處理方式相同。
使用 WebView 的應用程式
部分應用程式可能會使用 WebView 顯示內容。用途十分廣泛 如果是 WebView,例如顯示廣告、代管網頁內容或自訂應用程式 更適合在網頁格式的功能。
WebView 中只能使用 OS 層級歸因。 Attribution-Reporting-Support 標頭只會傳回 OS,且 Android Attribution Reporting API 已推出。
委派給 OS 時,WebView 可能會使用
registerSource
或registerWebSource
和registerTrigger
或registerWebTrigger
。 由轉譯 WebView 的應用程式設定,且取決於 依 WebView 處理registerSource
和registerWebSource
的差異如下: 來源則會以發布者的身分記錄透過registerSource
,系統會記錄應用程式 發布商;我們用registerSource
這個例子說明 發布商應用程式,顯示使用 WebView 顯示的廣告。取代為registerWebSource
,系統會將 WebView 中代管的網站記錄為 發布商;我們用registerWebSource
為例 而由 WebView 轉譯的網站 顯示廣告。registerTrigger
和registerWebTrigger
的行為類似。 商品 #3 的圖表,詳細說明應用程式或 SDK 開發人員的各種情境 只想將 API 設為使用registerSource
或registerWebSource
, 和registerTrigger
或registerWebTrigger
。
根據預設,WebView 會在下列情況下使用
registerSource
和registerWebTrigger
: 呼叫 Android Attribution Reporting API。這會將來源與 應用程式,以及何時與 WebView 中網址頂層來源的觸發事件 才會觸發- 如果應用程式需要不同行為,就需要採用新方法
androidx.webkit.WebViewSettingsCompat 上的 setAttributionRegistrationBehavior
類別這個方法會指定 WebView 是否應呼叫
registerWebSource()
或registerWebTrigger()
,而不是registerSource()
或registerTrigger()
。- 您必須為啟動的每個 WebView 設定此行為。
- 如果廣告技術 SDK 啟動 WebView,SDK 就必須進行設定 這種預設行為
- 適用於要使用
registerWebSource()
來連結來源的應用程式 所註冊的這類開發人員,必須 加入 WebApp 許可清單。如要加入許可清單,請填寫這份表單。 許可清單的用途是減少隱私權注意事項 建立對網路環境的信任感。
- setAttributionRegistrationBehavior 選項
值 說明 用途範例 APP_SOURCE_AND_WEB_TRIGGER (預設) 允許應用程式從 WebView 登錄應用程式來源 (與應用程式套件名稱相關聯的來源),以及網頁觸發事件 (與 eTLD+1 相關聯的觸發事件)。 使用 WebView 放送廣告 (而非啟用網頁瀏覽功能) 的應用程式 WEB_SOURCE_AND_WEB_TRIGGER 允許應用程式從 WebView 登錄網頁來源和網頁觸發事件。 以 WebView 為基礎的瀏覽器應用程式,且其廣告曝光和轉換皆可能發生在 WebView 網站上。 APP_SOURCE_AND_APP_TRIGGER 允許應用程式從 WebView 登錄應用程式來源和應用程式觸發事件。 以 WebView 為基礎的應用程式,且其廣告曝光和轉換應一律與應用程式建立關聯,而非與 WebView 的 eTLD+1 建立關聯。 已停用 停用從 WebView 登錄來源和觸發事件的功能。 - 如果應用程式需要不同行為,就需要採用新方法
androidx.webkit.WebViewSettingsCompat 上的 setAttributionRegistrationBehavior
類別這個方法會指定 WebView 是否應呼叫
從 WebView 登錄來源和觸發事件
廣告技術應使用
Attribution-Reporting-Register-OS-Source
標頭。根據設定行為 如果是 WebView,則呼叫會呼叫registerSource()
或registerWebSource()
並透過 Android 歸因分析發出次要 API 呼叫 將報表 API 傳送到廣告技術 URI。- 如要完成來源登錄程序,廣告技術的端點 以 回應標頭。
Attribution-Reporting-Register-OS-Source { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", ... }
其餘來源登錄設定將維持不變。
廣告技術應使用
Attribution-Reporting-Register-OS-Trigger
標頭。根據設定行為 如果是 WebView,則呼叫會呼叫registerTrigger()
或registerWebTrigger()
並透過 OS 向廣告技術 URI 發出次要 API 呼叫。- 如要完成觸發條件登錄程序,廣告技術的端點應 以回應回應 Android Attribution Reporting API 要求 標題。
Attribution-Reporting-Register-OS-Trigger { "event_trigger_data": [{"trigger_data":"1"}], "aggregatable_trigger_data": [ {"key_piece":"0x400","source_keys":["campaignCounts"]}, {"key_piece":"0xA80","source_keys":["geoValue"]} ], ... }
- 觸發條件登錄程序的其餘部分仍維持不變。
偵錯
設定應用程式至網頁的實作時,建議您設定偵錯功能 報表,確認來源和觸發條件是否已正確登錄,以及 未註冊,以便收到原因。
如需一般歸因報表偵錯步驟,請參閱偵錯教戰手冊。