Reporting API 已推出新版本。不同瀏覽器也較有保障隱私。
Reporting API 會通知您網站訪客使用這項工具時發生的錯誤。方便您掌握瀏覽器介入項目、瀏覽器當機、違反內容安全政策的情形、違反 COOP/COEP 政策的情形、淘汰警告等等。
新版 Reporting API 已推出。這個新的 API 變得更精簡,且有可能跨瀏覽器支援。
摘要
網站開發人員
如果您已經為網站提供報表功能:請使用新標頭 (Reporting-Endpoints
) 遷移至 v1,但請暫時保留舊版標頭 (Report-To
)。請參閱遷移:範例程式碼。
如果您現在要為網站新增報表功能:請使用新的標題 (Reporting-Endpoints
)。
⚠️ 在這兩種情況下,請務必為所有可能產生報表的回應設定 Reporting-Endpoints
標頭。
報表服務開發人員
如果您維護的是端點服務,或是正在營運,則在您或外部開發人員遷移至 Reporting API v1 (Reporting-Endpoints
標頭) 時,預期會有更多流量。
請繼續閱讀詳細資料和程式碼範例!
網路錯誤記錄
我們將開發網路錯誤記錄功能的新機制。推出之後,請從 Reporting API v0 切換到新機制。
示範模式和程式碼
- 示範網站:新版報表 API (v1)
- 示範網站的程式碼
v0 和 v1 之間的差異
異動內容
- API 介面不同。
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
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
- 報表範圍不同,
使用 v0 時,可以僅針對部分回應設定報告端點。該來源的其他文件 (頁面) 會自動使用這些環境端點。
使用 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 產生的報表類型 |
|
維持不變,除了網路錯誤記錄 (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) 有幾項好處 ✅:
瞭解這點之後:
- 如果您的網站已使用具有
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 的報表。
步驟 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 (現在採取的行動):確保所有可能會產生報表的回應都設有
Reporting-Endpoints
標頭。使用 v0 時,您可以選擇只針對部分回應設定報告端點,而該來源上的其他文件 (頁面) 將使用此「微量」端點。由於使用 v1 時,由於範圍設定不同,您需要為所有可能產生報表的回應設定
Reporting-Endpoints
標頭。步驟 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 (立即執行):如果您尚未新增,請同時新增
report-to
和report-uri
。僅支援report-uri
(Firefox) 的瀏覽器將使用report-uri
,而支援report-to
(Chrome、Edge) 的瀏覽器將會使用report-to
。如要指定在report-to
中使用的已命名端點,請同時使用Report-To
和Reporting-Endpoints
標頭。這樣可確保您取得的報告都是來自舊版及較新的 Chrome 和 Edge 用戶端。步驟 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
。
基本遷移
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
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" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
請注意,使用 v1 時,您還是可以將特定報表類型傳送至特定的端點。不過,每個端點只能有一個網址。
觀察所有網頁
app.get("/", (request, response) => { response.set("Report-To", …) response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
// 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(...) });
遷移 CSP 報告
Content-Security-Policy: ...; report-uri https://reports.example/main
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
其他資訊
- 使用 Reporting API 監控網頁應用程式 (Reporting API 的主要文章)
- 規格:舊版 Reporting API (v0)
- 規格:新版 Reporting API (v1)
主頁橫幅由 Nine Koepfer / @enka80 在 Unsplash 網站上編輯。感謝 Ian Clelland、Eiji Kitamura 和 Milica Mihajlija,針對這篇文章的評論和建議,我們由衷感謝。