Offlinefähige Seiten mit der Content Indexing API indexieren

Service Worker können Browsern mitteilen, welche Seiten offline funktionieren

Jeff Posnick

Was ist die Content Indexing API?

Wenn Sie eine progressive Webanwendung verwenden, haben Sie unabhängig vom aktuellen Status Ihrer Netzwerkverbindung Zugriff auf Informationen, die für Nutzer wichtig sind, z. B. Bilder, Videos und Artikel. Technologien wie Dienstworker, die Cache Storage API und IndexedDB bieten die Bausteine zum Speichern und Bereitstellen von Daten, wenn Nutzer direkt mit einer PWA interagieren. Doch die Entwicklung einer hochwertigen Offline-PWA ist nur ein Teil der Geschichte. Wenn Nutzer nicht wissen, dass der Inhalt einer Webanwendung auch offline verfügbar ist, können sie die Arbeit, die Sie in die Implementierung dieser Funktion investieren, nicht in vollem Umfang nutzen.

Das ist ein Problem der Auffindbarkeit: Wie können Nutzer in Ihrer PWA auf die offlinefähigen Inhalte aufmerksam gemacht werden, damit sie die verfügbaren Inhalte entdecken und ansehen können? Die Content Indexing API ist eine Lösung für dieses Problem. Der für Entwickler relevante Teil dieser Lösung ist eine Erweiterung von Service Workers, mit der Entwickler URLs und Metadaten von offlinefähigen Seiten einem lokalen Index hinzufügen können, der vom Browser verwaltet wird. Diese Verbesserung ist in Chrome 84 und höher verfügbar.

Sobald der Index mit Inhalten aus Ihrer PWA und allen anderen installierten PWAs gefüllt ist, werden sie wie unten dargestellt im Browser angezeigt.

Außerdem kann Chrome proaktiv Inhalte empfehlen, wenn erkannt wird, dass ein Nutzer offline ist.

Die Content Indexing API ist keine Alternative zum Caching von Inhalten. So können Sie Metadaten zu Seiten bereitstellen, die bereits von Ihrem Service Worker im Cache gespeichert sind, damit der Browser diese Seiten anzeigen kann, wenn Nutzer sie wahrscheinlich aufrufen möchten. Die Content Indexing API trägt zur Auffindbarkeit von im Cache gespeicherten Seiten bei.

Beispiele ansehen

Am besten lernen Sie die Content Indexing API kennen, indem Sie eine Beispielanwendung ausprobieren.

1. Achten Sie darauf, dass Sie einen unterstützten Browser und eine unterstützte Plattform verwenden. Derzeit ist die Funktion auf Chrome 84 oder höher auf Android-Geräten beschränkt. Unter about://version sehen Sie, welche Chrome-Version Sie verwenden.
2. Rufen Sie https://contentindex.dev auf.
3. Klicken Sie neben einem oder mehreren Elementen in der Liste auf die Schaltfläche +.
4. Optional: Deaktivieren Sie die WLAN- und Mobilfunkverbindung Ihres Geräts oder aktivieren Sie den Flugmodus, um zu simulieren, dass Ihr Browser offline ist.
5. Wählen Sie im Chrome-Menü Downloads aus und wechseln Sie zum Tab Artikel für mich.
6. Durchsuchen Sie die zuvor gespeicherten Inhalte.

Sie können sich den Quellcode der Beispielanwendung auf GitHub ansehen.

Eine weitere Beispielanwendung, eine Scrapbook-PWA, veranschaulicht die Verwendung der Content Indexing API mit der Web Share Target API. Der Code veranschaulicht eine Technik, mit der die Content Index API mit Elementen synchronisiert wird, die von einer Webanwendung über die Cache Storage API gespeichert werden.

API verwenden

Damit Sie die API verwenden können, muss Ihre App einen Dienst-Worker und URLs haben, die offline aufgerufen werden können. Wenn Ihre Webanwendung derzeit keinen Service Worker hat, können die Workbox-Bibliotheken das Erstellen eines solchen vereinfachen.

