Permettre aux services workers d'indiquer aux navigateurs quelles pages fonctionnent hors connexion
Qu'est-ce que l'API Content Indexing ?
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 ses contenus disponibles hors connexion afin qu'ils puissent les découvrir et les afficher ? 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.
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 ne constitue 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 service worker, afin que le navigateur puisse les afficher 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.
- 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. - Accédez à https://contentindex.dev.
- Cliquez sur le bouton
+
à côté d'un ou de plusieurs éléments de la liste. - (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.
- Sélectionnez Téléchargements dans le menu de Chrome, puis accédez à l'onglet Articles pour vous.
- Parcourez les contenus que vous avez précédemment enregistrés.
Vous pouvez afficher la source de l'exemple d'application sur GitHub.
Un autre exemple d'application, une PWA 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 possède pas encore de service worker, les bibliothèques Workbox peuvent en simplifier la 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 pouvait pas ajouter une URL appartenant à un domaine complètement différent dans l'index de contenu.
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 depuis un service worker plutôt que depuis une page Web, vous pouvez faire référence à ServiceWorkerRegistration
directement 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. Il 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 contextewindow
(en d'autres termes, depuis votre page Web), cette requête déclenche un événementfetch
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 gestionnairefetch
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 gestionnairefetch
, 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 de n'appeleradd()
qu'à partir du contextewindow
.
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 le 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:
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 de l'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 dont vous avez besoin 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.
Problème d'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.
- Envoyez un tweet à @ChromiumDev en utilisant le hashtag
#ContentIndexingAPI
et en indiquant où et comment vous l'utilisez.
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 de sécurité et de 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.