遷移至 Reporting API v1

Reporting API 已推出新版本。不同瀏覽器也較有保障隱私。

Maud Nalpas

注意：本文內容說明如何遷移至新版 Reporting API (v1)。如果您是第一次使用 Reporting API，或需要詳細的使用範例，請改為參閱 Reporting API 的主要文章。

Reporting API 會通知您網站訪客使用這項工具時發生的錯誤。方便您掌握瀏覽器介入項目、瀏覽器當機、違反內容安全政策的情形、違反 COOP/COEP 政策的情形、淘汰警告等等。

新版 Reporting API 已推出。這個新的 API 變得更精簡，且有可能跨瀏覽器支援。

注意：舊版 Reporting API 的名稱是 Reporting API v0。新的 Reporting API 名為 Reporting API v1。

摘要

網站開發人員

如果您已經為網站提供報表功能：請使用新標頭 (Reporting-Endpoints) 遷移至 v1，但請暫時保留舊版標頭 (Report-To)。請參閱遷移：範例程式碼。

如果您現在要為網站新增報表功能：請使用新的標題 (Reporting-Endpoints)。

⚠️ 在這兩種情況下，請務必為所有可能產生報表的回應設定 Reporting-Endpoints 標頭。

報表服務開發人員

如果您維護的是端點服務，或是正在營運，則在您或外部開發人員遷移至 Reporting API v1 (Reporting-Endpoints 標頭) 時，預期會有更多流量。

請繼續閱讀詳細資料和程式碼範例！

網路錯誤記錄

注意：如果您使用網路錯誤記錄功能，請繼續使用 Report-To (v0)，因為 Reporting API v1 不支援網路錯誤記錄。

我們將開發網路錯誤記錄功能的新機制。推出之後，請從 Reporting API v0 切換到新機制。

示範模式和程式碼

• 示範網站：新版報表 API (v1)
• 示範網站的程式碼

v0 和 v1 之間的差異

異動內容

• API 介面不同。

v0 (舊版)

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 使用 Report-To 標頭設定已命名的端點群組，而其他標頭中的 report-to 指令則用於參照這些端點群組。

v1 (新)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

v1 會使用 Reporting-Endpoints 標頭設定已命名的端點。和 v0 一樣，會使用其他標頭中的 report-to 指令來參照這些端點群組。

• 報表範圍不同，

v0 (舊版)

使用 v0 時，可以僅針對部分回應設定報告端點。該來源的其他文件 (頁面) 會自動使用這些環境端點。

v1 (新)

使用 v1 時，您需要為所有可能產生報表的回應設定 Reporting-Endpoints 標頭。

• 這兩個 API 支援相同的報表類型，但有一個例外：v1 不支援網路錯誤報表。詳情請參閱遷移步驟。
• v0 尚不支援，且將不支援所有瀏覽器。未來使用多個瀏覽器可能都會支援 v1。

維持不變的部分

• 報表的格式和結構維持不變。
• 瀏覽器傳送至端點的要求仍會保留 Content-type application/reports+json 的 POST 要求。
• 第 0 版和第 1 版都支援將特定端點對應到特定報表類型。
• default 端點的角色維持不變。

• Reporting API 第 1 版不會影響 ReportingObserver。ReportingObserver 會繼續存取所有可觀測的報表，且格式相同。

v0 和 v1 之間的所有差異

	舊版 Reporting API (v0) Report-To 標頭	新版 Reporting API (v1) Reporting-Endpoints 標頭
瀏覽器支援	Chrome 69 以上版本和 Edge 69 以上版本。	Chrome 96 以上版本和 Edge 96 以上版本。Firefox 支援支援。Safari 無法滿足物件的要求。請參閱瀏覽器信號。
端點	將報表傳送給「多個」報表收集器 (每個端點群組定義多個網址)。	將報表傳送給特定報表收集器 (每個端點只能定義一個網址)。
API 介面	使用 `Report-To` 標頭設定已命名的端點群組。	使用 `Reporting-Endpoints` 標頭設定已命名的端點。
可透過這個 API 產生的報表類型	淘汰 幹預 意外事故 COOP/COEP 內容安全政策級別 3 (CSP 層級 3) 網路錯誤記錄 (NEL) 如要進一步瞭解報表類型，請參閱 Reporting API 文章。	維持不變，除了網路錯誤記錄 (NEL) 以外：新版 Reporting API (v1) 不支援這項功能。
報表範圍	同源內容。 文件的 Report-To 標頭會影響來自該來源的其他文件 (頁面)。報表的 url 欄位依文件而異。	文件。 文件的 Reporting-Endpoints 標頭只會影響該文件。報表的 url 欄位依文件而異。
報表隔離 (批次處理)	凡是在相同時間產生報表，且具有相同報表端點的不同文件 (網頁) 或網站/來源，都會分批加入：系統會在同一個訊息中將這些文件 (網頁) 或來源傳送到報表端點。	來自不同文件 (頁面) 的報表一律不會一併傳送。即使同一來源的兩份文件 (頁面) 同時產生報表，但同一個端點的資料也不會批次處理。這項機制可防範隱私權攻擊。 系統可能會一併傳送同一文件 (頁面) 的報表。
支援負載平衡 / 優先順序	是	否

