本頁面由 Cloud Translation API 翻譯而成。

Attribution Reporting API 跨網站和應用程式導入指南

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 就能比對應用程式來源和網頁觸發條件並傳出你就能查看相關報表

應用程式來源登錄：

每日新聞 Android 應用程式中的廣告技術 SDK 使用 registerSource()
Android 版 Attribution Reporting API 將要求傳送至廣告技術伺服器提供給 registerSource() 的網址
廣告技術伺服器使用 Attribution-Reporting-Register-Source 回應完成來源登錄程序的標頭

網站觸發條件登錄：

廣告技術會登錄觸發事件，並在 Attribution Reporting API
網頁 ARA 會傳回支援的平台相關資訊
OS-Trigger 標頭會指示網頁 ARA API 呼叫 OS ARA API registerWebTrigger() 函式
對 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
```
  注意： 這個標頭之後的所有後續重新導向會在重新導向 URI 的路徑開頭加上 .well-known。
- 來源註冊程序的其餘部分與標準相同應用程式對應用程式的來源登錄作業。
，瞭解如何調查及移除這項存取權。
注意： 如果您或發布應用程式使用的是 WebView 若要在 Android 應用程式中顯示原生廣告，請參閱 WebView 上的章節
廣告客戶網站上的廣告技術要求取得觸發事件，方法是要求 Chrome 將註冊委派給 Android Attribution Reporting API：
- 使用者在網站上完成轉換後，廣告技術要求透過 Chrome 登錄觸發事件
  1. 像素或 fetch() 要求可用來提出要求觸發
  2. Chrome 傳回 Attribution-Reporting-Support 要求標頭廣告技術如果 Chrome 瀏覽器和 Android 裝置，標頭將傳回 os, web
```
Attribution-Reporting-Support: os, web
```
- 接著，廣告技術應指示 Chrome 使用 Attribution-Reporting-Register-OS-Trigger 標頭：
  1. 指示 Chrome 將註冊委派給 OS
  2. Chrome 會呼叫 OS API 函式，將註冊委派給 OS registerWebTrigger()
    - 在內部呼叫 registerWebTrigger() 時，廣告技術不需要直接呼叫 registerWebTrigger()
  3. 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-Register-Trigger 含有網站註冊資訊的標頭，以及包含 OS 註冊的 Attribution-Reporting-Register-OS-Trigger 標頭指定偏好的平台時應傳回資訊，確保正確可能需要進行大量的註冊作業系統和網路註冊都必須因此如果無法使用偏好的平台，便會顯示資訊必須包含備用方法所需的參數
```
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 能夠比對網頁來源和應用程式觸發條件，寄出相關報表

網站來源登錄：

廣告技術會登錄來源，並在 Attribution Reporting API
網頁 ARA 會傳回支援的平台相關資訊
OS-Source 標頭會指示網頁 ARA API 呼叫 OS ARA API registerWebSource() 函式
對 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
```
注意： 必須啟用 Attribution Reporting API ，以便順利跨應用程式和網站進行評估。
廣告技術應指示 Chrome 使用 Attribution-Reporting-Register-OS-Source 標頭：
1. 指示 Chrome 將註冊委派給 OS
2. Chrome 會呼叫 OS API 函式，將註冊委派給 OS registerWebSource()
3. 對 registerWebSource() 的呼叫會在背景進行不需要直接呼叫 registerWebSource()
4. OS API 會向傳入的廣告技術 URI 發出次要 API 呼叫瀏覽器
```
Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
```
- 在某些情況下，Attribution-Reporting-Support 標頭會無法使用。在此情況下，廣告技術仍可設定偏好的平台來處理加入 Attribution-Reporting-Info 標頭來註冊來源。鍵為偏好平台，允許的值為 os 和 web。瀏覽器會使用偏好的平台 (如果有的話)，並做為備用網路平台。
，瞭解如何調查及移除這項存取權。
注意： Attribution-Reporting-Register-Source 含有網站註冊資訊的標頭，以及包含 OS 註冊的 Attribution-Reporting-Register-OS-Source 標頭指定偏好的平台時應傳回資訊，確保正確可能需要進行大量的註冊作業系統和網路註冊都必須因此如果無法使用偏好的平台，便會顯示資訊必須包含備用方法所需的參數
```
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",
    ...
}
```
- 為支援來源註冊的重新導向功能，Chrome 會遵循重新導向並呼叫每個重新導向躍點的網路內容 API。
- 其餘來源登錄設定將維持不變。
廣告客戶應用程式中的廣告技術會透過 Android 系統登錄觸發事件 Attribution Reporting API：
- 對於在應用程式中發生的觸發條件，應用程式會使用 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 已推出。

注意： 如要針對 Chrome 和 WebView 進行歸因，在 Chrome 中，來源和觸發事件登錄需委派給 OS WebView 僅支援 OS 歸因。
委派給 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 登錄來源和觸發事件的功能。

從 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"]}
    ],
    ...
}
```
- 觸發條件登錄程序的其餘部分仍維持不變。

偵錯

設定應用程式至網頁的實作時，建議您設定偵錯功能報表，確認來源和觸發條件是否已正確登錄，以及未註冊，以便收到原因。

如需一般歸因報表偵錯步驟，請參閱偵錯教戰手冊。