Integração com o SO

Os apps da Web têm um grande alcance. Eles são executados em várias plataformas. Eles são fáceis de compartilhar por links. Mas, tradicionalmente, eles não tinham integração com o sistema operacional. Até pouco tempo atrás, eles nem sequer podiam ser instalados. Felizmente isso mudou, e agora podemos aproveitar a integração para adicionar recursos úteis aos nossos PWAs. Vamos conhecer algumas dessas opções.

Como trabalhar com o sistema de arquivos

Um fluxo de trabalho típico do usuário com arquivos é assim:

• Escolha um arquivo ou uma pasta no dispositivo e abra-o diretamente.
• Faça alterações nesses arquivos ou pastas e salve-as diretamente.
• Crie novos arquivos e pastas.

Antes da API File System Access, os apps da Web não podiam fazer isso. Para abrir os arquivos, era necessário fazer upload, salvar as alterações exigia que os usuários fizessem download, e a web não tinha acesso para criar novos arquivos e pastas no sistema de arquivos do usuário.

Abrir um arquivo

Para abrir um arquivo, usamos o método window.showOpenFilePicker(). Esse método exige um gesto do usuário, como um clique de botão. Veja o restante da configuração para abrir um arquivo:

1. Capture o identificador de arquivo da API do seletor de arquivos do acesso do sistema de arquivos. Isso fornece informações básicas sobre o arquivo.
2. Usando o método getFile() do identificador, você terá um tipo especial de Blob, chamado File, que inclui outras propriedades somente leitura (como nome e data da última modificação) do arquivo. Por ser um Blob, os métodos Blob podem ser chamados nele, como text(), para receber seu conteúdo.

// Have the user select a file.
const [ handle ] = await window.showOpenFilePicker();
// Get the File object from the handle.
const file = await handle.getFile();
// Get the file content.
// Also available, slice(), stream(), arrayBuffer()
const content = await file.text();

Salvando alterações

Para salvar alterações em um arquivo, você também precisa de um gesto do usuário. Depois:

1. Use o identificador de arquivo para criar um FileSystemWritableFileStream.
2. Faça as alterações no fluxo. Isso não atualiza o arquivo no local. Em vez disso, um arquivo temporário normalmente é criado.
3. Por fim, quando terminar de fazer as alterações, você fecha o stream, o que passa as alterações de temporárias para permanentes.

Vejamos isso no código:

// Make a writable stream from the handle.
const writable = await handle.createWritable();
// Write the contents of the file to the stream.
await writable.write(contents);
// Close the file and write the contents to disk.
await writable.close();

Atenção : o Safari implementa a API File System Access, não para o sistema público, mas como uma sandbox de origem. Só é possível ler e gravar arquivos nesse sistema virtual usando essa API.

Gerenciamento de arquivos

A API File System Access permite abrir arquivos de dentro do aplicativo, mas e o contrário? Os usuários querem definir o app favorito deles como padrão para abrir arquivos. A API de processamento de arquivos é uma API experimental que permite PWAs instalados: registre-se como um gerenciador de arquivos no dispositivo de um usuário, especificando o tipo MIME e a extensão de arquivo com suporte do PWA no manifesto do seu app da Web. Você pode especificar ícones de arquivo personalizados para as extensões compatíveis.

Após o registro, o PWA instalado vai aparecer como uma opção no sistema de arquivos do usuário, permitindo que ele abra o arquivo diretamente nele. Confira um exemplo da configuração do manifesto para um PWA para ler arquivos de texto:

...
"file_handlers": [
     {
         "action": "/open-file",
         "accept": {
             "text/*": [".txt"]
         }
     }
]
...

Processamento de URLs

Com o gerenciamento de URL, seu PWA pode capturar links que fazem parte do escopo do sistema operacional e renderizá-los em uma janela do PWA, em vez da guia do navegador padrão. Por exemplo, se você receber uma mensagem com um link para o PWA ou clicar em um link direto (um URL que leva a um conteúdo específico) no PWA, o conteúdo será aberto em uma janela independente.

Esse comportamento fica disponível automaticamente no Android quando o WebAPK é usado, como quando os usuários instalam um PWA com o Chrome. É impossível capturar URLs em PWAs instalados no iOS e no iPadOS a partir do Safari.

