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 或兩者，視該裝置上可用的項目而定。如果兩者皆可使用，廣告技術就能選擇透過瀏覽器或作業系統登錄網頁來源和網頁觸發條件。

廣告技術必須決定是否要向瀏覽器或 OS 登錄網頁來源或網頁觸發條件。

• 如果是僅限網站的廣告活動，廣告技術仍可透過 Chrome 的 Attribution Reporting API 登錄來源和觸發事件，或選擇將兩者都委派給 OS。對於來源或觸發事件可能發生在 WebView 中的純網頁廣告活動，廣告技術必須將來源和觸發事件登錄作業委派給 OS。詳情請參閱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 隨後就能比對應用程式來源和網站觸發事件，並傳送相關報表。

應用程式來源註冊：

1. Daily News Android 應用程式中的廣告技術 SDK 會使用 registerSource() 登錄點擊。

2. Android 上的 Attribution Reporting API 會向提供給 registerSource() 的廣告技術伺服器網址發出要求

3. 廣告技術伺服器會以 Attribution-Reporting-Register-Source 標頭回應，完成來源登錄程序

註冊網頁觸發條件：

1. 廣告技術登錄觸發事件，並在 Attribution Reporting API 中檢查 OS 是否可用

2. 網頁 ARA 會傳回支援的平台資訊

3. OS-Trigger 標頭會告知網頁 ARA API 呼叫 OS ARA API registerWebTrigger() 函式

4. 對 registerWebTrigger() 的呼叫會在幕後發生，開發人員不需要直接使用 OS 呼叫 registerWebTrigger()

5. 作業系統 ARA 會接管並傳送要求至 Attribution-Reporting-Register-OS-Trigger 標頭提供的廣告技術伺服器網址

6. 廣告技術會使用 OS API 完成觸發事件登錄程序

7. 作業系統 ARA 會根據套用至應用程式<>應用程式歸因的相同邏輯執行歸因，並傳送相同的報表

工作流程

下列步驟提供完成這項工作的詳細說明：

1. 應用程式中的廣告技術使用 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
     

   • 其餘來源註冊程序與標準的應用程式對應用程式來源註冊相同。

2. 廣告主網站上的廣告技術會要求 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 將註冊作業委派給 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 標頭，設定偏好的平台來處理觸發事件登錄作業。鍵為 preferred-platform，允許的值為 os 和 web。瀏覽器會盡可能使用偏好的平台，如果作業系統無法使用，則會改用網頁平台。

   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 可比對網頁來源和應用程式觸發事件，並傳送相關報表。

註冊網站來源：

1. 廣告技術會在 Attribution Reporting API 中登錄來源並檢查 OS 是否可用

2. 網頁 ARA 會傳回支援的平台資訊

3. OS-Source 標頭會告知網頁 ARA API 呼叫 OS ARA API registerWebSource() 函式

4. 對 registerWebSource() 的呼叫會在幕後發生，開發人員不需要直接使用 OS 呼叫 registerWebSource()

5. 作業系統 ARA 會接管，並將要求傳送至 Attribution-Reporting-Register-OS-Source 標頭提供的廣告技術伺服器網址

6. 廣告技術會使用 OS API 完成來源登錄程序

應用程式觸發條件登錄：

1. 服飾商店 Android 應用程式中的廣告技術 SDK 會向 OS ARA 登錄觸發事件

2. Android 上的 Attribution Reporting API 會向提供給 registerTrigger() 的廣告技術伺服器網址發出要求

3. 廣告技術伺服器會傳回 Attribution-Reporting-Register-Trigger 標頭，完成觸發事件登錄程序

4. 作業系統 ARA 會根據套用至應用程式<>應用程式歸因的相同邏輯執行歸因，並傳送相同的報表

工作流程

下列步驟提供完成這項工作的詳細說明：

1. 發布商網站上的廣告技術會指示 Chrome 將登錄作業委派給 Android Attribution Reporting API，藉此登錄來源：

   • 如果是「網頁至應用程式」的使用情境，登錄來源時必須直接指定歸因來源參數，方法是使用 attributionsrc 標記或 JavaScript 登錄
   • 以下範例使用 attributionsrc 標記指定來源參數：

   <img src="https://adtech.example/conversionpixel"
   attributionsrc="https://adtech.example/register-source?purchase=12">
   

2. Chrome 會將 Attribution-Reporting-Support 請求標頭傳回給廣告技術。如果 Chrome 瀏覽器和 Android 裝置都啟用這項 API，標頭會傳回 os, web。

   Attribution-Reporting-Support: os, web
   

