Offlinefähige Seiten mit der Content Indexing API indexieren

Service Workern ermöglichen, Browser darüber zu informieren, welche Seiten offline funktionieren

Jeff Posnick

Erfolg:Die Contentindexierungs-API ist Teil des Funktionsprojekts und wurde in Chrome 84 für Android eingeführt.

Was ist die Content Detection API?

Die Verwendung einer Progressive Web-App bedeutet, dass Sie unabhängig vom aktuellen Status Ihrer Netzwerkverbindung Zugriff auf Informationen haben, die für Ihre Nutzer wichtig sind, z. B. Bilder, Videos und Artikel. Technologien wie Service Worker, die Cache Storage API und IndexedDB bieten Ihnen die Bausteine zum Speichern und Bereitstellen von Daten, wenn Nutzer direkt mit einer PWA interagieren. Doch die Entwicklung einer qualitativ hochwertigen und offline orientierten PWA ist nur ein Teil des Ganzen. Wenn Nutzer nicht wissen, dass der Inhalt einer Webanwendung offline verfügbar ist, können sie die Arbeit, die Sie in die Implementierung dieser Funktion investieren, nicht in vollem Umfang nutzen.

Dies ist ein Erkennungsproblem. Wie kann Ihre PWA Nutzer auf ihre offline verfügbaren Inhalte aufmerksam machen, damit sie diese entdecken und ansehen können? Die Contentindexierungs-API ist eine Lösung für dieses Problem. Der für Entwickler vorgesehene Teil dieser Lösung ist eine Erweiterung für Service Worker, mit der Entwickler einem lokalen Index, der vom Browser verwaltet wird, URLs und Metadaten von offlinefähigen Seiten hinzufügen können. Diese Erweiterung ist ab Chrome 84 verfügbar.

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

Wähle zuerst auf der Seite „Neuer Tab“ in Chrome den Menüpunkt Downloads aus.

Medien und Artikel, die dem Index hinzugefügt wurden, werden im Bereich Artikel für mich angezeigt.

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

Die Content Detection API ist keine alternative Methode, Inhalte im Cache zu speichern. Es ist eine Möglichkeit, Metadaten zu Seiten bereitzustellen, die bereits von Ihrem Service Worker im Cache gespeichert sind, sodass der Browser diese Seiten dann anzeigen kann, wenn Nutzer sie wahrscheinlich ansehen möchten. Die Content Detection API erhöht die Auffindbarkeit von im Cache gespeicherten Seiten.

Hinweis:Die Content Detection API ist kein durchsuchbarer Index. Sie können zwar eine Liste aller indexierten Einträge abrufen, es ist aber nicht möglich, indexierte Metadaten direkt abzufragen.

Beispiele ansehen

Mit einer Beispielanwendung können Sie sich am besten mit der Content Detection API vertraut machen.

1. Achten Sie darauf, dass Sie einen unterstützten Browser und eine unterstützte Plattform verwenden. Derzeit ist dies auf Chrome 84 oder höher unter Android beschränkt. Rufe about://version auf, um zu sehen, welche Chrome-Version du verwendest.
2. Rufe https://contentindex.dev auf.
3. Klicken Sie neben einem oder mehreren der Einträge in der Liste auf die Schaltfläche +.
4. (Optional) Deaktivieren Sie die WLAN- und mobile Datenverbindung Ihres Geräts oder aktivieren Sie den Flugmodus, um zu simulieren, dass der Browser offline geht.
5. Wählen Sie im Chrome-Menü Downloads aus und wechseln Sie zum Tab Artikel für mich.
6. Blättern Sie durch die Inhalte, die Sie zuvor gespeichert haben.

Sie können die Quelle der Beispielanwendung auf GitHub ansehen.

In einer weiteren Beispielanwendung, einer Scrapbook-PWA, wird die Verwendung der Content Detection API mit der Web Share Target API veranschaulicht. Mit dem Code wird eine Technik veranschaulicht, mit der die Content Detection API mit Elementen synchronisiert bleibt, die von einer Web-App mithilfe der Cache Storage API gespeichert werden.

API verwenden

Damit Sie die API verwenden können, muss Ihre App einen Service Worker und offline zugängliche URLs haben. Wenn Ihre Webanwendung derzeit keinen Service Worker hat, können Sie das Erstellen eines Service Workers mit Workbox-Bibliotheken vereinfachen.

Welche Art von URLs kann als offline-fähig indexiert werden?

Die API unterstützt die Indexierung von URLs, die HTML-Dokumenten entsprechen. 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.

Es wird empfohlen, eine HTML-Seite vom Typ „Betrachter“ zu erstellen, die die zugrunde liegende Medien-URL als Suchparameter akzeptiert und dann den Inhalt der Datei – möglicherweise mit zusätzlichen Steuerelementen oder Inhalten auf der Seite – anzeigt.

Webanwendungen können dem Inhaltsindex nur URLs hinzufügen, die unter dem Bereich des aktuellen Service Workers liegen. Eine Webanwendung konnte dem Inhaltsindex also keine URL hinzufügen, die zu einer ganz anderen Domain gehört.

Überblick

