Sprawdzanie stanu kodu za pomocą interfejsu ReportingObserver API

Znajdź wycofane interfejsy API w aplikacjach produkcyjnych.

ReportingObserver informuje, gdy witryna używa wycofanego interfejsu API lub gdy dochodzi do interwencji przeglądarki. Podstawowe funkcje pojawiły się po raz pierwszy w Chrome 69. Od wersji Chrome 84 można go używać w skryptach service worker.

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    console.log(report.type, report.url, report.body);
  }
}, {buffered: true});

observer.observe();

Użyj wywołania zwrotnego, aby wysłać raporty do backendu lub dostawcy usług analitycznych w celu analizy.

Dlaczego to jest przydatne? Przed wprowadzeniem tego interfejsu API ostrzeżenia o wycofaniu i interwencji były dostępne w Narzędziach deweloperskich tylko jako komunikaty w konsoli. Interwencje są wywoływane tylko przez różne ograniczenia w świecie rzeczywistym, takie jak warunki urządzenia i sieci. Dlatego podczas tworzenia lub testowania witryny lokalnie możesz nigdy nie zobaczyć tych komunikatów. ReportingObserver rozwiązuje ten problem. Gdy użytkownicy napotkają potencjalne problemy, twórcy stron internetowych mogą otrzymać o nich powiadomienie.

Tło

Jakiś czas temu napisałem post na blogu (Obserwowanie aplikacji internetowej), ponieważ zafascynowało mnie, jak wiele interfejsów API służy do monitorowania „rzeczy”, które dzieją się w aplikacji internetowej. Istnieją na przykład interfejsy API, które mogą obserwować informacje o DOM: ResizeObserver, IntersectionObserver, MutationObserver. PerformanceObserver rejestruje pomiary wydajności. Metody takie jak window.onerror i window.onunhandledrejection informują nas nawet, gdy coś pójdzie nie tak.

Istnieją jednak inne typy ostrzeżeń, które nie są rejestrowane przez istniejące interfejsy API. Gdy Twoja witryna używa wycofanego interfejsu API lub napotyka interwencję przeglądarki, Narzędzia deweloperskie jako pierwsze Cię o tym poinformują:

Ostrzeżenia w konsoli Narzędzi deweloperskich dotyczące wycofanych funkcji i interwencji.
Ostrzeżenia inicjowane przez przeglądarkę w konsoli Narzędzi deweloperskich.

Można by pomyśleć, że window.onerror rejestruje te ostrzeżenia. Nie. Dzieje się tak, ponieważ zdarzenie window.onerror nie jest wywoływane w przypadku ostrzeżeń generowanych bezpośrednio przez klienta użytkownika. Uruchamia się w przypadku błędów środowiska wykonawczego (wyjątków JavaScript i błędów składni) spowodowanych przez wykonanie kodu.

ReportingObserver przejmuje obciążenie. Umożliwia on automatyczne otrzymywanie powiadomień o ostrzeżeniach generowanych przez przeglądarkę, takich jak wycofanie i interwencje. Możesz go używać jako narzędzia do raportowania i nie martwić się, czy użytkownicy napotykają nieoczekiwane problemy w Twojej witrynie.

Interfejs API

ReportingObserver nie różni się od innych interfejsów API Observer, takich jak IntersectionObserver i ResizeObserver. Przekazujesz mu wywołanie zwrotne, a on przekazuje Ci informacje. Informacje, które otrzymuje wywołanie zwrotne, to lista problemów, które spowodowała strona:

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    // → report.type === 'deprecation'
    // → report.url === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.id === 'XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload'
    // → report.body.message === 'Synchronous XMLHttpRequest is deprecated...'
    // → report.body.lineNumber === 11
    // → report.body.columnNumber === 22
    // → report.body.sourceFile === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.anticipatedRemoval === <JS_DATE_STR> or null
  }
});

observer.observe();

Raporty filtrowane

Raporty można wstępnie filtrować, aby wyświetlać tylko określone typy raportów. Obecnie dostępne są 2 typy raportów: 'deprecation' i 'intervention'.

const observer = new ReportingObserver((reports, observer) => {
  …
}, {types: ['deprecation']});

Raporty buforowane

Użyj opcji buffered: true, jeśli chcesz zobaczyć raporty wygenerowane przed utworzeniem instancji obserwatora:

const observer = new ReportingObserver((reports, observer) => {
  …
}, {types: ['intervention'], buffered: true});

Ta opcja świetnie sprawdza się w sytuacjach takich jak leniwe ładowanie biblioteki, która używa ReportingObserver. Obserwator jest dodawany późno, ale nie tracisz żadnych informacji o tym, co działo się wcześniej podczas wczytywania strony.

Przestań obserwować

Zatrzymaj obserwowanie za pomocą metody disconnect():

observer.disconnect();

Przykłady

Zgłaszanie interwencji przeglądarki dostawcy usług analitycznych

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    sendReportToAnalytics(JSON.stringify(report.body));
  }
}, {types: ['intervention'], buffered: true});

observer.observe();

Otrzymywanie powiadomień o planowanym usunięciu interfejsów API

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    if (report.type === 'deprecation') {
      sendToBackend(`Using a deprecated API in ${report.body.sourceFile} which will be
                     removed on ${report.body.anticipatedRemoval}. Info: ${report.body.message}`);
    }
  }
});

observer.observe();

Podsumowanie

ReportingObserver to dodatkowy sposób na wykrywanie i monitorowanie potencjalnych problemów w aplikacji internetowej. To przydatne narzędzie, które pozwala sprawdzić, czy baza kodu działa prawidłowo. Wysyłaj raporty do backendu, dowiaduj się o problemach w rzeczywistym świecie, aktualizuj kod i czerp korzyści.

Kolejne działania

Mam nadzieję, że w przyszłości ReportingObserver stanie się de facto interfejsem API do wykrywania wszystkich typów problemów w kodzie JavaScript. Wyobraź sobie jeden interfejs API, który wykrywa wszystkie błędy w aplikacji:

Dodatkowe materiały:

Baner powitalny: Sieuwert Otterloo, Unsplash.