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
Maud Nalpas
X GitHub

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 informacje.

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 sam ją udostępniasz, 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

Różnice między wersjami 0 i 1

Co się zmienia

  • Interfejs API jest inny.
v0 (starsza wersja)
 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} używa nagłówka Report-To do konfigurowania nazwanych grup punktów końcowych, a w innych nagłówkach dyrektywy report-to do odwoływania się do tych grup.

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

Wersja 1 używa nagłówka Reporting-Endpoints do konfigurowania nazwanych punktów końcowych. Podobnie jak w wersji 0, w innych nagłówkach używa ona dyrektywy report-to, aby odwoływać się do tych grup punktów końcowych.

  • Zakres raportu jest inny.
v0 (starsza wersja)

W wersji 0 możesz skonfigurować punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. Inne dokumenty (strony) tego źródła będą automatycznie używać tych punktów końcowych.

wersja 1 (nowa)

W wersji 1 musisz ustawić nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

  • 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ędzie obsługiwana wersja 1.

Co pozostaje bez zmian

  • Format i struktura raportów pozostają niezmienione.
  • Żą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

Starszy interfejs Reporting API (w wersji 0)
Report-To nagłówek		 Nowy interfejs API do raportowania (wersja 1)
Reporting-Endpoints nagłówek
Obsługa przeglądarek Chrome 69 lub nowszy oraz Edge 69 lub nowszy. Chrome 96 lub nowszy oraz Edge 96 lub nowszy. Firefox jest obsługiwany. Safari nie ma nic przeciwko temu. Zobacz sygnały przeglądarki.
Punkty końcowe Wysyła raporty do wielu usług gromadzenia raportów (wiele adresów URL zdefiniowanych na grupę punktów końcowych). Wysyła raporty do określonych zbieraczy raportów (na każdy punkt końcowy można zdefiniować tylko 1 adres URL).
Interfejs API Używa nagłówka `Report-To` do konfigurowania nazwanych grup punktów końcowych. Używa nagłówka `Reporting-Endpoints` do konfigurowania nazwanych punktów końcowych.
Typy raportów, które można wygenerować za pomocą tego interfejsu API
  • Wycofanie
  • interwencji;
  • Wypadek
  • COOP/COEP
  • Content-Security-Policy Level 3 (CSP Level 3)
  • Rejestrowanie błędów sieciowych (NEL)
Więcej informacji o typach raportów znajdziesz w poście na temat interfejsu Reporting API. 		Nie zmienione, z wyjątkiem logowania błędów sieci (NEL): ta funkcja nie jest obsługiwana w nowym interfejsie Reporting API (w wersji 1).
Zakres raportu pochodzenia.
Nagłówek Report-To dokumentu wpływa na inne dokumenty (strony) z tego źródła. Pole url w raporcie nadal różni się w zależności od dokumentu. 		Dokument.
Nagłówek Reporting-Endpoints dokumentu ma zastosowanie tylko do tego dokumentu. Pole url w raporcie nadal różni się w zależności od dokumentu.
Izolacja raportów (pakowanie) Różne dokumenty (strony) lub witryny/źródła, które generują raport mniej więcej w tym samym czasie i mają ten sam punkt końcowy raportowania, zostaną zgrupowane razem: zostaną wysłane w tym samym komunikacie do punktu końcowego raportowania.
  • Raporty z różnych dokumentów (stron) nigdy nie są wysyłane razem. Nawet jeśli 2 dokumenty (strony) z tego samego źródła wygenerują raport w tym samym czasie i dla tego samego punktu końcowego, nie zostaną one zgrupowane. Jest to mechanizm ograniczający ataki na prywatność.
  • Raporty z tego samego dokumentu (strony) mogą być wysyłane razem.
