Indicizzare le pagine compatibili con la modalità offline con l'API Content Indexing

Consente ai service worker di indicare ai browser quali pagine funzionano offline

Jeff Posnick

Risultato positivo: l'API Content Indexing, parte del progetto di funzionalità, è stata lanciata in Chrome 84 per Android.

Che cos'è l'API Content Indexing?

L'utilizzo di un'app web progressiva significa avere accesso alle informazioni che interessano alle persone, come immagini, video, articoli e altro ancora, indipendentemente dallo stato attuale della connessione di rete. Tecnologie come i service worker, l'API Cache Storage e IndexedDB ti forniscono gli elementi di base per archiviare e pubblicare i dati quando gli utenti interagiscono direttamente con una PWA. Tuttavia, creare una PWA di alta qualità incentrata sull'offline è solo una parte della storia. Se gli utenti non sanno che i contenuti di un'app web sono disponibili offline, non sfruttano appieno il lavoro che hai svolto per implementare questa funzionalità.

Si tratta di un problema di rivelazione: come può la tua PWA informare gli utenti dei suoi contenuti disponibili offline in modo che possano scoprire e visualizzare ciò che è disponibile? L'API Content Indexing è una soluzione a questo problema. La parte rivolta agli sviluppatori di questa soluzione è un'estensione dei service worker, che consente agli sviluppatori di aggiungere URL e metadati di pagine compatibili con la modalità offline a un indice locale gestito dal browser. Questo miglioramento è disponibile in Chrome 84 e versioni successive.

Una volta che l'indice è stato compilato con i contenuti della tua PWA e di tutte le altre PWA installate, verrà visualizzato dal browser come mostrato di seguito.

Innanzitutto, seleziona la voce di menu Download nella pagina Nuova scheda di Chrome.

I contenuti multimediali e gli articoli che sono stati aggiunti all'indice verranno visualizzati nella sezione Articoli per te.

Inoltre, Chrome può consigliare in modo proattivo i contenuti quando rileva che un utente è offline.

L'API Content Indexing non è un modo alternativo per memorizzare nella cache i contenuti. È un modo per fornire metadati sulle pagine già memorizzate nella cache dal tuo servizio worker, in modo che il browser possa mostrarle quando è probabile che gli utenti vogliano visualizzarle. L'API Content Indexing contribuisce alla visibilità delle pagine memorizzate nella cache.

Nota: l'API Content Indexing non è un indice in cui è possibile eseguire ricerche. Sebbene sia possibile ottenere un elenco di tutte le voci indicizzate, non è possibile eseguire query direttamente sui metadati indicizzati.

Guarda come funziona

Il modo migliore per farsi un'idea dell'API Content Indexing è provare un'applicazione di esempio.

1. Assicurati di utilizzare un browser e una piattaforma supportati. Al momento, questa funzionalità è limitata a Chrome 84 o versioni successive su Android. Visita il sito about://version per verificare la tua versione di Chrome.
2. Visita la pagina https://contentindex.dev
3. Fai clic sul pulsante + accanto a uno o più elementi dell'elenco.
4. (Facoltativo) Disattiva la connessione Wi-Fi e la rete dati del dispositivo oppure attiva la modalità aereo per simulare il passaggio del browser alla modalità offline.
5. Scegli Download dal menu di Chrome e passa alla scheda Articoli per te.
6. Sfoglia i contenuti salvati in precedenza.

Puoi visualizzare il codice sorgente dell'applicazione di esempio su GitHub.

Un'altra applicazione di esempio, una PWA Scrapbook, illustra l'utilizzo dell'API Content Index con l'API Web Share Target. Il codice dimostra una tecnica per mantenere sincronizzata l'API Content Index con gli elementi archiviati da un'app web utilizzando l'API Cache Storage.

Utilizzo dell'API

Per utilizzare l'API, la tua app deve avere un servizio worker e URL navigabili offline. Se la tua app web non ha attualmente un servizio worker, le librerie Workbox possono semplificarne la creazione.

Quali tipi di URL possono essere indicizzati come compatibili con l'utilizzo offline?

L'API supporta l'indicizzazione degli URL corrispondenti ai documenti HTML. Ad esempio, l'URL di un file multimediale memorizzato nella cache non può essere indicizzato direttamente. Devi fornire un URL per una pagina che mostri contenuti multimediali e che funzioni offline.

Un pattern consigliato è creare una pagina HTML "visualizzatore" che possa accettare l'URL multimediale sottostante come parametro di query e poi visualizzare i contenuti del file, potenzialmente con controlli o contenuti aggiuntivi nella pagina.

Le app web possono aggiungere all'indice dei contenuti solo gli URL che rientrano nell'ambito del service worker corrente. In altre parole, un'app web non potrebbe aggiungere nell'indice dei contenuti un URL appartenente a un dominio completamente diverso.

Panoramica

L'API Content Indexing supporta tre operazioni: aggiunta, elencazione e rimozione di metadati. Questi metodi sono esposti da una nuova proprietà, index, che è stata aggiunta all'interfaccia ServiceWorkerRegistration.

