Przejdź na interfejs API do raportowania w wersji 1

Dostępna jest nowa wersja interfejsu Reporting API. Zapewnia większą prywatność i jest bardziej prawdopodobne, że będzie obsługiwany w różnych przeglądarkach.

Maud Nalpas

Interfejs Reporting API informuje o błędach występujących w Twojej witrynie podczas jej użytkowania przez użytkowników. Dzięki niemu możesz sprawdzać interwencje przeglądarki, jej awarie, naruszenia zasad Content Security Policy, naruszenia zasad COOP/COEP, ostrzeżenia o wycofaniu i inne.

Dostępna jest nowa wersja interfejsu Reporting API. Nowy interfejs API jest bardziej zwięzły i bardziej prawdopodobne, że będzie obsługiwany w różnych przeglądarkach.

Podsumowanie

Deweloperzy witryn

Jeśli masz już w swojej witrynie funkcję raportowania: przejdź na wersję 1, używając nowego nagłówka (Reporting-Endpoints), ale przez jakiś czas zachowaj stary nagłówek (Report-To). Zobacz Przejście na wersję 1: przykładowy kod.

Jeśli dopiero teraz dodajesz do swojej witryny funkcję raportowania: użyj tylko nowego nagłówka (Reporting-Endpoints).

⚠️ W obu przypadkach pamiętaj, aby ustawić nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

Deweloperzy usług raportowania

Jeśli zarządzasz usługą punktu końcowego lub korzystasz z własnej, spodziewaj się większego ruchu, gdy Ty lub zewnętrzni deweloperzy przejdziecie na interfejs Reporting API w wersji 1 (nagłówek Reporting-Endpoints).

Czytaj dalej, aby dowiedzieć się więcej i poznać przykładowy kod.

Rejestrowanie błędów sieci

Zostanie opracowany nowy mechanizm rejestrowania błędów sieci. Gdy to nastąpi, przejdź z interfejsu Reporting API w wersji 0 na nowy mechanizm.

Wersja demonstracyjna i kod

• Witryna demonstracyjna: nowy interfejs Reporting API (wersja 1)
• Kod witryny demonstracyjnej

Różnice między wersjami 0 i 1

Co się zmienia

• Interfejs API jest inny.

 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

• Zakres raportu jest inny.

• Oba interfejsy API obsługują te same typy raportów z jednym wyjątkiem: wersja 1 nie obsługuje raportów o błędach sieciowych. Więcej informacji znajdziesz w instrukcji migracji.
• Wersja 0 nie jest i nie będzie obsługiwana we wszystkich przeglądarkach. W przyszłości prawdopodobnie będziemy obsługiwać wersję 1.

Co pozostaje bez zmian

• Format i struktura raportów nie uległy zmianie.
• Żądanie wysłane przez przeglądarkę do punktu końcowego pozostaje żądaniem POST o wartości Content-type application/reports+json.
• Mapowanie niektórych punktów końcowych na określone typy raportów jest obsługiwane zarówno w wersji 0, jak i w wersji 1.
• Rola punktu końcowego default pozostaje niezmieniona.

• Interfejs API do raportowania w wersji 1 nie ma wpływu na ReportingObserver. Użytkownik ReportingObserver nadal ma dostęp do wszystkich raportów obserwowalnych, a ich format jest identyczny.

Wszystkie różnice między wersjami 0 i 1

Deweloperzy punktów końcowych: spodziewajcie się większego ruchu

Jeśli masz skonfigurowany własny serwer jako punkt końcowy raportowania lub tworzysz lub utrzymujesz usługę zbierania raportów, spodziewaj się większego ruchu na tym punkcie końcowym.

Wynika to z tego, że w interfejsie Reporting API w wersji 1 raporty nie są grupowane, jak w interfejsie Reporting API w wersji 0. Gdy deweloperzy aplikacji zaczną przechodzić na interfejs Reporting API w wersji 1, liczba raportów pozostanie podobna, ale objętość żądań do serwera punktu końcowego wzrośnie.

Deweloperzy aplikacji: migracja do Reporting-Endpoints (wersja 1)

Co musisz zrobić?

