Como indexar suas páginas compatíveis com o modo off-line com a API Content Indexing

Como ativar service workers para informar aos navegadores quais páginas funcionam off-line

Jeff Posnick

O que é a API de indexação de conteúdo?

Usar um Progressive Web App significa ter acesso a informações importantes para as pessoas, como imagens, vídeos, artigos e muito mais, independentemente do estado atual da conexão de rede. Tecnologias como service workers, a API Cache Storage, e IndexedDB e fornece as bases para armazenar e disponibilizar dados quando as pessoas interagem diretamente com um PWA. Mas criar um PWA de alta qualidade que prioriza off-line é apenas parte da história. Se as pessoas não perceberem que o conteúdo de um aplicativo da web está disponíveis enquanto estiverem off-line, não vão aproveitar ao máximo o trabalho que você na implementação dessa funcionalidade.

Esse é um problema de descoberta. como seu PWA pode informar os usuários conteúdo compatível com o modo off-line para que eles possam descobrir e visualizar o que está disponível? A A API de indexação de conteúdo é uma solução para esse problema. A parte voltada para o desenvolvedor dessa solução é uma extensão dos service workers, o que permite que os desenvolvedores adicionar URLs e metadados de páginas compatíveis com o modo off-line a um índice local mantido pelo no navegador. Essa melhoria está disponível no Chrome 84 e em versões mais recentes.

Depois que o índice for preenchido com o conteúdo do seu PWA, bem como qualquer outro PWAs instalados, ele será exibido pelo navegador, conforme mostrado abaixo.

Uma captura de tela do item de menu "Downloads" na página "Nova guia" do Chrome.
Primeiro, selecione o item de menu Downloads na página "Nova guia" do Chrome.
.
Mídia e artigos que foram adicionados ao índice.
A mídia e os artigos que foram adicionados ao índice serão exibidos no Artigos para você.

Além disso, o Chrome pode recomendar conteúdo de forma proativa quando detecta que um usuário está off-line.

A API Content Index não é uma maneira alternativa de armazenar conteúdo em cache. Está uma maneira de fornecer metadados sobre páginas que já estão armazenadas em cache pelo seu serviço para que o navegador possa exibir essas páginas quando houver probabilidade de quiser visualizá-las. A API Content Indexing ajuda na possibilidade de descoberta de das páginas armazenadas em cache.

Confira na prática

A melhor maneira de ter uma noção sobre a API de indexação de conteúdo é testar uma amostra para o aplicativo.

  1. Verifique se você está usando um navegador e uma plataforma compatíveis. Atualmente, limitado ao Chrome 84 ou posterior no Android. Acesse about://version para conferir qual versão do Chrome você está usando.
  2. Acesse https://contentindex.dev
  3. Clique no botão + ao lado de um ou mais itens na lista.
  4. (Opcional) Desative o Wi-Fi e a conexão de dados móveis do dispositivo ou ative modo avião para simular a desativação do navegador.
  5. Escolha Downloads no menu do Chrome e alterne para a guia Artigos para você.
  6. Navegue pelo conteúdo que você salvou anteriormente.

Veja o código-fonte do aplicativo de exemplo no GitHub (link em inglês).

Outro aplicativo de exemplo, o PWA do mural, ilustra o uso da API de indexação de conteúdo com a API de destino de compartilhamento da Web. O código demonstra uma técnica para manter a API de indexação de conteúdo sincronizada com os itens armazenados por um app da Web. usando a API Cache Storage.

Como usar a API

Para usar a API, seu app precisa ter um service worker e URLs navegáveis off-line. Se seu app da Web não tiver um service worker no momento, as bibliotecas do Workbox poderão simplificar criar um.

Que tipo de URL pode ser indexado como compatível off-line?

A API oferece suporte à indexação de URLs correspondentes a documentos HTML. Um URL de um arquivo arquivo de mídia, por exemplo, não pode ser indexado diretamente. Em vez disso, você precisa fornecer o URL de uma página que exibe mídia e funciona off-line.

Um padrão recomendado é criar um "visualizador" página HTML que aceita o URL de mídia subjacente como parâmetro de consulta e, em seguida, exibir o conteúdo do , potencialmente com controles ou conteúdo adicionais na página.

Os aplicativos da Web só podem adicionar URLs ao índice de conteúdo que estejam na escopo do service worker atual. Em outras palavras, um app da Web não conseguiu adicionar um URL que pertencem a um domínio completamente diferente no índice de conteúdo.