Welche Arten von URLs können als offline-fähig indexiert werden?

Die API unterstützt die Indexierung von URLs, die zu HTML-Dokumenten gehören. Eine URL für eine im Cache gespeicherte Mediendatei kann beispielsweise nicht direkt indexiert werden. Stattdessen müssen Sie eine URL für eine Seite angeben, auf der Medien angezeigt werden und die offline funktioniert.

Wir empfehlen, eine HTML-Seite für den „Betrachter“ zu erstellen, die die zugrunde liegende Medien-URL als Abfrageparameter akzeptieren und dann den Inhalt der Datei anzeigen kann, möglicherweise mit zusätzlichen Steuerelementen oder Inhalten auf der Seite.

Web-Apps können dem Inhaltsindex nur URLs hinzufügen, die sich im Umfang des aktuellen Service Workers befinden. Mit anderen Worten, eine Webanwendung könnte dem Inhaltsindex keine URL hinzufügen, die zu einer völlig anderen Domain gehört.

Übersicht

Die Content Indexing API unterstützt drei Vorgänge: das Hinzufügen, Auflisten und Entfernen von Metadaten. Diese Methoden werden über eine neue Property namens index bereitgestellt, die der Benutzeroberfläche von ServiceWorkerRegistration hinzugefügt wurde.

Der erste Schritt beim Indexieren von Inhalten besteht darin, einen Verweis auf die aktuelle ServiceWorkerRegistration abzurufen. Die Verwendung von navigator.serviceWorker.ready ist die einfachste Methode:

const registration = await navigator.serviceWorker.ready;

// Remember to feature-detect before using the API:
if ('index' in registration) {
  // Your Content Indexing API code goes here!
}

Wenn Sie die Content Indexing API nicht über eine Webseite, sondern über einen Service Worker aufrufen, können Sie sich direkt über registration auf ServiceWorkerRegistration beziehen. Sie ist bereits als Teil der ServiceWorkerGlobalScope. definiert.

Zum Index hinzufügen

Verwenden Sie die Methode add(), um URLs und die zugehörigen Metadaten zu indexieren. Sie entscheiden selbst, wann dem Index Elemente hinzugefügt werden. Sie können den Index als Reaktion auf eine Eingabe hinzufügen, z. B. wenn auf die Schaltfläche „Offline speichern“ geklickt wird. Sie können Artikel auch automatisch hinzufügen, wenn die im Cache gespeicherten Daten über einen Mechanismus wie die regelmäßige Hintergrundsynchronisierung aktualisiert werden.

await registration.index.add({
  // Required; set to something unique within your web app.
  id: 'article-123',

  // Required; url needs to be an offline-capable HTML page.
  url: '/articles/123',

  // Required; used in user-visible lists of content.
  title: 'Article title',

  // Required; used in user-visible lists of content.
  description: 'Amazing article about things!',

  // Required; used in user-visible lists of content.
  icons: [{
    src: '/img/article-123.png',
    sizes: '64x64',
    type: 'image/png',
  }],

  // Optional; valid categories are currently:
  // 'homepage', 'article', 'video', 'audio', or '' (default).
  category: 'article',
});

Das Hinzufügen eines Eintrags wirkt sich nur auf den Inhaltsindex aus. Der Cache wird nicht erweitert.

Grenzfall: add() aus dem window-Kontext aufrufen, wenn Ihre Symbole einen fetch-Handler verwenden

Wenn Sie add() aufrufen, fordert Chrome die URL jedes Symbols an, um sicherzustellen, dass eine Kopie des Symbols vorhanden ist, die beim Anzeigen einer Liste der indexierten Inhalte verwendet werden kann.

• Wenn Sie add() aus dem window-Kontext aufrufen (d. h. von Ihrer Webseite), löst diese Anfrage ein fetch-Ereignis in Ihrem Service Worker aus.