端點開發人員：預期流量會增加

如果您已將自己的伺服器設為回報端點，或正在開發或維護報表收集器做為服務，則流量可能會增加到該端點。

這是因為報表不會因為 Reporting API v1 批次處理，跟 Reporting API v0 不同。因此，隨著應用程式開發人員開始遷移至 Reporting API v1，報表數量會維持不變，但傳送至端點伺服器的「要求量」將會增加。

應用程式開發人員：遷移至 Reporting-Endpoints (v1)

此時該如何處理這種狀況？

使用新的 Reporting API (v1) 有幾項好處 ✅：

• 瀏覽器信號具有「陽性」，這表示第 1 版支援跨瀏覽器支援 (不同於僅限 Chrome 和 Edge 的 v0)。
• API 較精簡，
• 工具是根據新的 Reporting API (v1) 開發。

瞭解這點之後：

• 如果您的網站已使用具有 Report-To 標頭的 Reporting API v0，請遷移至 Reporting API v1 (請參閱遷移步驟)。如果您的網站已經使用回報功能處理違反內容安全政策的行為，請查看特定的 CSP 報告遷移步驟。
• 如果您的網站尚未使用 Reporting API，而現在想要新增報表功能，請使用新的 Reporting API (v1) (Reporting-Endpoints 標頭)。例外情況：如需使用網路錯誤記錄，請使用 Report-To (v0)。Reporting API v1 目前不支援網路錯誤記錄。我們將開發網路錯誤 Logging 的新機制⏤un 直到可用，請使用 Reporting API v0。如果您需要網路錯誤記錄和其他報表類型，請使用 Report-To (v0) 和 Reporting-Endpoints (v1)。v0 提供的網路錯誤記錄和 v1 可提供所有其他類型的報表。

遷移步驟

這次遷移作業的目標，是要不會遺失之前用於 v0 的報表。

注意：只有 Chrome 和 Edge 支援 Reporting API v0，因此在遷移至第 1 版時，您不必專注於其他瀏覽器。不過請注意，我們日後可能會支援更多瀏覽器。這些瀏覽器目前未發生追蹤錯誤，但可能會發生變更。

1. 步驟 1 (立即執行)：同時使用兩個標頭：Report-To (v0) 和 Reporting-Endpoints (v1)。

   如此一來，您就能：

   • Reporting-Endpoints (第 1 版) 由新版 Chrome 和 Edge 用戶端提供的報告。
   • Report-To (v0) 來自舊版 Chrome 和 Edge 用戶端的報告。

   支援 Reporting-Endpoints 的瀏覽器執行個體將使用 Reporting-Endpoints，且執行個體不會改回使用 Report-To。v0 和 v1 的要求和報表格式相同。

2. 步驟 2 (現在採取的行動)：確保所有可能會產生報表的回應都設有 Reporting-Endpoints 標頭。

   使用 v0 時，您可以選擇只針對部分回應設定報告端點，而該來源上的其他文件 (頁面) 將使用此「微量」端點。由於使用 v1 時，由於範圍設定不同，您需要為所有可能產生報表的回應設定 Reporting-Endpoints 標頭。

3. 步驟 3 (之後開始)：所有或大部分使用者都更新為之後的 Chrome 或 Edge 安裝作業 (96 以上版本) 後，請移除 Report-To (v0) 並僅保留 Reporting-Endpoints。

   例外狀況：如果您需要網路錯誤記錄報告，請保留 Report-To，直到網路錯誤記錄採用新機制為止。

查看遷移教戰手冊中的程式碼範例。

CSP 報告遷移步驟

有兩種方式可以設定 Content-Security-Policy 違規報告：

• 透過 report-uri 指令單獨使用 CSP 標頭。這可在 Chrome、Firefox、Safari 和 Edge 中支援廣泛的瀏覽器。報告會以內容類型 application/csp-report 的形式傳送，並且採用 CSP 專屬格式。這些報表稱為「CSP 層級 2 報告」，但「不」採用 Reporting API。
• 使用 Reporting API 時，透過 Report-To 標頭 (舊版) 或新版 Reporting-Endpoints (v1)。這項功能僅適用於 Chrome 和 Edge。報表要求的格式與其他 Reporting API 要求格式相同，且內容類型 application/reports+json 也相同。

我們已不再推薦使用第一個方法 (只有 report-uri)，而第二種方法有幾個優點。具體來說，您可透過單一方式為所有報表類型設定報表，以及設定一般端點 (因為所有透過 Reporting API 產生⏤和其他其他報表請求的 application/reports+json 格式 ⏤ )。

