Przejdź na interfejs API do raportowania w wersji 1

Dostępna jest nowa wersja interfejsu API do raportowania. Zapewnia to większą prywatność i jest większa szansa na to, że będzie obsługiwany w różnych przeglądarkach.

Maud Nalpas

Interfejs API do raportowania informuje o błędach, które pojawiają się w witrynie, gdy użytkownicy z niej korzystają. Informuje o interwencjach przeglądarek, awariach przeglądarki, naruszeniach zasad zabezpieczeń zawartości, naruszeń COOP/COEP, ostrzeżeniami o wycofaniu usługi i nie tylko.

Dostępna jest nowa wersja interfejsu API do raportowania. Nowy interfejs API jest udoskonalony i prawdopodobnie będzie obsługiwany w różnych przeglądarkach.

Podsumowanie

Deweloperzy witryn

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

Jeśli dodajesz w witrynie funkcję raportowania od razu: używaj tylko nowego nagłówka (Reporting-Endpoints).

⚠️ W obu przypadkach ustaw nagłówek Reporting-Endpoints w przypadku wszystkich odpowiedzi, które mogą generować raporty.

Deweloperzy usług raportowania

Jeśli korzystasz z usługi punktu końcowego lub używasz własnej usługi, możesz spodziewać się większego ruchu w miarę przejścia przez Ciebie lub zewnętrznych deweloperów na interfejs Reporting API w wersji 1 (nagłówek Reporting-Endpoints).

Czytaj dalej, aby poznać szczegóły i przykładowy kod.

Logowanie błędów sieciowych

Opracowany zostanie nowy mechanizm logowania błędów sieciowych. Gdy będzie on dostępny, przejdź z interfejsu Reporting API w wersji 0 na ten nowy mechanizm.

Demonstracja i kod

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

Różnice między wersjami v0 i v1

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 sieci. Więcej informacji znajdziesz w sekcji Migracja.
• Wersja v0 nie jest i nie będzie obsługiwana w różnych przeglądarkach. Prawdopodobnie będzie ona w przyszłości obsługiwana w różnych przeglądarkach.

Co się nie zmieniło

• Format i struktura raportów nie uległy zmianie.
• Żądanie wysłane przez przeglądarkę do punktu końcowego pozostaje żądaniem POST 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 1.
• Rola punktu końcowego default nie została zmieniona.

• Interfejs Reporting API w wersji 1 nie ma wpływu na środowisko ReportingObserver. ReportingObserver nadal ma dostęp do wszystkich dostępnych raportów, a ich format jest identyczny.

Wszystkie różnice między wersjami v0 i v1

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

Jeśli masz skonfigurowany własny serwer jako punkt końcowy raportowania albo tworzysz lub utrzymujesz kolektor raportów jako usługę, spodziewaj się większego ruchu do tego punktu końcowego.

Dzieje się tak, ponieważ raporty nie są grupowane w wersji 1 interfejsu Reporting API (w wersji 1), jak w przypadku interfejsu Reporting API v0. Dlatego gdy deweloperzy aplikacji zaczną przechodzić na interfejs Reporting API w wersji 1, liczba raportów pozostanie podobna, ale liczba żądań do serwera punktu końcowego będzie się zwiększać.

Programiści aplikacji: Migracja do Reporting-Endpoints (wersja 1)

Co musisz zrobić?

Korzystanie z nowego interfejsu Reporting API (v1) ma kilka zalet ✅:

• Sygnały z przeglądarki są pozytywne, co oznacza, że wersja 1 będzie obsługiwać wiele przeglądarek (w przeciwieństwie do wersji 0, która jest obsługiwana tylko w Chrome i Edge).
• Interfejs API jest udoskonalony.
• Pracujemy nad narzędziami związanymi z nowym interfejsem Reporting API (v1).

Pamiętaj o tym:

• Jeśli Twoja witryna korzysta już z interfejsu Reporting API w wersji 0 z nagłówkiem Report-To, przejdź na interfejs Reporting API w wersji 1 (patrz instrukcje migracji). Jeśli Twoja witryna korzysta już z funkcji zgłaszania naruszeń zasad bezpieczeństwa treści, zapoznaj się z instrukcją migracji raportów CSP.
• Jeśli Twoja witryna nie korzysta jeszcze z interfejsu API do raportowania i dodajesz funkcję raportowania, użyj nowego interfejsu Reporting API (v1) (nagłówka Reporting-Endpoints). Jest jeden wyjątek: jeśli chcesz korzystać z logowania błędów sieci, użyj Report-To (v0). Logowanie błędów sieciowych nie jest obecnie obsługiwane w interfejsie Reporting API w wersji 1. Opracujemy nowy mechanizm logowania błędów sieciowych ⏤ Dopóki nie będzie dostępny, używaj interfejsu Reporting API w wersji 0. Jeśli logowanie błędów sieci potrzebujesz razem z innymi typami raportów, użyj zarówno Report-To (v0), jak i Reporting-Endpoints (1). Wersja 0 umożliwia rejestrowanie błędów sieciowych, a wersja 1 – raporty wszystkich innych typów.

