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

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

Attribution Reporting API 可針對在同一裝置上發生的來源和觸發事件，啟用跨應用程式和網頁歸因功能。Chrome 等瀏覽器可以將來源和觸發事件登錄作業委派給 Android 的 Attribution Reporting API，而非在瀏覽器中處理這些登錄作業。這可讓 Android 在網站和應用程式中比對來源和觸發事件。

本指南將說明如何設定跨應用程式和網站歸因。

設定跨應用程式和網站歸因時，強烈建議您也熟悉偵錯解決方案，確保設定能正常運作。

使用 Android OS 登錄來源和觸發條件

只有在同一部裝置的瀏覽器和 Android OS 中都啟用 Attribution Reporting API 時，才能使用跨應用程式和網頁歸因功能。Android Attribution Reporting API 的可用性會透過 Attribution-Reporting-Support 標頭傳送。這個標頭會傳回 os、web，或兩者皆傳回，取決於該裝置可用的內容。如果兩者皆可使用，廣告技術就能選擇透過瀏覽器或作業系統登錄網頁來源和網頁觸發條件。

廣告技術需要決定是否要透過瀏覽器或作業系統登錄網頁來源或網頁觸發事件。

針對僅限網頁的廣告活動，廣告技術仍可透過 Chrome 的 Attribution Reporting API 登錄來源和觸發事件，或選擇將這兩項都委派給 OS。如果是純網頁廣告活動，來源或觸發事件可能會在 WebView 中發生，廣告技術必須將來源和觸發事件登錄委派給作業系統。詳情請參閱 WebView 相關章節。
廣告技術應避免同時使用 Chrome 和 Android API 登錄來源和觸發事件，以免產生重複的歸因報表。
瀏覽器和作業系統的歸因作業是分開進行。如果來源已在瀏覽器中註冊，但觸發條件已在作業系統中註冊，則這兩者無法配對，反之亦然。
對於可能導致應用程式或網頁觸發事件的來源，廣告技術強烈建議將網頁來源和觸發事件登錄委派給 Android Attribution Reporting API。
如果觸發事件可能是由應用程式來源觸發，廣告技術可以選擇將網頁觸發事件登錄委派給 Android Attribution Reporting API。
如果廣告活動的來源和觸發事件都發生在應用程式中，則需要透過 OS Attribution Reporting API 登錄這兩項資訊。

註冊應用程式來源和網頁觸發條件

對於某些廣告活動，來源可能發生在應用程式中，而觸發事件則發生在同一裝置上行動瀏覽器的網站中。

範例

使用者在喜愛的新聞應用程式中閱讀文章，看到巴黎廉航廣告後，興奮地點選預訂。在新聞應用程式中放送廣告的廣告技術，會使用 Android Attribution Reporting API 登錄點擊來源。使用者會在 Chrome 中前往廣告主的網頁，並完成轉換。廣告客戶網站上的廣告技術會檢查是否有可用的作業系統層級 API，如果有的話，廣告技術會指示 Chrome 將登錄作業委派給作業系統，而非直接透過 Chrome 的 Attribution Reporting API 登錄。接著，作業系統層級的 Attribution Reporting API 就能比對應用程式來源和網頁觸發事件，並傳送相關報表。

應用程式來源註冊：

Daily News Android 應用程式中的廣告技術 SDK 會使用 registerSource() 註冊點擊
Android 版 Attribution Reporting API 會向 registerSource() 提供的廣告技術伺服器網址傳送要求
廣告技術伺服器會回應 Attribution-Reporting-Register-Source 標頭，完成來源登錄程序

網頁觸發事件登錄：

廣告技術登錄觸發事件，並在 Attribution Reporting API 中檢查作業系統是否可用
Web ARA 會傳回支援哪些平台的資訊
OS-Trigger 標頭會指示 Web ARA API 呼叫 OS ARA API registerWebTrigger() 函式
對 registerWebTrigger() 的呼叫會在幕後發生，開發人員不必直接透過 OS 呼叫 registerWebTrigger()
OS ARA 會接手並傳送要求至 Attribution-Reporting-Register-OS-Trigger 標頭提供的廣告技術伺服器網址
廣告技術會透過 OS API 完成觸發事件登錄
OS ARA 會根據套用至 app<>app 歸因的相同邏輯執行歸因，並傳送相同的報表

工作流程

請按照下列步驟完成這項工作：

