Indexeer uw offline pagina's met de Content Indexing API

Servicemedewerkers in staat stellen browsers te vertellen welke pagina's offline werken

Jeff Posnick

Succes: de Content Indexing API, onderdeel van het mogelijkhedenproject , gelanceerd in Chrome 84 voor Android.

Wat is de Content Indexing-API?

Het gebruik van een progressieve webapp betekent dat u toegang heeft tot informatie waar mensen om geven (afbeeldingen, video's, artikelen en meer), ongeacht de huidige status van uw netwerkverbinding. Technologieën zoals servicemedewerkers , de Cache Storage API en IndexedDB bieden u de bouwstenen voor het opslaan en aanbieden van gegevens wanneer mensen rechtstreeks met een PWA communiceren. Maar het bouwen van een hoogwaardige, offline-first PWA is slechts een deel van het verhaal. Als mensen zich niet realiseren dat de inhoud van een webapp beschikbaar is terwijl ze offline zijn, zullen ze niet optimaal profiteren van het werk dat u in de implementatie van die functionaliteit steekt.

Dit is een ontdekkingsprobleem ; Hoe kan uw PWA gebruikers bewust maken van de offline-inhoud, zodat ze kunnen ontdekken en bekijken wat er beschikbaar is? De Content Indexing API is een oplossing voor dit probleem. Het ontwikkelaarsgedeelte van deze oplossing is een uitbreiding voor servicemedewerkers, waarmee ontwikkelaars URL's en metagegevens van offline-compatibele pagina's kunnen toevoegen aan een lokale index die door de browser wordt bijgehouden. Die verbetering is beschikbaar in Chrome 84 en hoger.

Zodra de index is gevuld met inhoud van uw PWA en eventuele andere geïnstalleerde PWA's, wordt deze door de browser weergegeven, zoals hieronder weergegeven.

Selecteer eerst het menu-item Downloads op de nieuwe tabbladpagina van Chrome.

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

Bovendien kan Chrome proactief inhoud aanbevelen wanneer het detecteert dat een gebruiker offline is.

De Content Indexing API is geen alternatieve manier om inhoud in de cache op te slaan . Het is een manier om metagegevens te verstrekken over pagina's die al door uw servicemedewerker in de cache zijn opgeslagen, zodat de browser die pagina's kan weergeven wanneer mensen deze waarschijnlijk willen bekijken. De Content Indexing API helpt bij de vindbaarheid van in de cache opgeslagen pagina's.

Opmerking: de Content Indexing API is geen doorzoekbare index. Hoewel u een lijst met alle geïndexeerde vermeldingen kunt krijgen, is het niet mogelijk om rechtstreeks naar geïndexeerde metagegevens te zoeken.

Zie het in actie

De beste manier om een ​​indruk te krijgen van de Content Indexing API is door een voorbeeldtoepassing uit te proberen.

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

U kunt de bron van de voorbeeldtoepassing bekijken op GitHub .

Een andere voorbeeldtoepassing, 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 zijn opgeslagen door een webapp met behulp van de Cache Storage API .

Met behulp van de API

Als u de API wilt gebruiken, moet uw app een servicemedewerker hebben en URL's die offline navigeerbaar zijn. Als uw webapp momenteel geen servicemedewerker heeft, kunnen de Workbox-bibliotheken het maken ervan vereenvoudigen.

Welk type URL's kunnen offline worden geïndexeerd?

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

Een aanbevolen patroon is het maken van een 'viewer'-HTML-pagina die de onderliggende media-URL als queryparameter accepteert en vervolgens de inhoud van het bestand weergeeft, mogelijk met extra besturingselementen of inhoud op de pagina.

Web-apps kunnen alleen URL's toevoegen aan de inhoudsindex die binnen het bereik van de huidige servicemedewerker vallen. Met andere woorden: een webapp kan geen URL die tot een heel ander domein behoort, aan de inhoudsindex toevoegen.

Overzicht

De Content Indexing API ondersteunt drie bewerkingen: metagegevens toevoegen, weergeven en verwijderen. Deze methoden worden weergegeven via een nieuwe eigenschap, index , die is toegevoegd aan de ServiceWorkerRegistration interface.

De eerste stap bij het indexeren van inhoud 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 de Content Indexing API aanroept vanuit een servicemedewerker, in plaats van vanuit een webpagina, kunt u rechtstreeks naar de ServiceWorkerRegistration verwijzen via registration . Het zal al worden gedefinieerd als onderdeel van ServiceWorkerGlobalScope.

Toevoegen aan de index

Gebruik de add() methode om URL's en de bijbehorende metagegevens te indexeren. Het is aan jou om te kiezen wanneer items aan de index worden toegevoegd. Mogelijk wilt u iets toevoegen aan de index als reactie op een invoer, bijvoorbeeld door op de knop 'offline opslaan' te klikken. Of u kunt automatisch items toevoegen telkens wanneer gegevens in de cache worden bijgewerkt via 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 currently:
  // '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 .

Edge case: Roep add() aan vanuit window als uw pictogrammen afhankelijk zijn van een fetch

Wanneer u add() aanroept, doet Chrome een verzoek om de URL van elk pictogram om ervoor te zorgen dat er een kopie van het pictogram is die kan worden gebruikt bij het weergeven van een lijst met geïndexeerde inhoud.

• Als u add() aanroept vanuit de window (met andere woorden, vanaf uw webpagina), zal dit verzoek een fetch -gebeurtenis activeren voor uw servicemedewerker.

• Als u add() aanroept binnen uw servicemedewerker (misschien binnen een andere gebeurtenishandler), zal het verzoek de fetch van de servicemedewerker niet activeren. De pictogrammen worden direct opgehaald, zonder tussenkomst van een servicemedewerker. Houd hier rekening mee als uw pictogrammen afhankelijk zijn van uw fetch , misschien omdat ze alleen in de lokale cache voorkomen en niet op het netwerk. Als dit het geval is, zorg er dan voor dat u add() alleen vanuit de window aanroept.

Lijst met de inhoud van de index

De methode getAll() retourneert een belofte voor een iterabele lijst met geïndexeerde items en hun metagegevens. Geretourneerde gegevens 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, roept u delete() aan met de id van het item dat u wilt verwijderen:

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

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

Waarschuwing: Eenmaal geïndexeerd vervallen de vermeldingen niet automatisch. Het is aan u om een ​​interface in uw webapp te presenteren voor het wissen van vermeldingen, of om periodiek oudere vermeldingen te verwijderen waarvan u weet dat ze niet langer offline beschikbaar zouden moeten zijn.

Een gebruikersverwijderingsgebeurtenis afhandelen

Wanneer de browser de geïndexeerde inhoud weergeeft, kan deze een eigen gebruikersinterface bevatten met een menu-item Verwijderen , waardoor mensen de kans krijgen om aan te geven 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 servicemedewerker van uw webapp een contentdelete gebeurtenis. Hoewel het afhandelen van deze gebeurtenis optioneel is, biedt het uw servicemedewerker de kans om inhoud, zoals lokaal in de cache opgeslagen mediabestanden, op te ruimen waarvan iemand heeft aangegeven dat hij er klaar mee is.

U hoeft registration.index.delete() niet aan te roepen in uw contentdelete handler; als de gebeurtenis 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.
});

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

Feedback over het API-ontwerp

Is er iets aan de API dat lastig is of niet werkt zoals verwacht? Of ontbreken er stukjes die je nodig hebt om je idee te verwezenlijken?

Dien een probleem in op de Content Indexing API-uitleg GitHub repo , of voeg uw mening toe aan een bestaand probleem.

Probleem met de implementatie?

Heeft u een bug gevonden in de implementatie van Chrome?

Dien een bug in op https://new.crbug.com . Voeg zoveel mogelijk details toe, eenvoudige instructies voor het reproduceren, en stel Components in op Blink>ContentIndexing .

Bent u van plan de API te gebruiken?

Bent u van plan de Content Indexing API in uw web-app te gebruiken? Uw publieke steun helpt Chrome prioriteit te geven aan 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 u deze gebruikt.

Wat zijn enkele implicaties voor de veiligheid en privacy van het indexeren van inhoud?

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

Heldenafbeelding door Maksym Kaharlytskyi op Unsplash .