• Wenn Sie add() in Ihrem Service Worker aufrufen (z. B. in einem anderen Ereignis-Handler), wird durch die Anfrage nicht der fetch-Handler des Service Workers ausgelöst. Die Symbole werden direkt abgerufen, ohne dass ein Service Worker beteiligt ist. Berücksichtigen Sie dies, wenn Ihre Symbole auf Ihrem fetch-Handler basieren, möglicherweise weil sie nur im lokalen Cache und nicht im Netzwerk vorhanden sind. Achten Sie in diesem Fall darauf, add() nur im Kontext von window aufzurufen.

Indexinhalte auflisten

Die Methode getAll() gibt ein Versprechen für eine iterierbare Liste von indexierten Einträgen und deren Metadaten zurück. Die zurückgegebenen Einträge enthalten alle mit add() gespeicherten Daten.

const entries = await registration.index.getAll();
for (const entry of entries) {
  // entry.id, entry.launchUrl, etc. are all exposed.
}

Elemente aus dem Index entfernen

Wenn Sie ein Element aus dem Index entfernen möchten, rufen Sie delete() mit dem id des zu entfernenden Elements auf:

await registration.index.delete('article-123');

Der Aufruf von delete() wirkt sich nur auf den Index aus. Dabei wird nichts aus dem Cache gelöscht.

Nutzerlöschereignisse verarbeiten

Wenn die indexierten Inhalte im Browser angezeigt werden, kann er eine eigene Benutzeroberfläche mit dem Menüpunkt Löschen enthalten. So können Nutzer angeben, dass sie bereits indexierte Inhalte angesehen haben. So sieht die Benutzeroberfläche zum Löschen in Chrome 80 aus:

Wenn ein Nutzer diesen Menüpunkt auswählt, erhält der Service Worker Ihrer Webanwendung ein contentdelete-Ereignis. Die Verarbeitung dieses Ereignisses ist optional, bietet aber Ihrem Service Worker die Möglichkeit, Inhalte zu „bereinigen“, z. B. lokal im Cache gespeicherte Mediendateien, die ein Nutzer nicht mehr benötigt.

Sie müssen registration.index.delete() nicht in Ihrem contentdelete-Handler aufrufen. Wenn das Ereignis ausgelöst wurde, wurde die entsprechende Indexlöschung bereits vom Browser ausgeführt.

self.addEventListener('contentdelete', (event) => {
  // event.id will correspond to the id value used
  // when the indexed content was added.
  // Use that value to determine what content, if any,
  // to delete from wherever your app stores it—usually
  // the Cache Storage API or perhaps IndexedDB.
});

Feedback zum API-Design

Gibt es etwas an der API, das umständlich ist oder nicht wie erwartet funktioniert? Oder fehlen Ihnen Teile, die Sie für die Umsetzung Ihrer Idee benötigen?

Reichen Sie ein Problem im GitHub-Repository mit der Erklärung zur Content Indexing API ein oder fügen Sie Ihre Gedanken zu einem vorhandenen Problem hinzu.

Problem bei der Implementierung?

Haben Sie einen Fehler in der Chrome-Implementierung gefunden?

Reichen Sie einen Fehler unter https://new.crbug.com ein. Geben Sie so viele Details wie möglich an, eine einfache Anleitung zum Nachstellen und setzen Sie Components auf Blink>ContentIndexing.

Sie möchten die API verwenden?

Sie möchten die Content Indexing API in Ihrer Webanwendung verwenden? Ihre öffentliche Unterstützung hilft uns, die Priorität von Funktionen in Chrome festzulegen, und zeigt anderen Browseranbietern, wie wichtig es ist, diese zu unterstützen.

• Tweeten Sie an @ChromiumDev und verwenden Sie dabei den Hashtag #ContentIndexingAPI sowie Details dazu, wo und wie Sie die Funktion verwenden.

Welche Auswirkungen hat die Indexierung von Inhalten auf Sicherheit und Datenschutz?

Sehen Sie sich die Antworten an, die auf den Fragebogen zum Thema Sicherheit und Datenschutz des W3C geantwortet wurden. Wenn Sie weitere Fragen haben, starten Sie bitte eine Unterhaltung über das GitHub-Repository des Projekts.

Hero-Image von Maksym Kaharlytskyi auf Unsplash.