3. 廣告技術應使用 Attribution-Reporting-Register-OS-Source 標頭，告知 Chrome 委派給 OS 層級的 API，該標頭應：

   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 標頭，設定偏好的平台來處理來源登錄。鍵為 preferred-platform，可接受的值為 os 和 web。瀏覽器會使用偏好的平台，如果作業系統無法使用，則會改用網路平台。

   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。
   • 來源註冊的其餘部分則維持不變。

4. 廣告主應用程式中的廣告技術會使用 Android Attribution Reporting API 登錄觸發條件：

   • 如果是應用程式中發生的觸發條件，應用程式會照常透過 Android Attribution Reporting API 登錄觸發條件。

廣告活動同時有應用程式和網站這兩種潛在到達網頁

1. 設定雙重目的地

   • 部分廣告活動可能會根據各種因素 (例如使用者是否已安裝應用程式)，在廣告主的應用程式或網頁上進行轉換。
   • 在這些情況下，建議將來源登錄作業委派給 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"
       ...
   }
   

   • 下一節將說明粗略報表，並解釋使用雙重目的地可能會如何影響報表中的雜訊。

2. 針對雙重目的地來源，使用粗略報表減少事件層級報表中的干擾：

   • 如果在來源註冊中同時指定 OS (應用程式) 和網頁目的地，事件層級報表預設會指出觸發事件是發生在網頁目的地還是應用程式目的地。不過，為維持隱私權限制，這些報表會額外加入雜訊。
   • 廣告技術可以在 Attribution-Reporting-Register-Source 標頭下使用 coarse_event_report_destinations 欄位，開啟粗略報表並減少雜訊。如果指定 coarse_event_report_destinations 欄位的來源贏得歸因，相關報表就會包含應用程式和網站目的地，不區分觸發事件的實際發生位置，但與指定應用程式或網站目的地的報表相比，雜訊較少。
   • 匯總報表維持不變。

使用 Chrome Custom Tabs 的應用程式

部分應用程式可能會使用自訂分頁來顯示網頁內容。評估跨應用程式和行動網站的成效時，自訂分頁的行為與一般網頁類似。

1. 註冊應用程式來源和自訂分頁觸發條件：

   • 按照指示註冊應用程式來源和網頁觸發條件。

2. 登錄自訂分頁來源和應用程式觸發條件：

   • 按照指示註冊網頁來源和應用程式觸發條件。

3. 登錄 CCT 來源和 CCT 觸發條件

   • 這與 Chrome 中的任何網站間網頁歸因相同。

使用 WebView 的應用程式

部分應用程式可能會使用 WebView 顯示內容。WebView 的用途十分廣泛，例如顯示廣告、代管網頁內容，或以更適合網頁格式的方式呈現自訂應用程式功能。

1. 如要允許 WebView 使用 Attribution Reporting API，必須為內嵌應用程式設定正確的權限。

2. WebView 中僅提供作業系統層級的歸因。只有在 Android Attribution Reporting API 可用時，Attribution-Reporting-Support 標頭才會傳回 os。

3. 委派給 OS 時，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。
   • 根據預設，呼叫 Android Attribution Reporting API 時，WebView 會使用 registerSource 和 registerWebTrigger。將來源與應用程式建立關聯，並在觸發事件發生時，將觸發事件與 WebView 中網址的頂層來源建立關聯。

     • androidx.webkit.WebViewSettingsCompat這個方法會指定 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 登錄來源和觸發事件的功能。

   1. 從 WebView 登錄來源和觸發事件

   2. 廣告技術應使用 Attribution-Reporting-Register-OS-Source 標頭回應來源登錄。根據 WebView 的設定行為，系統會呼叫 registerSource() 或 registerWebSource()，並從 Android 歸因報表 API 對廣告技術 URI 發出次要 API 呼叫。

      • 如要完成來源註冊，廣告技術的端點應使用回應標頭，回應 Android Attribution Reporting API 要求。

       Attribution-Reporting-Register-OS-Source: {
        "source_event_id":"123001",
        "destination":"android-app://com.example.advertiser",
        ...
      }
      

   3. 來源註冊的其餘部分則維持不變。

   4. 廣告技術應使用 Attribution-Reporting-Register-OS-Trigger 標頭回應觸發事件登錄。根據 WebView 的設定行為，系統會使用 OS 呼叫 registerTrigger() 或 registerWebTrigger()，並從 Rb 對廣告技術 URI 發出次要 API 呼叫。

   5. 如要完成觸發條件登錄程序，廣告技術的端點應使用回應標頭，回應 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"]}
       ],
       ...
   }
   

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

偵錯

設定應用程式到網站導入作業時，建議設定偵錯報告，確認來源和觸發條件是否已正確登錄，如果未登錄，則可取得相關資訊。

如需一般歸因報表偵錯步驟，請參閱偵錯指南。