Korzystanie z nowego interfejsu Reporting API (w wersji 1) niesie ze sobą kilka korzyści: ✅

• Sygnały z przeglądarki są dodatnie, co oznacza, że można oczekiwać obsługi wersji 1 w różnych przeglądarkach (w przeciwieństwie do wersji 0, która jest obsługiwana tylko w Chrome i Edge).
• Interfejs API jest prostszy.
• Narzędzia są opracowywane pod kątem nowego interfejsu API do raportowania (w wersji 1).

Mając to na uwadze:

• Jeśli Twoja witryna korzysta już z interfejsu Reporting API w wersji 0 z nagłówkiem Report-To, przeprowadź migrację do interfejsu Reporting API w wersji 1 (patrz sposób przeprowadzenia migracji). Jeśli Twoja witryna korzysta już z funkcji zgłaszania naruszeń dyrektywy Content Security Policy, zapoznaj się z szczegółami migracji w przypadku zgłaszania naruszeń CSP.
• Jeśli Twoja witryna nie korzysta jeszcze z interfejsu Reporting API i dodajesz do niej funkcję raportowania: użyj nowego interfejsu Reporting API (w wersji 1) (nagłówek Reporting-Endpoints). Jest jednak jedno zastrzeżenie: jeśli musisz używać rejestrowania błędów sieci, użyj Report-To (w wersji 0). Logowanie błędów sieci nie jest obecnie obsługiwane w interfejsie Reporting API w wersji 1. Będziemy opracowywać nowy mechanizm rejestrowania błędów sieci. Do tego czasu używaj interfejsu Reporting API w wersji 0. Jeśli potrzebujesz rejestrowania błędów sieci oraz innych typów raportów, użyj obu opcji Report-To (wersja 0) i Reporting-Endpoints (wersja 1). Wersja 0 umożliwia rejestrowanie błędów sieci, a wersja 1 – raportowanie wszystkich innych typów.

Etapy migracji

Celem tej migracji jest uniknięcie utraty raportów, które były dostępne w wersji 0.

1. Krok 1 (do tej pory): użyj obu nagłówków: Report-To (w wersji 0) i Reporting-Endpoints (w wersji 1).

   Dzięki temu:

   • Raporty z nowych klientów Chrome i Edge dzięki Reporting-Endpoints (w wersji 1).
   • Raporty ze starszych klientów Chrome i Edge dzięki interfejsowi Report-To (w wersji 0).

   Instanse przeglądarki, które obsługują Reporting-Endpoints, będą używać Reporting-Endpoints, a te, które nie obsługują, będą używać Report-To. Format żądania i raportu jest taki sam w przypadku wersji 0 i 1.

2. Krok 2 (do tej pory): sprawdź, czy nagłówek Reporting-Endpoints jest ustawiony we wszystkich odpowiedziach, które mogą generować raporty.

   W wersji 0 można było ustawić punkty końcowe raportowania tylko w niektórych odpowiedziach, a inne dokumenty (strony) w tym pochodzeniu używały tego „ambientalnego” punktu końcowego. W wersji 1 ze względu na różnice w zakresie działania musisz ustawić nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

3. Krok 3 (rozpocznij później): gdy wszyscy lub większość użytkowników zaktualizują Chrome lub Edge do nowszych wersji (96 i nowszych), usuń Report-To (w wersji 0) i zachowaj tylko Reporting-Endpoints.

   Wyjątek: jeśli potrzebujesz raportów z rejestrowania błędów sieciowych, zachowaj Report-To do czasu wdrożenia nowego mechanizmu rejestrowania błędów sieciowych.

Przykłady kodu znajdziesz w książce kucharskiej migracji.

Kroki migracji dotyczące raportowania w CSP

Raporty o naruszeniu Content-Security-Policy można skonfigurować na 2 sposoby:

• Tylko nagłówek CSP za pomocą dyrektywy report-uri. Ta funkcja jest obsługiwana w wielu przeglądarkach, takich jak Chrome, Firefox, Safari i Edge. Raporty są wysyłane z typem treści application/csp-reporti mają format właściwy dla CSP. Te raporty nazywają się „Raporty CSP poziomu 2” i nie są zależne od interfejsu Reporting API.
• W przypadku interfejsu Reporting API można to zrobić za pomocą nagłówka Report-To (w starszej wersji) lub nowszego nagłówka Reporting-Endpoints (w wersji 1). Ta funkcja jest obsługiwana tylko w Chrome i Edge. Prośby o raporty mają ten sam format co inne żądania interfejsu Reporting API i mają ten sam typ treści application/reports+json.