Obsługa równoważenia obciążenia / priorytetów Tak Nie

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. Dlatego, 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 Reporting API (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ń dyrektywy 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 (wersja 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 (w wersji 0) i Reporting-Endpoints (w wersji 1). Opcja 0 umożliwia rejestrowanie błędów sieci, a opcja 1 – raportowanie wszystkich innych typów.

Etapy migracji

Celem tej migracji jest utrzymanie 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 (wersja 0) i Reporting-Endpoints (wersja 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 skonfigurować punkty końcowe raportowania tylko w niektórych odpowiedziach, a inne dokumenty (strony) w tym pochodzeniu używały tego „obciętego” 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 korzystają z 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. Żądania dotyczące raportów mają ten sam format co inne żądania interfejsu Reporting API i ten sam typ treści application/reports+json.

Pierwszego podejścia (tylko report-uri) nie zalecamy, ponieważ drugie podejście ma kilka zalet. W szczególności umożliwia to skonfigurowanie raportowania dla wszystkich typów raportów za pomocą jednej metody oraz ustawienie ogólnego punktu końcowego (ponieważ wszystkie żądania raportów wygenerowane za pomocą interfejsu Reporting API⏤CSP i inne⏤ 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 jest ignorowana, jeśli występuje 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 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 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ługi 360 Analytics do usługi Google Analytics 4.

Migracja: przykładowy kod

Omówienie

Jeśli korzystasz z poprzedniej wersji interfejsu Reporting API (w wersji 0), aby otrzymywać raporty o naruszeniu zasad w ramach zasad: Cross-Origin-Opener-Policy (nagłówek), Cross-Origin-Embedder-Policy (nagłówek) lub Document-Policy (nagłówek): nie musisz zmieniać tych nagłówków zasad podczas migracji do interfejsu Reporting API w wersji 1. Musisz tylko przejść ze 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

Kod starszy (z wersją 0)
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
Nowy kod (kod przejściowy z wersji 0 obok wersji 1)
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" }] }

Jeśli w swojej witrynie masz już funkcję raportowania, zachowaj Report-To tylko tymczasowo (do czasu zaktualizowania większości klientów Chrome i Edge), aby nie stracić raportów.

Jeśli potrzebujesz logowania błędów sieci, zachowaj Report-To do czasu udostępnienia zamiennika.

Nowy kod (tylko w wersji 1)
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Tak może wyglądać Twój kod w przyszłości, gdy większość klientów Chrome i Edge zostanie zaktualizowana i obsługiwać będzie interfejs API w wersji 1.

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

Starszy kod (z wersją 0), na przykład z Express
app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

W wersji 0 możesz skonfigurować punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. Inne dokumenty (strony) w tym pochodzeniu automatycznie korzystają z tych punktów końcowych. W tym przypadku punkty końcowe ustawione dla "/" są używane we wszystkich odpowiedziach, np. dla page1.

Nowy kod (z wersją 1), np. z 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(...)
});

W wersji 1 nagłówek Reporting-Endpoints musisz ustawić we wszystkich odpowiedziach, które mogą generować raporty.

Migracja raportów CSP

Starszy kod, tylko z parametrem report-uri
Content-Security-Policy: ...; report-uri https://reports.example/main

Używanie tylko atrybutu report-uri nie jest już zalecane. Jeśli Twój kod wygląda jak powyżej, przeprowadź migrację. Poniżej (na zielono) znajdziesz przykłady nowego kodu.

Ulepszony kod starszy: dyrektywa report-uri i dyrektywa report-to z nagłówkiem Report-To (wersja 0).
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Lepiej jest użyć kodu, który używa parametru report-to, który jest nowszą wersją parametru report-uri. W celu zachowania zgodności wstecznej nadal zachowuje się parametr report-uri. Wiele przeglądarek nie obsługuje parametru report-to, ale obsługuje parametr report-uri.

Można to jednak ulepszyć: ten kod używa interfejsu API do raportowania w wersji 0 (nagłówek Report-To). Przejście na wersję 1: poniżej znajdziesz przykłady „Nowego kodu” (w kolorze zielonym).

Nowy kod z parametrami report-uri i report-to oraz nagłówkiem Reporting-Endpoints (v1)
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Zachowaj dyrektywę report-uri obok dyrektywy report-to, dopóki ta ostatnia nie będzie obsługiwana we wszystkich przeglądarkach.report-to Zobacz tabelę zgodności z przeglądarkami.

Tymczasowo Report-To będzie się znajdować obok Reporting-Endpoints. Gdy większość użytkowników Chrome i Edge zainstaluje wersję 96 lub nowszą, usuń Report-To.

Więcej informacji

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