Para navegadores de computadores, a comunidade criou uma nova especificação. No momento, ela é experimental. Ela adiciona um novo membro ao arquivo de manifesto: url_handlers. Essa propriedade espera uma matriz de origens que o PWA quer capturar. A origem do PWA será concedida automaticamente, e as outras origens precisam aceitar esse processamento em um arquivo chamado web-app-origin-association. Por exemplo, se o manifesto do PWA estiver hospedado no web.dev e você quiser adicionar a origem app.web.dev, ele vai ficar assim:

"url_handlers": [
    {"origin": "https://app.web.dev"},
]

Nesse caso, o navegador vai verificar se um arquivo existe em app.web.dev/.well-known/web-app-origin-association, aceitando o processamento de URL do URL do escopo do PWA. O desenvolvedor precisa criar esse arquivo. No exemplo abaixo, o arquivo é assim:

{
    "web_apps": [
        {
            "manifest": "/mypwa/app.webmanifest",
            "details": {
                "paths": [ "/*" ]
            }
        }
    ]
}

No Android com WebAPKs, os PWAs são registrados automaticamente como gerenciadores do escopo do manifesto com um filtro de intent do Android, e não é possível adicionar mais origens ou escopos a ele. No iOS e no iPadOS, você só pode processar URLs com PWAs publicados na App Store, como aqueles criados com o PWABuilder.

Processamento de protocolo de URL

O processamento de URL funciona com URLs de protocolo https padrão, mas é possível usar esquemas de URI personalizados, como pwa://. Em vários sistemas operacionais, os apps instalados ganham essa capacidade ao registrarem seus esquemas.

Para PWA, esse recurso é ativado usando a API URL Protocol Handler, disponível apenas em dispositivos desktop. Só é possível permitir protocolos personalizados para dispositivos móveis ao distribuir seu PWA em app stores.

Atenção : para PWAs que usam a API URL do gerenciador de protocolo, o nome do protocolo precisa ser um dos esquemas da lista segura ou usar um prefixo web+. Portanto, no nosso exemplo, um link precisa apontar para web+pwa:// para abrir o PWA.

Para fazer o registro, use o métodoregister ProtocolHandler() ou use o membro protocol_handlers no seu manifesto, com o esquema desejado e o URL que você quer carregar no contexto do seu PWA, como:

...
{
  "protocol_handlers": [
    {
      "protocol": "web+pwa",
      "url": "/from-protocol?value=%s"
    },
  ]
}
...

Você pode encaminhar o URL from-protocol para o gerenciador correto e receber a string de consulta value no seu PWA. O %s é um marcador para o URL com escape que acionou a operação. Portanto, se você tiver um link em algum lugar como <a href="web+pwa://testing">, o PWA vai abrir /from-protocol?value=testing.

Chamar outros apps

Você pode usar esquemas de URI para se conectar a qualquer outro app instalado (PWA ou não) nos dispositivos dos usuários em todas as plataformas. Você só precisa criar um link ou usar navigator.href e apontar para o esquema de URI que quiser, transmitindo os argumentos com escape de URL.

Você pode usar esquemas padrão bem conhecidos, como tel: para ligações telefônicas, mailto: para envio de e-mails ou sms: para mensagens de texto. Também é possível saber mais sobre esquemas de URL de outros apps, como mensagens conhecidas, mapas, navegação, reuniões on-line, redes sociais e app stores.

Observação : em vez de usar esquemas de URI particulares para se comunicar com apps de mensagens e mídias sociais, você pode usar a API Web Share genérica

Compartilhamento na Web

Compatibilidade com navegadores

• 89
• 93
• 12.1

Origem

Com a API Web Share, o PWA pode enviar conteúdo pelo canal compartilhado para outros apps instalados no dispositivo.

A API está disponível apenas em sistemas operacionais com um mecanismo share, incluindo Android, iOS, iPadOS, Windows e ChromeOS. É possível compartilhar um objeto que contenha:

• Texto (propriedades title e text)
• Um URL (propriedade url)
• Arquivos (propriedade files).

Para conferir se o dispositivo atual pode compartilhar dados simples, como texto, confira a presença do método navigator.share(). Assim, você verifica se o método navigator.canShare() está presente.

Para solicitar a ação de compartilhamento, chame navigator.share(objectToShare). Essa chamada retorna uma promessa que é resolvida com undefined ou rejeitada com uma exceção.

Destino de compartilhamento da Web

