Indexer vos pages hors connexion avec l'API Content Indexing

Permettre aux services workers d'indiquer aux navigateurs quelles pages fonctionnent hors connexion

L'utilisation d'une application Web progressive permet d'accéder aux informations qui intéressent les utilisateurs (images, vidéos, articles, etc.), quel que soit l'état actuel de leur connexion réseau. Des technologies telles que les service workers, l'API Cache Storage et IndexedDB vous fournissent les éléments de base pour stocker et diffuser des données lorsque les utilisateurs interagissent directement avec une PWA. Mais créer une PWA de haute qualité, axée sur le hors connexion, n'est qu'une partie de l'histoire. Si les utilisateurs ne réalisent pas que le contenu d'une application Web est disponible lorsqu'ils sont hors connexion, ils ne profiteront pas pleinement du travail que vous avez effectué pour implémenter cette fonctionnalité.

Il s'agit d'un problème de découverte. Comment votre PWA peut-elle informer les utilisateurs de son contenu accessible hors connexion afin qu'ils puissent découvrir et consulter le contenu disponible ? L'API Content Indexing est une solution à ce problème. La partie destinée aux développeurs de cette solution est une extension des services workers, qui permet aux développeurs d'ajouter des URL et des métadonnées de pages compatibles avec le mode hors connexion à un index local géré par le navigateur. Cette amélioration est disponible dans Chrome 84 et versions ultérieures.

Une fois l'index renseigné avec le contenu de votre PWA, ainsi que celui de toutes les autres PWA installées, il sera affiché par le navigateur, comme indiqué ci-dessous.

Capture d'écran de l'élément de menu "Téléchargements" sur la page "Nouvel onglet" de Chrome.
Tout d'abord, sélectionnez l'élément de menu Téléchargements sur la page "Nouvel onglet" de Chrome.
Médias et articles ajoutés à l'index.
Les contenus multimédias et les articles ajoutés à l'index s'affichent dans la section Articles pour vous.

De plus, Chrome peut recommander de manière proactive du contenu lorsqu'il détecte qu'un utilisateur est hors connexion.

L'API Content Indexing n'est pas une autre méthode de mise en cache du contenu. Il s'agit d'un moyen de fournir des métadonnées sur les pages déjà mises en cache par votre worker de service afin que le navigateur puisse afficher ces pages lorsque les utilisateurs sont susceptibles de les consulter. L'API Content Indexing facilite la visibilité des pages mises en cache.

Démonstration

Le meilleur moyen de vous familiariser avec l'API Content Indexing est d'essayer un exemple d'application.

  1. Assurez-vous d'utiliser un navigateur et une plate-forme compatibles. Pour le moment, cette fonctionnalité est limitée à Chrome 84 ou version ultérieure sur Android. Accédez à about://version pour connaître la version de Chrome que vous utilisez.
  2. Accédez à https://contentindex.dev.
  3. Cliquez sur le bouton + à côté d'un ou de plusieurs éléments de la liste.
  4. (Facultatif) Désactivez le Wi-Fi et la connexion aux données mobiles de votre appareil, ou activez le mode Avion pour simuler la mise hors connexion de votre navigateur.
  5. Sélectionnez Téléchargements dans le menu de Chrome, puis accédez à l'onglet Articles pour vous.
  6. Parcourez les contenus que vous avez précédemment enregistrés.

Vous pouvez consulter le code source de l'exemple d'application sur GitHub.

Un autre exemple d'application, une PWA de scrapbook, illustre l'utilisation de l'API Content Indexing avec l'API Web Share Target. Le code illustre une technique permettant de synchroniser l'API Content Indexing avec les éléments stockés par une application Web à l'aide de l'API Cache Storage.

Utilisation de l'API

Pour utiliser l'API, votre application doit disposer d'un service worker et d'URL accessibles hors connexion. Si votre application Web ne dispose pas actuellement d'un service worker, les bibliothèques Workbox peuvent simplifier sa création.

Quels types d'URL peuvent être indexés comme compatibles avec le mode hors connexion ?

L'API permet d'indexer les URL correspondant à des documents HTML. Par exemple, une URL d'un fichier multimédia mis en cache ne peut pas être indexée directement. Vous devez plutôt fournir l'URL d'une page qui affiche des contenus multimédias et qui fonctionne hors connexion.

Nous vous recommandons de créer une page HTML de "lecteur" pouvant accepter l'URL multimédia sous-jacente en tant que paramètre de requête, puis d'afficher le contenu du fichier, éventuellement avec des commandes ou du contenu supplémentaires sur la page.

Les applications Web ne peuvent ajouter à l'index de contenu que des URL qui relèvent du champ d'application du service worker actuel. En d'autres termes, une application Web ne peut pas ajouter dans l'index de contenu une URL appartenant à un domaine complètement différent.

Présentation

