Indexeer uw offline pagina's met de Content Indexing API

Serviceworkers kunnen browsers laten weten welke pagina's offline werken.

Jeff Posnick

Succes: De Content Indexing API, onderdeel van het capabilities-project , is gelanceerd in Chrome 84 voor Android.

Wat is de Content Indexing API?

Met een progressieve webapp (PWA) heb je toegang tot informatie die mensen belangrijk vinden – afbeeldingen, video's, artikelen en meer – ongeacht de status van je netwerkverbinding. Technologieën zoals service workers , de Cache Storage API en IndexedDB bieden de bouwstenen voor het opslaan en leveren van data wanneer gebruikers rechtstreeks met een PWA interageren. Maar het bouwen van een hoogwaardige, offline-first PWA is slechts een deel van het verhaal. Als gebruikers zich niet realiseren dat de content van een webapp ook offline beschikbaar is, zullen ze niet optimaal profiteren van de functionaliteit die je hebt geïmplementeerd.

Dit is een probleem met de vindbaarheid ; hoe kan uw PWA gebruikers bewust maken van de offline-compatibele content, zodat ze kunnen ontdekken en bekijken wat er beschikbaar is? De Content Indexing API biedt hiervoor een oplossing. Het ontwikkelaarsgedeelte van deze oplossing is een uitbreiding op service workers, waarmee ontwikkelaars URL's en metadata van offline-compatibele pagina's kunnen toevoegen aan een lokale index die door de browser wordt beheerd. Deze verbetering is beschikbaar in Chrome 84 en later.

Zodra de index gevuld is met content van uw PWA, en alle andere geïnstalleerde PWA's, wordt deze als volgt door de browser weergegeven.

Selecteer eerst het menu-item Downloads op de pagina voor nieuwe tabbladen van Chrome.

Media en artikelen die aan de index zijn toegevoegd, worden weergegeven in de sectie 'Artikelen voor jou' .

Daarnaast kan Chrome proactief content aanbevelen wanneer het detecteert dat een gebruiker offline is.

De Content Indexing API is geen alternatieve manier om content in de cache op te slaan . Het is een manier om metadata te verstrekken over pagina's die al in de cache van uw service worker zijn opgeslagen, zodat de browser die pagina's kan tonen wanneer gebruikers ze waarschijnlijk willen bekijken. De Content Indexing API helpt bij het vinden van pagina's in de cache.

Let op: de Content Indexing API is geen doorzoekbare index. Hoewel u een lijst van alle geïndexeerde items kunt opvragen, is het niet mogelijk om rechtstreeks te zoeken op basis van geïndexeerde metadata.

Bekijk het in actie.

De beste manier om de Content Indexing API te leren kennen, is door een voorbeeldapplicatie uit te proberen.

1. Zorg ervoor dat je een ondersteunde browser en platform gebruikt. Op Android is dit beperkt tot Chrome 84 of later . Ga naar about://version om te zien welke versie van Chrome je gebruikt.
2. Bezoek https://contentindex.dev
3. Klik op de + knop naast een of meer items in de lijst.
4. (Optioneel) Schakel de wifi- en mobiele dataverbinding van uw apparaat uit, of activeer de vliegtuigmodus om te simuleren dat uw browser offline is.
5. Kies Downloads in het Chrome-menu en ga naar het tabblad Artikelen voor jou .
6. Blader door de inhoud die je eerder hebt opgeslagen.

Je kunt de broncode van de voorbeeldapplicatie bekijken op GitHub .

Een andere voorbeeldapplicatie, een Scrapbook PWA , illustreert het gebruik van de Content Indexing API met de Web Share Target API . De code demonstreert een techniek om de Content Indexing API gesynchroniseerd te houden met items die door een webapplicatie worden opgeslagen met behulp van de Cache Storage API .

De API gebruiken

Om de API te gebruiken, moet uw app een service worker hebben en URL's die offline toegankelijk zijn. Als uw webapp geen service worker heeft, kunnen de Workbox-bibliotheken het aanmaken ervan vereenvoudigen.

Welke soorten URL's kunnen als offline-compatibel worden geïndexeerd?

De API ondersteunt het indexeren van URL's die overeenkomen met HTML-documenten. Een URL voor een gecacheerd mediabestand kan bijvoorbeeld niet direct worden geïndexeerd. In plaats daarvan moet u een URL opgeven voor een pagina die media weergeeft en die offline werkt.

Een aanbevolen werkwijze is het maken van een HTML-pagina die als "viewer" fungeert. Deze pagina accepteert de URL van het onderliggende mediabestand als queryparameter en toont vervolgens de inhoud van het bestand, eventueel met extra elementen of content op de pagina.

Webapplicaties kunnen alleen URL's aan de contentindex toevoegen die binnen het bereik van de huidige service worker vallen. Met andere woorden, een webapplicatie kan geen URL van een volledig ander domein aan de contentindex toevoegen.

Overzicht

De Content Indexing API ondersteunt drie bewerkingen: het toevoegen, weergeven en verwijderen van metadata. Deze methoden zijn beschikbaar via een nieuwe eigenschap, index , die is toegevoegd aan de ServiceWorkerRegistration interface.

De eerste stap bij het indexeren van content is het verkrijgen van een verwijzing naar de huidige ServiceWorkerRegistration . Het gebruik van navigator.serviceWorker.ready is de meest eenvoudige manier:

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!
}