Il primo passaggio per indicizzare i contenuti consiste nell'ottenere un riferimento all'ServiceWorkerRegistration corrente. L'utilizzo di navigator.serviceWorker.ready è il modo più semplice:

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

Se effettui chiamate all'API Content Indexing da un servizio worker, piuttosto che all'interno di una pagina web, puoi fare riferimento a ServiceWorkerRegistration direttamente tramite registration. È già definito come parte del ServiceWorkerGlobalScope.

Aggiunta all'indice

Utilizza il metodo add() per indicizzare gli URL e i relativi metadati associati. Sta a te scegliere quando aggiungere gli elementi all'indice. Potresti voler aggiungere elementi all'indice in risposta a un input, ad esempio facendo clic su un pulsante "Salva offline". In alternativa, puoi aggiungere elementi automaticamente ogni volta che i dati memorizzati nella cache vengono aggiornati tramite un meccanismo come la sincronizzazione in background periodica.

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'aggiunta di una voce interessa solo l'indice dei contenuti e non aggiunge nulla alla cache.

Caso limite: chiama add() dal contesto window se le icone si basano su un gestore fetch

Quando chiami add(), Chrome effettua una richiesta per l'URL di ogni icona per garantire che abbia una copia dell'icona da utilizzare durante la visualizzazione di un elenco di contenuti indicizzati.

• Se chiami add() dal contesto window (in altre parole, dalla pagina web), questa richiesta attiverà un evento fetch nel tuo service worker.

• Se chiami add() all'interno del tuo service worker (ad esempio all'interno di un altro gestore di eventi), la richiesta non attiverà il gestore fetch del service worker. Le icone verranno recuperate direttamente, senza l'intervento del service worker. Tieni presente questo aspetto se le tue icone si basano sul gestore fetch, probabilmente perché esistono solo nella cache locale e non nella rete. In questo caso, assicurati di chiamare add() solo dal contesto window.

Elenco dei contenuti dell'indice

Il metodo getAll() restituisce una promessa per un elenco iterabile di voci indicizzate e dei relativi metadati. Le voci restituite conterranno tutti i dati salvati con add().

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

Rimozione di elementi dall'indice

Per rimuovere un elemento dall'indice, chiama delete() con il id dell'elemento da rimuovere:

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

La chiamata a delete() influisce solo sull'indice. Non viene eliminato nulla dalla cache.

Avviso:una volta indicizzate, le voci non scadono automaticamente. Sta a te decidere se mostrare un'interfaccia nella tua app web per eliminare le voci o rimuovere periodicamente le voci precedenti che sai non essere più disponibili offline.

Gestione di un evento di eliminazione utente

Quando il browser mostra i contenuti indicizzati, potrebbe includere la propria interfaccia utente con un elemento di menu Elimina, che consente agli utenti di indicare che hanno terminato di visualizzare i contenuti indicizzati in precedenza. Questo è l'aspetto dell'interfaccia di eliminazione in Chrome 80:

Quando qualcuno seleziona quella voce di menu, il service worker della tua app web riceverà un evento contentdelete. Sebbene la gestione di questo evento sia facoltativa, offre al tuo service worker la possibilità di "ripulire" i contenuti, ad esempio i file multimediali memorizzati nella cache locale, di cui qualcuno ha indicato di non aver più bisogno.

Non è necessario chiamare registration.index.delete() all'interno del gestore contentdelete; se l'evento è stato attivato, l'eliminazione dell'indice pertinente è già stata eseguita dal browser.

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

Nota: l'evento contentdelete viene attivato solo quando l'eliminazione si verifica a causa dell'interazione con l'interfaccia utente integrata del browser. Non viene attivata quando viene chiamato registration.index.delete(). Se la tua app web attiva l'eliminazione dell'indice utilizzando questo metodo dell'API, deve anche ripulire i contenuti memorizzati nella cache contemporaneamente.

Feedback sul design dell'API

L'API presenta problemi o non funziona come previsto? Oppure mancano elementi per implementare la tua idea?

Invia una segnalazione nel repository GitHub dell'articolo esplicativo sull'API Content Indexing o aggiungi il tuo parere a un problema esistente.

Problemi con l'implementazione?

Hai trovato un bug nell'implementazione di Chrome?

Invia un bug all'indirizzo https://new.crbug.com. Includi il maggior numero possibile di dettagli, istruzioni semplici per la riproduzione e imposta Componenti su Blink>ContentIndexing.

Hai intenzione di utilizzare l'API?

Hai intenzione di utilizzare l'API Content Indexing nella tua app web? Il tuo supporto pubblico aiuta Chrome a dare la priorità alle funzionalità e mostra ad altri fornitori di browser quanto sia importante supportarle.

• Invia un tweet all'indirizzo @ChromiumDev utilizzando l'hashtag #ContentIndexingAPI e i dettagli su dove e come lo utilizzi.

Quali sono alcune implicazioni per la sicurezza e la privacy dell'indicizzazione dei contenuti?

Consulta le risposte fornite in risposta al questionario sulla sicurezza e sulla privacy del W3C. Se hai altre domande, avvia una discussione tramite il repo GitHub del progetto.

Immagine hero di Maksym Kaharlytskyi su Unsplash.