L'API Content Indexing prend en charge trois opérations: l'ajout, la liste et la suppression de métadonnées. Ces méthodes sont exposées à partir d'une nouvelle propriété, index, qui a été ajoutée à l'interface ServiceWorkerRegistration.

La première étape de l'indexation du contenu consiste à obtenir une référence à l'ServiceWorkerRegistration actuelle. L'utilisation de navigator.serviceWorker.ready est le moyen le plus simple:

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

Si vous appelez l'API Content Indexing à partir d'un service worker plutôt que d'une page Web, vous pouvez vous référer directement à ServiceWorkerRegistration via registration. Il sera déjà défini dans ServiceWorkerGlobalScope..

Ajouter à l'index

Utilisez la méthode add() pour indexer les URL et les métadonnées associées. C'est à vous de choisir quand les éléments sont ajoutés à l'index. Vous pouvez ajouter à l'index en réponse à une entrée, par exemple en cliquant sur un bouton "Enregistrer hors connexion". Vous pouvez également ajouter des éléments automatiquement chaque fois que les données mises en cache sont mises à jour via un mécanisme tel que la synchronisation en arrière-plan périodique.

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',
});

L'ajout d'une entrée n'affecte que l'index de contenu ; cela n'ajoute rien au cache.

Cas particulier: Appelez add() à partir du contexte window si vos icônes reposent sur un gestionnaire fetch.

Lorsque vous appelez add(), Chrome envoie une requête pour l'URL de chaque icône afin de s'assurer qu'il dispose d'une copie de l'icône à utiliser lors de l'affichage d'une liste de contenus indexés.

  • Si vous appelez add() à partir du contexte window (en d'autres termes, à partir de votre page Web), cette requête déclenchera un événement fetch sur votre service worker.

  • Si vous appelez add() dans votre service worker (peut-être dans un autre gestionnaire d'événements), la requête ne déclenchera pas le gestionnaire fetch du service worker. Les icônes seront récupérées directement, sans intervention du service worker. Gardez cela à l'esprit si vos icônes reposent sur votre gestionnaire fetch, peut-être parce qu'elles n'existent que dans le cache local et non sur le réseau. Si c'est le cas, assurez-vous d'appeler uniquement add() à partir du contexte window.

Répertorier le contenu de l'index

La méthode getAll() renvoie une promesse pour une liste itérable d'entrées indexées et de leurs métadonnées. Les entrées renvoyées contiennent toutes les données enregistrées avec add().

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

Supprimer des éléments de l'index

Pour supprimer un élément de l'index, appelez delete() avec l'id de l'élément à supprimer:

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

L'appel de delete() ne concerne que l'indice. Elle ne supprime rien du cache.

Gérer un événement de suppression d'utilisateur

Lorsque le navigateur affiche le contenu indexé, il peut inclure sa propre interface utilisateur avec un élément de menu Supprimer, ce qui permet aux utilisateurs d'indiquer qu'ils ont terminé de consulter le contenu précédemment indexé. Voici à quoi ressemble l'interface de suppression dans Chrome 80:

Élément de menu "Supprimer".

Lorsqu'un utilisateur sélectionne cet élément de menu, le service worker de votre application Web reçoit un événement contentdelete. Bien que la gestion de cet événement soit facultative, elle permet à votre service worker de "nettoyer" le contenu, comme les fichiers multimédias mis en cache localement, dont quelqu'un a indiqué qu'il n'en avait plus besoin.

Vous n'avez pas besoin d'appeler registration.index.delete() dans votre gestionnaire contentdelete. Si l'événement a été déclenché, la suppression d'index appropriée a déjà été effectuée par le navigateur.

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

Commentaires sur la conception de l'API

L'API présente-t-elle des difficultés ou ne fonctionne-t-elle pas comme prévu ? Ou manque-t-il des éléments pour mettre en œuvre votre idée ?

Signalez un problème dans le dépôt GitHub de l'explication de l'API Content Indexing ou ajoutez vos commentaires à un problème existant.

Vous rencontrez un problème lors de l'implémentation ?

Avez-vous trouvé un bug dans l'implémentation de Chrome ?

Signalez un bug sur https://new.crbug.com. Incluez autant de détails que possible, des instructions simples pour reproduire le problème et définissez Components sur Blink>ContentIndexing.

Vous prévoyez d'utiliser l'API ?

Vous prévoyez d'utiliser l'API Content Indexing dans votre application Web ? Votre soutien public aide Chrome à hiérarchiser les fonctionnalités et montre aux autres fournisseurs de navigateurs à quel point il est essentiel de les prendre en charge.

Quelles sont les implications de l'indexation de contenu en termes de sécurité et de confidentialité ?

Consultez les réponses fournies en réponse au questionnaire sur la sécurité et la confidentialité du W3C. Si vous avez d'autres questions, veuillez lancer une discussion via le dépôt GitHub du projet.

Image principale par Maksym Kaharlytskyi sur Unsplash.