Przejdź na interfejs API do raportowania w wersji 1

Dostępna jest nowa wersja interfejsu API do raportowania. Zapewnia większą prywatność i jest bardziej prawdopodobne, że będzie obsługiwany przez różne przeglądarki.

Maud Nalpas

Interfejs API do raportowania informuje o błędach, które występują w Twojej witrynie podczas korzystania z niej przez użytkowników. Umożliwia on monitorowanie interwencji przeglądarki, awarii przeglądarki, naruszeń zasad Content Security Policy, naruszeń COOP/COEP, ostrzeżeń o wycofaniu i innych zdarzeń.

Dostępna jest nowa wersja interfejsu API do raportowania. Nowy interfejs API jest prostszy i bardziej prawdopodobne jest, że będzieobsługiwany przez różne przeglądarki.

Podsumowanie

Deweloperzy witryn

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

Jeśli dopiero teraz dodajesz do witryny funkcję raportowania: używaj 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 utrzymujesz usługę punktu końcowego lub zarządzasz własną, spodziewaj się większego ruchu, ponieważ Ty i zewnętrzni programiści będziecie migrować do interfejsu API do raportowania w wersji 1 (nagłówek Reporting-Endpoints).

Szczegółowe informacje i przykładowy kod znajdziesz poniżej.

Rejestrowanie błędów sieci

Zostanie opracowany nowy mechanizm rejestrowania błędów sieci. Gdy ta funkcja będzie dostępna, przejdź z interfejsu API do raportowania w wersji 0 na ten nowy mechanizm.

Wersja demonstracyjna i kod

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

Różnice między wersjami 0 i 1

Co się zmienia

• Zestaw interfejsów 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: interfejs API w wersji 1 nie obsługuje raportów o błędach sieci. Więcej informacji znajdziesz w instrukcji migracji.
• Wersja 0 nie jest i nie będzie obsługiwana w przeglądarkach. Wersja 1 ma większe szanse na obsługę w przyszłości w wielu przeglądarkach.

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 typu Content-type application/reports+json.
• Mapowanie określonych punktów końcowych na określone typy raportów jest obsługiwane w wersjach 0 i 1.
• Rola punktu końcowego default pozostaje bez zmian.

• Interfejs API do raportowania w wersji 1 nie ma wpływu na ReportingObserver. ReportingObserver nadal ma dostęp do wszystkich raportów, które można obserwować, a ich format jest identyczny.

Wszystkie różnice między wersją 0 a wersją 1

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

Jeśli Twój serwer został skonfigurowany jako punkt końcowy raportowania lub jeśli tworzysz lub utrzymujesz kolektor raportów jako usługę, spodziewaj się większego ruchu w tym punkcie końcowym.

Dzieje się tak, ponieważ w interfejsie API do raportowania w wersji 1 raporty nie są przetwarzane zbiorczo, jak w przypadku interfejsu API do raportowania w wersji 0. Dlatego, gdy deweloperzy aplikacji zaczną przechodzić na interfejs API do raportowania w wersji 1, liczba raportów pozostanie podobna, ale liczba żądań wysyłanych do serwera punktu końcowego wzrośnie.

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

Co musisz zrobić?

Korzystanie z nowego interfejsu API do raportowania (wersja 1) ma kilka zalet: ✅

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

Pamiętaj:

• Jeśli Twoja witryna korzysta już z interfejsu API do raportowania w wersji 0 z nagłówkiem Report-To, przeprowadź migrację do interfejsu API do raportowania w wersji 1 (patrz kroki migracji). Jeśli Twoja witryna korzysta już z funkcji raportowania naruszeń standardu Content Security Policy, zapoznaj się z konkretnymi krokami migracji w przypadku raportowania CSP.
• Jeśli Twoja witryna nie korzysta jeszcze z interfejsu API do raportowania, a teraz dodajesz funkcję raportowania: użyj nowego interfejsu API do raportowania (wersja 1) (nagłówek Reporting-Endpoints). Jest jeden wyjątek od tej reguły: jeśli musisz użyć rejestrowania błędów sieci, użyj Report-To (wersja 0). Rejestrowanie błędów sieciowych nie jest obecnie obsługiwane w interfejsie API do raportowania w wersji 1. Zostanie opracowany nowy mechanizm rejestrowania błędów sieciowych. Do tego czasu używaj interfejsu API do raportowania w wersji 0. Jeśli potrzebujesz rejestrowania błędów sieci wraz z innymi typami raportów, użyj obu wersji: Report-To (v0) i Reporting-Endpoints (v1). Wersja v0 umożliwia rejestrowanie błędów sieci, a wersja v1 – generowanie raportów o wszystkich innych typach.

Etapy migracji

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