Visão geral

A API de indexação de conteúdo oferece suporte a três operações: adição, listagem e e remoção de metadados. Esses métodos são expostos de uma nova propriedade, index, que foi adicionado ao ServiceWorkerRegistration interface gráfica do usuário.

A primeira etapa na indexação de conteúdo é obter uma referência ao conteúdo ServiceWorkerRegistration Usar navigator.serviceWorker.ready é a maneira mais direta:

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 você estiver fazendo chamadas para a API de indexação de conteúdo a partir de um service worker, em vez de em uma página da Web, consulte o ServiceWorkerRegistration diretamente via registration. Ela já estará definida. como parte do ServiceWorkerGlobalScope.

Como adicionar ao índice

Use o método add() para indexar URLs e os metadados associados a eles. Você decide você escolhe quando os itens são adicionados ao índice. Você pode querer adicionar à em resposta a uma entrada, como clicar em "salvar off-line" . Ou você pode adicionar itens automaticamente sempre que os dados em cache forem atualizados por meio de um mecanismo como a sincronização periódica em segundo plano.

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

Adicionar uma entrada afeta apenas o índice de conteúdo. isso não acrescenta nada cache.

Caso extremo: chame add() do contexto window se os ícones dependerem de um gerenciador fetch

Quando você ligar para add(), o Chrome fará uma solicitação de o URL de cada ícone para garantir que ele tenha uma cópia do ícone a ser usado ao exibindo uma lista de conteúdo indexado.

  • Se você chamar add() no contexto window, ou seja, na Web página), essa solicitação acionará um evento fetch no service worker.

  • Se você chamar add() no service worker (talvez em outro evento) de serviço), a solicitação não acionará o gerenciador fetch do service worker. Os ícones serão buscados diretamente, sem qualquer envolvimento de service worker. Manter ter isso em mente se os ícones dependerem do gerenciador fetch, talvez porque eles existem apenas no cache local e não na rede. Se isso acontecer, verifique se você só chama add() no contexto window.

Como listar o conteúdo do índice

O método getAll() retorna uma promessa para uma lista iterável de entradas indexadas e seus metadados. As entradas retornadas vão conter todos os dados salvos com add():

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

Como remover itens do índice

Para remover um item do índice, chame delete() com o id do item para remover:

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

Chamar delete() afeta apenas o índice. Ele não exclui nada do cache.

Como processar um evento de exclusão do usuário

Quando o navegador exibe o conteúdo indexado, ele pode incluir seu próprio usuário interface com um item de menu Excluir, o que dá às pessoas a chance de indicar que já visualizaram conteúdo indexado anteriormente. É assim que a exclusão aparência da interface no Chrome 80:

O item de menu "Excluir".

Quando alguém selecionar esse item de menu, o service worker do seu app da Web receberá um evento contentdelete. Embora o manuseio desse evento seja opcional, ele fornece uma chance do seu service worker "limpar" conteúdo, como mídia armazenada localmente em cache arquivos, já que alguém indicou que já terminou.

Não é necessário chamar registration.index.delete() dentro contentdelete; se o evento tiver sido disparado, o índice relevante exclusão já foi realizada pelo navegador.

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

Feedback sobre o design da API

Existe algo estranho na API ou que não funciona como esperado? Ou estão faltando partes que você precisa para implementar sua ideia?

Registre um problema no repositório do GitHub de explicação sobre a API Content indexação ou deixe sua opinião a um problema existente.

Problemas com a implementação?

Você encontrou um bug na implementação do Chrome?

Registre um bug em https://new.crbug.com. Incluir o máximo detalhes, instruções simples para reprodução e configuração de Componentes para Blink>ContentIndexing.

Planeja usar a API?

Planejando usar a API de indexação de conteúdo no seu app da Web? Seu apoio público ajuda o Chrome a priorizar recursos e mostra a outros fornecedores de navegador como ele é essencial para apoiá-los.

Quais são algumas das implicações de segurança e privacidade da indexação de conteúdo?

Confira as respostas fornecido em resposta ao questionário de segurança e privacidade do W3C. Se você tiver mais dúvidas, inicie uma discussão no repositório do GitHub do projeto.

Imagem principal de Maksym Kaharlytskyi no Unsplash.