Pierwsze podejście (tylko report-uri) nie jest już zalecane, a drugie podejście ma kilka zalet. W szczególności umożliwia to skonfigurowanie raportowania we wszystkich typach raportów za pomocą jednej metody oraz ustawienie ogólnego punktu końcowego (ponieważ wszystkie żądania raportu wygenerowane za pomocą interfejsu Reporting API⏤CSP i innych⏤ mają ten sam format: application/reports+json.

Jednak report-to obsługuje tylko kilka przeglądarek. Dlatego zalecamy, aby report-uri stosować równolegle z interfejsem API do raportowania (Report-To lub lepiej Reporting-Endpoints), aby otrzymywać raporty o naruszeniu zasad CSP z wielu przeglądarek. W przeglądarce, która rozpoznaje report-uri i report-to, zasada report-uri zostanie zignorowana, jeśli obecna jest zasada report-to. W przeglądarce, która rozpoznaje tylko report-uri, brany pod uwagę będzie tylko report-uri.

1. Krok 1 (do tej pory): jeśli nie dodano jeszcze tego parametru, dodaj report-to obok report-uri. Przeglądarki, które obsługują tylko report-uri (Firefox), będą używać report-uri, a przeglądarki, które obsługują też report-to(Chrome, Edge), będą używać report-to. Aby określić nazwane punkty końcowe, których użyjesz w report-to, użyj nagłówków Report-To i Reporting-Endpoints. Dzięki temu będziesz otrzymywać raporty zarówno ze starszych, jak i nowszych klientów Chrome i Edge.

2. Krok 3 (rozpocznij później): gdy wszyscy lub większość użytkowników zaktualizują Chrome lub Edge do nowszych wersji (96 i nowszych), usuń Report-To (w wersji 0) i zachowaj tylko Reporting-Endpoints. Zachowaj report-uri, aby nadal otrzymywać raporty z przeglądarek, które obsługują tylko tę metodę.

Przykłady kodu dla tych kroków znajdziesz w artykule Migrowanie raportowania z usług CSP.

Migracja: przykładowy kod

Omówienie

Jeśli korzystasz z poprzedniej wersji interfejsu Reporting API (w wersji 0), aby otrzymywać raporty o naruszeniu zasad dotyczących: – zasad COOP (główny nagłówek Cross-Origin-Opener-Policy), – zasad COEP (główny nagłówek Cross-Origin-Embedder-Policy) lub – zasad dotyczących dokumentu (główny nagłówek Document-Policy). Nie musisz zmieniać tych nagłówków zasad podczas migracji do interfejsu Reporting API w wersji 1. Musisz tylko przejść z starego nagłówka Report-To na nowy nagłówek Reporting-Endpoints.

Jeśli używasz starszego interfejsu Reporting API (wersja 0) do otrzymywania raportów o naruszeniu zasad dotyczących mechanizmu CSP (nagłówek Content-Security-Policy), w ramach migracji na nowy interfejs Reporting API (wersja 1) możesz potrzebować dostosowania Content-Security-Policy.

Podstawowa migracja

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"

Pamiętaj, że w wersji 1 nadal możesz wysyłać określone typy raportów do określonych punktów końcowych. Możesz jednak użyć tylko 1 adresu URL na punkt końcowy.

Obserwowanie wszystkich stron

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(...)
});

Migracja raportów 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: ...

Więcej informacji

• Monitorowanie aplikacji internetowej za pomocą interfejsu Reporting API (główny wpis na temat interfejsu Reporting API)
• Specyfikacja: starsza wersja interfejsu Reporting API (wersja 0)
• Specyfikacja: nowy interfejs Reporting API (wersja 1)

Dziękujemy Ianowi Clellandowi, Eiji Kitamurze i Milicy Mihajlija za opinie i sugestie dotyczące tego artykułu.