應用程式中的廣告技術會使用 Android 的 Attribution Reporting API 登錄來源，並進行下列調整：
- 如要註冊預期會在網站上轉換的應用程式來源，Attribution-Reporting-Register-Source 回應標頭應包含網站目的地 (eTLD+1)，而非應用程式目的地。
```
Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
```
注意： 如果廣告活動可能在網站或應用程式目的地中轉換，請參閱「雙重目的地」一節
- 部分廣告主可能會使用多個評估服務供應商 (例如第三方評估工具或數據分析工具)，並透過 302 重新導向鏈進行評估。在某些情況下，Attribution Reporting API 會在背景中依照 Attribution-Reporting-Redirect 標頭指定的重新導向路徑，同時針對現有導覽要求在前景執行 302 重新導向路徑。這些要求會傳送至相同的網址，可能會導致第三方評估供應商重複計算註冊次數。為避免登錄次數重複計算，廣告技術可以修改重新導向行為，將 Attribution Reporting API 登錄資料傳送至其他可確定的網址。
- 如要啟用這項行為，廣告技術在回應註冊要求時，必須加入新的 HTTP 標頭：
  - 標頭為 Attribution-Reporting-Redirect-Config
  - 標頭的值應為 redirect-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 裝置上都啟用 API，標頭會傳回 os, web
```
Attribution-Reporting-Support: os, web
```
- 接著，廣告技術應使用 Attribution-Reporting-Register-OS-Trigger 標頭，告知 Chrome 將權限委派給作業系統，該標頭會執行以下操作：
  1. 告知 Chrome 將註冊委派給作業系統
  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 標頭，設定偏好的平台來處理觸發事件登錄作業。鍵為 preferred-platform，允許的值為 os 和 web。瀏覽器會在可用時使用偏好的平台，並在無法使用 OS 時改用網頁平台。
注意： 在指定偏好平台時，應一併傳回包含網站註冊資訊的 Attribution-Reporting-Register-Trigger 標頭，以及包含 OS 註冊資訊的 Attribution-Reporting-Register-OS-Trigger 標頭，以確保能進行正確的平台註冊。您必須提供 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，而非在 Chrome 上使用 Attribution Reporting API，藉此登錄點擊來源。使用者在購物應用程式中購買了毛衣。廣告主應用程式中的廣告技術隨後會使用 Android Attribution Reporting API 登錄轉換觸發事件。作業系統層級的 Attribution Reporting API 可比對網頁來源和應用程式觸發條件，並傳送相關報表。

網站來源註冊：

廣告技術登錄來源，並在 Attribution Reporting API 中檢查 OS 是否可用
Web ARA 會傳回支援哪些平台的資訊
OS-Source 標頭會指示 Web 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 會根據套用至 app<>app 歸因的相同邏輯執行歸因，並傳送相同的報表

工作流程

請按照下列步驟完成這項工作：

發布商網站上的廣告技術會透過指示 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
```
注意： 必須在 Android 作業系統上啟用 Attribution Reporting API，才能成功評估跨應用程式和網站的轉換。
廣告技術應使用 Attribution-Reporting-Register-OS-Source 標頭，告知 Chrome 將工作委派給 OS 層級 API，該標頭具有以下功能：
1. 告知 Chrome 將註冊委派給作業系統
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 標頭，設定偏好的平台來處理來源登錄作業。鍵為 preferred-platform，可接受的值為 os 和 web。瀏覽器會在可用時使用偏好的平台，並在無法使用作業系統時改用網路平台。
注意： 在指定偏好平台時，應一併傳回包含網站註冊資訊的 Attribution-Reporting-Register-Source 標頭，以及包含 OS 註冊資訊的 Attribution-Reporting-Register-OS-Source 標頭，以確保能進行正確的平台註冊。您必須提供 OS 和網頁註冊，以便在無法使用偏好平台時，提供備用方法所需的資訊。
```
Attribution-Reporting-Info: preferred-platform=os
```
- 如要完成來源登錄，廣告技術的端點應使用回應標頭 Attribution-Reporting-Register-Source 回應 Android Attribution Reporting API 要求。回應也應在目的地欄位中指定應用程式目的地。
```
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 (如有)，這樣無論觸發事件發生的位置為何，來源都能正確歸因。向 OS 註冊來源時，您可以在各個參數中指定應用程式和網頁目的地。
- 應用程式目的地應位於 destination 欄位
- 網頁目的地應位於 web_destination 欄位
- Chrome 開發人員應注意，OS Attribution Reporting API 的 destination 欄位應為應用程式套件，而非網址。
```
Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    "web_destination": "https://example.advertiser"
    ...
}
```
- 下一節將說明粗略報表，並說明使用雙重目的地可能會如何影響報表中的雜訊。
使用粗略報表，減少雙重目的地來源的事件層級報表中的雜訊：
- 如果來源註冊中同時指定了作業系統 (應用程式) 和網頁目的地，事件層級報表預設會指出觸發事件是在網頁目的地還是應用程式目的地發生。不過，為了維持隱私權限制，這些報表會加入額外的雜訊。
- 廣告技術可以在 Attribution-Reporting-Register-Source 標頭下使用 coarse_event_report_destinations 欄位，啟用粗略報表並減少雜訊。如果指定 coarse_event_report_destinations 欄位的來源贏得歸因，相關報表就會包含應用程式和網站目的地，不區分觸發事件的實際發生位置，但雜訊較少，比指定應用程式或網站目的地的報表更為精簡。
- 匯總報表則維持不變。