Die Content Detection API unterstützt drei Vorgänge: Hinzufügen, Auflisten und Entfernen von Metadaten. Diese Methoden werden über das neue Attribut index bereitgestellt, das der Oberfläche ServiceWorkerRegistration hinzugefügt wurde.

Der erste Schritt beim Indexieren von Inhalten besteht darin, einen Verweis auf den aktuellen 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 du die Content Detection API von einem Service Worker statt innerhalb einer Webseite aufrufen möchtest, kannst du über registration direkt auf die ServiceWorkerRegistration verweisen. Sie ist als Teil des ServiceWorkerGlobalScope. bereits definiert.

Wird dem Index hinzugefügt

Verwenden Sie die Methode add(), um URLs und die zugehörigen Metadaten zu indexieren. Sie entscheiden, wann Elemente zum Index hinzugefügt werden. Sie können dem Index als Reaktion auf eine Eingabe hinzufügen, z. B. durch Klicken auf die Schaltfläche „Offline speichern“. Alternativ können Sie auch jedes Mal automatisch Elemente hinzufügen, wenn im Cache gespeicherte 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',
});

Ein Eintrag wirkt sich nur auf den Inhaltsindex aus und nichts zum Cache.

Grenzfall: Rufe add() aus dem window-Kontext auf, wenn deine Symbole auf einem fetch-Handler basieren

Wenn Sie add() aufrufen, fragt Chrome die URL jedes Symbols an, um sicherzustellen, dass eine Kopie des Symbols vorhanden ist, das bei der Anzeige einer Liste indexierter Inhalte verwendet werden kann.

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

• Wenn Sie add() in Ihrem Service Worker aufrufen (möglicherweise in einem anderen Event-Handler), löst die Anfrage nicht den fetch-Handler des Service Workers aus. Die Symbole werden ohne Eingriff von Service Workern direkt abgerufen. Beachten Sie, dass für die Symbole der fetch-Handler erforderlich ist, möglicherweise weil sie nur im lokalen Cache und nicht im Netzwerk vorhanden sind. Ist dies der Fall, musst du add() nur aus dem Kontext window aufrufen.

Indexinhalt 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');

Das Aufrufen von delete() wirkt sich nur auf den Index aus. Es wird nichts aus dem Cache gelöscht.

Warnung:Einträge laufen nach der Indexierung nicht automatisch ab. Sie müssen entweder eine Schnittstelle zum Löschen von Einträgen in Ihrer Webanwendung bereitstellen oder regelmäßig ältere Einträge entfernen, von denen Sie wissen, dass sie nicht mehr offline verfügbar sein sollen.

Umgang mit Nutzerlöschungsereignissen

Wenn der Browser den indexierten Inhalt anzeigt, enthält er möglicherweise eine eigene Benutzeroberfläche mit dem Menüpunkt Löschen. Nutzer können dann angeben, dass sie sich die indexierten Inhalte nicht mehr angesehen haben. So sieht die Löschoberfläche in Chrome 80 aus:

Wenn ein Nutzer diesen Menüpunkt auswählt, empfängt der Service Worker Ihrer Webanwendung ein contentdelete-Ereignis. Die Verarbeitung dieses Ereignisses ist zwar optional, bietet Ihrem Service Worker jedoch die Möglichkeit, Inhalte wie lokal im Cache gespeicherte Mediendateien zu bereinigen, die jemand angegeben hat, dass sie nicht mehr benötigt werden.

Sie müssen registration.index.delete() nicht in Ihrem contentdelete-Handler aufrufen. Wurde das Ereignis ausgelöst, wurde der relevante Index bereits vom Browser gelöscht.

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.
});

Hinweis:Das Ereignis contentdelete wird nur ausgelöst, wenn der Löschvorgang aufgrund einer Interaktion mit der integrierten Benutzeroberfläche des Browsers erfolgt. Sie wird nicht ausgelöst, wenn registration.index.delete() aufgerufen wird. Wenn Ihre Webanwendung das Löschen des Index mit dieser API-Methode auslöst, sollten gleichzeitig auch im Cache gespeicherte Inhalte bereinigt werden.

Feedback zum API-Design

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

Sie können ein Problem im erklärenden GitHub-Repository zur Content Reporting API melden oder Ihre Gedanken zu einem vorhandenen Problem hinzufügen.

Probleme bei der Implementierung?

Haben Sie einen Fehler bei der Implementierung in Chrome gefunden?

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

Möchten Sie die API verwenden?

Möchten Sie die Content Detection API in Ihrer Webanwendung verwenden? Ihre öffentliche Unterstützung hilft Chrome dabei, Funktionen zu priorisieren, und zeigt anderen Browseranbietern, wie wichtig es ist, sie zu unterstützen.

• Sende einen Tweet an @ChromiumDev und verwende das Hashtag #ContentIndexingAPI sowie Details dazu, wo und wie du es verwendest.

Welche Auswirkungen hat die Inhaltsindexierung auf Sicherheit und Datenschutz?

Sieh dir die Antworten im W3C-Fragebogen zu Sicherheit und Datenschutz an. Wenn Sie weitere Fragen haben, können Sie über das GitHub-Repository des Projekts eine Diskussion beginnen.

Hero-Image von Maksym Kaharlytskyi auf Unsplash