Etapy migracji

W ramach tej migracji chcesz nie utracić 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 generowane przez nowsze klienty Chrome i Edge za pomocą usługi Reporting-Endpoints (v1).
   • Raporty generowane przez starsze klienty Chrome i Edge za pomocą Report-To (v0).

   Instancje przeglądarki, które obsługują Reporting-Endpoints, będą używać Reporting-Endpoints, a instancje, które nie korzystają z metody Report-To. Format żądania i raportu jest taki sam w wersjach v0 i 1.

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

   W wersji 0 punkty końcowe raportowania można ustawić tylko w przypadku niektórych odpowiedzi, a inne dokumenty (strony) w tym źródle będą używać tego punktu końcowego „otwartego”. Ze względu na różnice w zakresie w wersji 1 musisz ustawiać nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

3. Krok 3 (Rozpocznij później). Gdy wszyscy lub większość Twoich użytkowników zaktualizują Chrome lub Edge do nowszej wersji (96 i nowsze), usuń Report-To (wersja 0) i zachowaj tylko Reporting-Endpoints.

   Jeden wyjątek: jeśli potrzebujesz raportów dotyczących logowania błędów sieci, zachowaj Report-To, dopóki nie zostanie wdrożony nowy mechanizm logowania błędów sieciowych.

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

Etapy migracji raportów CSP

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

• Z samym nagłówkiem CSP za pomocą dyrektywy report-uri. Obsługuje ona szeroką gamę przeglądarek z Chrome, Firefoksa, Safari i Edge. Raporty są wysyłane z typem treści application/csp-report i w formacie dostosowanym do potrzeb CSP. Raporty te są nazywane „raportami CSP poziomu 2” i nie korzystają z interfejsu Reporting API.
• Za pomocą interfejsu API do raportowania można to robić za pomocą nagłówka Report-To (starsza wersja) lub nowszego Reporting-Endpoints (wersja 1). Ta funkcja jest obsługiwana tylko w Chrome i Edge. Żądania raportu mają ten sam format co inne żądania do interfejsu API do raportowania i ten sam typ treści application/reports+json.

Stosowanie pierwszego podejścia (tylko report-uri) nie jest już zalecane, a drugie przynosi kilka korzyści. W szczególności pozwala skonfigurować raportowanie we wszystkich typach raportów w jeden sposób, a także ustawić ogólny punkt końcowy (ponieważ wszystkie żądania raportów generowane za pomocą interfejsu API do raportowania ⏤CSP i inne ⏤ mają ten sam format application/reports+json.

Jednak tylko niektóre przeglądarki obsługują report-to. Dlatego zalecamy stosowanie metody report-uri równolegle z metodą Reporting API (Report-Tolub lepiej Reporting-Endpoints), aby otrzymywać z różnych przeglądarek zgłoszenia o naruszeniach zasad CSP. W przeglądarce, która rozpoznaje report-uri i report-to, ciąg report-uri jest ignorowany, jeśli występuje report-to. W przeglądarce, która rozpoznaje tylko typ report-uri, tylko report-uri zostanie uwzględniony.

1. Krok 1 (wykonaj teraz). Jeśli nie został jeszcze dodany element report-to, dodaj go oprócz pola report-uri. Przeglądarki, które obsługują tylko report-uri (Firefox), będą używać report-uri, a przeglądarki, które również obsługują report-to(Chrome, Edge), będą używać przeglądarki report-to. Aby określić nazwane punkty końcowe, których będziesz używać w usłudze report-to, użyj zarówno nagłówków Report-To, jak 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ść Twoich użytkowników zaktualizują Chrome lub Edge do nowszej wersji (96 i nowsze), usuń Report-To (wersja 0) i zachowaj tylko Reporting-Endpoints. Zachowaj report-uri, aby nadal otrzymywać raporty w przeglądarkach, które ją obsługują.

Przykłady kodu tych czynności znajdziesz w artykule Migracja raportów CSP.

Migracja: przykładowy kod

Przegląd

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

Jeśli do otrzymywania raportów o naruszeniach dotyczących CSP (nagłówek Content-Security-Policy) używasz starszej wersji interfejsu Reporting API (v0), być może musisz zmodyfikować Content-Security-Policy w ramach migracji do nowego interfejsu Reporting API (v1).

Migracja podstawowa

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 wersja 1 pozwala wysyłać określone typy raportów do określonych punktów końcowych. Ale możesz mieć tylko 1 adres 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 przy użyciu interfejsu Reporting API (główny post o interfejsie Reporting API)
• Specyfikacja: starsza wersja interfejsu API do raportowania (wersja 0)
• Specyfikacja: nowy interfejs API do raportowania (wersja 1)

Baner powitalny od Nine Koepfer / @enka80 na kanale Unsplash, edytowany. Podziękowania dla Iana Clellanda, Eiji Kitamury i Milicy Mihajlija za ich opinie i sugestie dotyczące tego artykułu.