不過，只有部分瀏覽器支援 report-to。 因此，建議您保留 report-uri 以及 Reporting API 方法 (Report-To 或更好的 Reporting-Endpoints)，以便從多個瀏覽器取得 CSP 違規報告。在可辨識 report-uri 和 report-to 的瀏覽器中，如果 report-to 存在，系統會忽略 report-uri。在只能辨識 report-uri 的瀏覽器中，系統只會考慮 report-uri。

1. 步驟 1 (立即執行)：如果您尚未新增，請同時新增 report-to 和 report-uri。僅支援 report-uri (Firefox) 的瀏覽器將使用 report-uri，而支援 report-to(Chrome、Edge) 的瀏覽器將會使用 report-to。如要指定在 report-to 中使用的已命名端點，請同時使用 Report-To 和 Reporting-Endpoints 標頭。這樣可確保您取得的報告都是來自舊版及較新的 Chrome 和 Edge 用戶端。

2. 步驟 3 (之後開始)：所有或大部分使用者都更新為之後的 Chrome 或 Edge 安裝作業 (96 以上版本) 後，請移除 Report-To (v0) 並僅保留 Reporting-Endpoints。保留 report-uri，您仍然只會收到瀏覽器是否支援該報告。

請參閱 CSP 報表遷移中這些步驟的程式碼範例。

遷移：範例程式碼

總覽

如果您是使用舊版 Reporting API (v0) 取得 COOP (Cross-Origin-Opener-Policy 標頭)、COEP (Cross-Origin-Embedder-Policy) 或文件政策 (Document-Policy 標頭) 的違規報告：遷移至 Reporting API v1，您不需要自行變更這些政策標頭。您需要從舊版 Report-To 標頭遷移至新的 Reporting-Endpoints 標頭。

如果您使用舊版 Reporting API (v0) 取得 CSP (Content-Security-Policy 標頭) 的違規報表，則可能需要在遷移至新版 Reporting API (v1) 時調整 Content-Security-Policy。

基本遷移

舊版程式碼 (包含 v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

新程式碼 (搭配 v1 使用 v0 的轉換程式碼)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

如果您的網站已有報表功能，請暫時保留 Report-To (直到大多數 Chrome 和 Edge 用戶端完成更新為止)，以免遺失報表。

如果您需要網路錯誤記錄，請保留 Report-To，直到「網路錯誤 Logging 可替換為止」。

新程式碼 (僅限 v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

大多數 Chrome 和 Edge 用戶端都完成更新，並支援 API v1 後，程式碼日後看起來會像這樣。

請注意，使用 v1 時，您還是可以將特定報表類型傳送至特定的端點。不過，每個端點只能有一個網址。

觀察所有網頁

舊版程式碼 (包含 v0)，例如 Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

使用 v0 時，可以僅針對部分回應設定報告端點。該來源的其他文件 (頁面) 會自動使用這些環境端點。在本例中，針對 "/" 設定的端點會用於所有回應，例如 page1。

新程式碼 (包含 v1)，例如 Express

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

使用 v1 時，您必須在所有可能產生報表的回應中設定 Reporting-Endpoints 標頭。

遷移 CSP 報告

舊版程式碼，僅包含 report-uri

Content-Security-Policy: ...; report-uri https://reports.example/main

我們不再建議僅使用 report-uri。如果您的程式碼與上述項目類似，請進行遷移。請參閱下方的新程式碼範例 (綠色)。

更理想的舊版程式碼，使用 report-uri 和具有 Report-To (v0) 標頭的 report-to 指令

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

這樣的情況比較好：這個程式碼使用「report-to」來取代 report-uri。但仍會保留 report-uri，藉此確保回溯相容性；多個瀏覽器不支援 report-to，但支援 report-uri。

不過，但可能更好：這段程式碼使用 Reporting API v0 (Report-To 標頭)。遷移至 v1：請參閱下方的「新程式碼範例」範例 (綠色)。

新增程式碼，含有 report-uri 和含有 Reporting-Endpoint (v1) 標頭的 report-to 指令

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

請保持 report-uri 指令與 report-to 指令，直到瀏覽器支援 report-to 指令為止。請參閱瀏覽器相容性表格。

暫時保留「Report-To」和「Reporting-Endpoints」。大部分 Chrome 和 Edge 訪客將瀏覽器版本升級至 96 以上版本後，請移除 Report-To。

其他資訊

• 使用 Reporting API 監控網頁應用程式 (Reporting API 的主要文章)
• 規格：舊版 Reporting API (v0)
• 規格：新版 Reporting API (v1)

主頁橫幅由 Nine Koepfer / @enka80 在 Unsplash 網站上編輯。感謝 Ian Clelland、Eiji Kitamura 和 Milica Mihajlija，針對這篇文章的評論和建議，我們由衷感謝。