針對使用 Chrome Custom Tabs 的應用程式

部分應用程式可能會使用自訂分頁來轉譯網頁內容。在評估應用程式和行動網站時，自訂分頁的運作方式與一般網頁類似。

註冊應用程式來源和自訂分頁觸發條件：
- 按照指示註冊應用程式來源和網頁觸發事件。
註冊自訂分頁來源和應用程式觸發條件：
- 按照指示註冊網頁來源和應用程式觸發事件。
註冊 CCT 來源和 CCT 觸發條件
- 這項功能的處理方式與 Chrome 中的任何網站對網站網站歸因相同。

使用 WebView 的應用程式

有些應用程式可能會使用 WebView 顯示內容。WebView 的用途多元，例如顯示廣告、代管網頁內容，或更適合網頁格式的自訂應用程式功能。

如要讓 WebView 使用 Attribution Reporting API，嵌入應用程式必須設定正確的權限。
WebView 僅支援作業系統層級歸因。只有在 Android Attribution Reporting API 可用時，Attribution-Reporting-Support 標頭才會傳回 os。

注意： 如要跨 Chrome 和 WebView 進行歸因，Chrome 中的來源和觸發事件註冊項目必須委派給作業系統，因為 WebView 僅支援以作業系統為依據的歸因。

委派給作業系統時，WebView 可能會使用 registerSource 或 registerWebSource，以及 registerTrigger 或 registerWebTrigger。WebView 會由顯示 WebView 的應用程式設定所使用的程式，並根據每個 WebView 決定。

registerSource 和 registerWebSource 的差異在於哪個來源會記錄為發布者。使用 registerSource 時，應用程式會以發布商的身份記錄；舉例來說，如果發布商應用程式顯示的是使用 WebView 算繪的廣告，那麼這時就應使用 registerSource。使用 registerWebSource 時，系統會將 WebView 中代管的網站登錄為發布商。舉例來說，如果應用程式代管 WebView，且 WebView 正在顯示廣告的網站，則可使用 registerWebSource。registerTrigger 和 registerWebTrigger 的行為類似。項目 3 中的圖表詳細說明應用程式或 SDK 開發人員想要將 API 設定為使用 registerSource 或 registerWebSource，以及 registerTrigger 或 registerWebTrigger 的不同情況。

根據預設，WebView 會在呼叫 Android Attribution Reporting API 時使用 registerSource 和 registerWebTrigger。這會將來源與應用程式建立關聯，並在觸發事件發生時，將觸發事件與 WebView 中網址的頂層來源建立關聯。

如果應用程式需要不同的行為，就必須在 androidx.webkit.WebViewSettingsCompat 類別上使用新方法 setAttributionRegistrationBehavior。這個方法會指定 WebView 是否應呼叫 registerWebSource() 或 registerWebTrigger()，而非呼叫 registerSource() 或 registerTrigger()。
您必須為每個啟動的 WebView 設定這項行為。
如果廣告技術 SDK 正在啟動 WebView，則 SDK 需要設定這個預設行為。
如果應用程式想使用 registerWebSource() 將來源登錄項目與 WebView 中的網站建立關聯，而非在應用程式中建立關聯，則必須加入 WebApp 許可清單。如要加入許可清單，請填寫這份表單。許可清單的用途是就建立對網路環境的信任感這項議題，減少隱私權方面的疑慮。

值	說明	用途範例
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 Attribution Reporting API 發出對廣告技術 URI 的次要 API 呼叫。
- 如要完成來源註冊程序，廣告技術的端點應使用回應標頭回應 Android Attribution Reporting API 要求。
```
 Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}
```
來源註冊的其餘部分則維持不變。
廣告技術應使用 Attribution-Reporting-Register-OS-Trigger 標頭回應觸發事件登錄，根據 WebView 的設定行為，這會使用 OS 呼叫 registerTrigger() 或 registerWebTrigger()，並從 Rb 發出對廣告技術 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"]}
    ],
    ...
}

觸發事件註冊程序的其餘部分則維持不變。

偵錯

設定應用程式網頁實作項目時，建議您設定偵錯報告，以便驗證來源和觸發事件是否已正確註冊，如果未註冊，則可收到相關原因。

如需 Attribution Reporting 的一般偵錯步驟，請參閱偵錯手冊。