1. Krok 1 (wykonaj teraz): użyj obu nagłówków: Report-To (v0) i Reporting-Endpoints (v1).

   Dzięki temu zyskujesz:

   • Raporty z nowszych klientów Chrome i Edge dzięki Reporting-Endpoints (wersja 1).
   • Raporty ze starszych klientów Chrome i Edge dzięki Report-To (v0).

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

2. Krok 2 (wykonaj teraz): upewnij się, że nagłówek Reporting-Endpoints jest ustawiony we wszystkich odpowiedziach, które mogą generować raporty.

   W przypadku wersji 0 można było ustawić punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi, a inne dokumenty (strony) w tej domenie używałyby tego „otaczającego” punktu końcowego. W przypadku wersji 1 ze względu na różnice w zakresie 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 zaktualizuje Chrome lub Edge do nowszej wersji (96 lub nowszej), usuń Report-To (v0) i pozostaw tylko Reporting-Endpoints.

   Wyjątek: jeśli potrzebujesz raportów rejestrowania błędów sieciowych, zachowaj Report-To, dopóki nie zostanie wdrożony nowy mechanizm rejestrowania błędów sieciowych.

Przykłady kodu znajdziesz w przewodniku po migracji.

Kroki migracji raportowania CSP

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

• za pomocą samego nagłówka CSP za pomocą dyrektywy report-uri, Jest ona obsługiwana przez wiele przeglądarek, w tym Chrome, Firefox, Safari i Edge. Raporty są wysyłane z typem treści application/csp-report i mają format specyficzny dla CSP. Są to „Raporty CSP na poziomie 2”, które nie korzystają z interfejsu Reporting API.
• W przypadku interfejsu API do raportowania jest to nagłówek Report-To (starszy) lub nowszy nagłówek Reporting-Endpoints (wersja 1). Ta funkcja jest obsługiwana tylko w Chrome i Edge. Żądania raportów mają taki sam format jak inne żądania interfejsu API do raportowania i ten sam typ treści application/reports+json.

Pierwsze podejście (tylko report-uri) nie jest już zalecane, a drugie ma kilka zalet. Umożliwia to w szczególności korzystanie z jednego sposobu konfigurowania raportowania dla wszystkich typów raportów, a także ustawianie ogólnego punktu końcowego (ponieważ wszystkie żądania raportów generowane za pomocą interfejsu Reporting API – CSP i innych – mają ten sam format application/reports+json).

Jednak tylko kilka przeglądarek obsługuje report-to. Dlatego zalecamy, aby oprócz podejścia opartego na interfejsie API do raportowania (Report-To lub nowszym, Reporting-Endpoints) stosować też report-uri, aby otrzymywać raporty o naruszeniach CSP z wielu przeglądarek. W przeglądarce, która rozpoznaje report-uri i report-to, element report-uri zostanie zignorowany, jeśli występuje element report-to. W przeglądarce, która rozpoznaje tylko report-uri, pod uwagę będzie brany tylko znak report-uri.

1. Krok 1. (wykonaj teraz): jeśli jeszcze tego nie zrobiono, 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 będziesz używać 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 zaktualizuje Chrome lub Edge do nowszej wersji (96 lub nowszej), usuń Report-To (v0) i pozostaw tylko Reporting-Endpoints. Zachowaj report-uri, aby nadal otrzymywać raporty dotyczące przeglądarek, które obsługują tylko tę opcję.

Przykłady kodu dla tych kroków znajdziesz w artykule Migracja raportowania CSP.

Migracja: przykładowy kod

Przegląd

Jeśli używasz starszej wersji interfejsu API do raportowania (v0) do pobierania raportów o naruszeniach zasad dotyczących nagłówka COOP (Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy) lub zasad dokumentu (Document-Policy): podczas migracji do interfejsu API do raportowania w wersji 1 nie musisz zmieniać tych nagłówków zasad. Musisz jednak przejść ze starszego nagłówka Report-To na nowy nagłówek Reporting-Endpoints.

Jeśli używasz starszej wersji interfejsu API do raportowania (v0) do uzyskiwania raportów o naruszeniach w przypadku nagłówka CSP (Content-Security-Policy), w ramach migracji na nowy interfejs API do raportowania (v1) może być konieczne dostosowanie 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 przypadku wersji 1 nadal możesz wysyłać określone typy raportów do określonych punktów końcowych. Jednak do każdego punktu końcowego możesz przypisać tylko 1 adres URL.

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 raportowania 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 API do raportowania (główny post o interfejsie API do raportowania)
• Specyfikacja: starszy interfejs API do raportowania (wersja 0)
• Specyfikacja: nowy interfejs API do raportowania (wersja 1)

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