A API Web Share Target permite que seu PWA seja o destino de uma operação de compartilhamento de outro app nesse dispositivo, seja ele um PWA ou não. Seu PWA recebe os dados compartilhados por outro app.

No momento, ele está disponível no Android com WebAPK e ChromeOS e funciona apenas depois que o usuário instala o PWA. O navegador registra o alvo de compartilhamento no sistema operacional quando o aplicativo é instalado.

Você configura um destino de compartilhamento da Web no manifesto com o membro share_target definido nas especificações de rascunho do destino de compartilhamento da Web. share_target é definido como um objeto com algumas propriedades:

action

URL que vai ser carregado em uma janela PWA e que vai receber os dados compartilhados.

method

O método verbo HTTP será usado para a ação, como GET, POST ou PUT.

enctype

(Opcional) Tipo de codificação para os parâmetros. Por padrão, é application/x-www-form-urlencoded, mas também pode ser definido como multipart/form-data para métodos como POST.

params

Um objeto que mapeará dados de compartilhamento (das chaves: title, text, url e files do Web Share) para argumentos que o navegador transmitirá no URL (em method: 'GET') ou no corpo da solicitação usando a codificação selecionada.

Observação : é possível analisar uma solicitação POST do lado do servidor ou do service worker se quiser evitar uma viagem à rede. Confira este exemplo para mais detalhes.

Por exemplo, você pode definir para seu PWA que quer receber dados compartilhados (somente título e URL) adicionando ao seu manifesto:

...
"share_target": {
   "action": "/receive-share/",
   "method": "GET",
   "params": {
      "title": "shared_title",
      "url": "shared_url"
   }
}
...

No exemplo anterior, se algum app no sistema compartilhar um URL com um título, e o usuário escolher seu PWA na caixa de diálogo, o navegador vai criar uma nova navegação para o /receive-share/?shared_title=AAA&shared_url=BBB da origem, em que "AAA" é o título compartilhado e "BBB" é o URL compartilhado. É possível usar o JavaScript para ler esses dados da string window.location, analisando-os com o construtor URL.

O navegador vai usar o nome e o ícone do PWA do seu manifesto para alimentar a entrada de compartilhamento do sistema operacional. Não é possível escolher um conjunto diferente para essa finalidade.

Observação : a página que processa os dados compartilhados precisa estar acessível off-line. Você não quer que os usuários escolham seu app e encontrem um erro porque eles não têm uma conexão no momento.

Para ver exemplos mais detalhados e saber como receber arquivos, consulte Como receber dados compartilhados com a API Web Share Target.

Seleção de contatos

Compatibilidade com navegadores

• x
• x
• x
• x

Origem

Com a API Contact Picker, é possível solicitar que o dispositivo renderize uma caixa de diálogo nativa com todos os contatos do usuário para que ele possa escolher um ou mais. Seu PWA poderá receber os dados que você quiser desses contatos.

A API Contact Picker está disponível principalmente em dispositivos móveis e tudo é feito na interface do navigator.contacts em plataformas compatíveis.

Você pode solicitar as propriedades disponíveis para consulta com o navigator.contacts.getProperties() e solicitar a seleção de um ou vários contatos com uma lista das propriedades desejadas.

Alguns exemplos de propriedades são name, email, address e tel. Quando você pedir para o usuário escolher um ou mais contatos, chame navigator.contacts.select(properties), transmitindo uma matriz de propriedades que você quer receber.

Atenção : a API não garante que os objetos retornados tenham todas as propriedades solicitadas. Por isso, verifique novamente a presença deles.

O exemplo a seguir listará os contatos recebidos pelo seletor.

async function getContacts() {
   const properties = ['name', 'email', 'tel'];
   const options = { multiple: true };
   try {
     const contacts = await navigator.contacts.select(properties, options);
     console.log(contacts);
   } catch (ex) {
     // Handle any errors here.
   }
}

Recursos

• API File System Access: como simplificar o acesso a arquivos locais (em inglês)
• Permitir que aplicativos da Web instalados sejam gerenciadores de arquivos
• Gerenciar arquivos em Progressive Web Apps
• Integrar com a interface de Compartilhamento do SO usando a API Web Share
• Compartilhar conteúdo com outros apps
• Como receber dados compartilhados com a API Web Share Target
• Um seletor de contatos para a Web