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żywania 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ędzie obsługiwana wersja 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 jeśli 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 przypadku interfejsu 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 przeglądarki są dodatnie, co oznacza, że można oczekiwać obsługi wersji 1 w wielu 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ń 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 (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 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 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 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 we wszystkich typach 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 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 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 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ł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 dotyczących: – zasad COOP (nagłówek Cross-Origin-Opener-Policy), – zasad COEP (nagłówek Cross-Origin-Embedder-Policy) lub – zasad dotyczących dokumentów (nagłówek Document-Policy). Podczas migracji do interfejsu Reporting API w wersji 1 nie musisz zmieniać nagłówków zasad. 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 uzyskiwania raportów o naruszeniu zasad dotyczących nagłówka CSP (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.