Als u vanuit een service worker, in plaats van vanuit een webpagina, aanroepen doet naar de Content Indexing API, kunt u rechtstreeks naar de ServiceWorkerRegistration verwijzen met behulp van registration . Deze is dan al gedefinieerd als onderdeel van de ServiceWorkerGlobalScope.

Toevoegen aan de index

Gebruik de add() -methode om URL's en de bijbehorende metadata te indexeren. Je kunt zelf bepalen wanneer items aan de index worden toegevoegd. Je kunt items bijvoorbeeld toevoegen naar aanleiding van een invoer, zoals het klikken op een knop 'offline opslaan'. Of je kunt items automatisch toevoegen telkens wanneer de gecachede gegevens worden bijgewerkt met behulp van een mechanisme zoals periodieke achtergrondsynchronisatie .

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:
  // 'homepage', 'article', 'video', 'audio', or '' (default).
  category: 'article',
});

Het toevoegen van een item heeft alleen invloed op de inhoudsindex; het voegt niets toe aan de cache .

Uitzonderlijk geval: Roep add() aan vanuit window venstercontext als uw pictogrammen afhankelijk zijn van een fetch handler.

Wanneer je de functie add() aanroept, zal Chrome voor elk pictogram een ​​verzoek indienen om de URL op te vragen. Zo zorgt Chrome ervoor dat er een kopie van het pictogram beschikbaar is om te gebruiken bij het weergeven van een lijst met geïndexeerde inhoud.

• Als je add() methode aanroept vanuit de window context (oftewel vanuit je webpagina), zal dit verzoek een fetch gebeurtenis op je service worker activeren.

• Als je add() aanroept binnen je service worker (bijvoorbeeld binnen een andere event handler), zal het verzoek de fetch handler van de service worker niet activeren. De pictogrammen worden direct opgehaald, zonder tussenkomst van de service worker. Houd hier rekening mee als je pictogrammen afhankelijk zijn van je fetch handler, bijvoorbeeld omdat ze alleen in de lokale cache aanwezig zijn en niet op het netwerk. Zorg er in dat geval voor dat je add() alleen vanuit de window context aanroept.

Een overzicht van de inhoud van de index

De getAll() methode retourneert een promise voor een iterable lijst met geïndexeerde items en hun metadata. De geretourneerde items bevatten alle gegevens die zijn opgeslagen met add() .

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

Items uit de index verwijderen

Om een ​​item uit de index te verwijderen, roep je delete() aan met de id van het item dat je wilt verwijderen:

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

Het aanroepen van delete() heeft alleen invloed op de index. Het verwijdert niets uit de cache .

Waarschuwing: Eenmaal geïndexeerde gegevens verlopen niet automatisch. Het is aan u om ofwel een interface in uw webapplicatie te bieden voor het verwijderen van gegevens, ofwel periodiek oudere gegevens te verwijderen waarvan u weet dat ze offline niet langer beschikbaar zouden moeten zijn.

Het afhandelen van een verwijderingsgebeurtenis van een gebruiker

Wanneer de browser de geïndexeerde inhoud weergeeft, kan deze een eigen gebruikersinterface met een menuoptie 'Verwijderen ' tonen, waarmee gebruikers kunnen aangeven dat ze klaar zijn met het bekijken van eerder geïndexeerde inhoud. Zo ziet de verwijderingsinterface eruit in Chrome 80:

Wanneer iemand dat menu-item selecteert, ontvangt de service worker van uw webapplicatie een contentdelete gebeurtenis. Hoewel het afhandelen van deze gebeurtenis optioneel is, biedt het uw service worker de mogelijkheid om inhoud, zoals lokaal opgeslagen mediabestanden, te "opschonen" waarvan de gebruiker heeft aangegeven dat hij of zij er klaar mee is.

Je hoeft registration.index.delete() niet aan te roepen in je contentdelete handler; als de gebeurtenis al is geactiveerd, is de relevante indexverwijdering al door de browser uitgevoerd.

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

Let op: de contentdelete gebeurtenis wordt alleen geactiveerd wanneer de verwijdering plaatsvindt als gevolg van interactie met de ingebouwde gebruikersinterface van de browser. Deze wordt niet geactiveerd wanneer registration.index.delete() wordt aangeroepen. Als uw webapplicatie de verwijdering van de index activeert met behulp van deze API-methode, moet deze tegelijkertijd ook de in de cache opgeslagen inhoud opschonen .

Feedback over het API-ontwerp

Is er iets aan de API dat onhandig is of niet werkt zoals verwacht? Of ontbreken er onderdelen die je nodig hebt om je idee te implementeren?

Dien een probleemmelding in op de GitHub-repository van de Content Indexing API explainer , of voeg uw opmerkingen toe aan een bestaande probleemmelding.

Probleem met de implementatie?

Heb je een bug gevonden in de implementatie van Chrome?

Meld een bug op https://new.crbug.com . Vermeld zoveel mogelijk details, instructies voor het reproduceren van het probleem en stel Components in op Blink>ContentIndexing .

Ben je van plan de API te gebruiken?

Ben je van plan de Content Indexing API in je webapplicatie te gebruiken? Jouw publieke steun helpt Chrome bij het prioriteren van functies en laat andere browserleveranciers zien hoe belangrijk het is om deze te ondersteunen.

• Stuur een tweet naar @ChromiumDev met de hashtag #ContentIndexingAPI en details over waar en hoe je het gebruikt.

Wat zijn de gevolgen van contentindexering voor de beveiliging en privacy?

Bekijk de antwoorden op de vragenlijst van het W3C over beveiliging en privacy . Als je nog vragen hebt, start dan een discussie in de GitHub-repository van het project.