Iniciar a API Handler

Controle como o app é iniciado.

Thomas Steiner

A API Launch Handler permite controlar como o app é iniciado, por exemplo, se ele usa uma janela existente ou uma nova e se a janela escolhida é navegada para o URL de inicialização. Assim como a API File Handling, essa API também enfileira um objeto LaunchParams no window.launchQueue da página aberta.

Status atual

Etapa Status
1. Criar uma explicação Concluído
2. Criar um rascunho inicial da especificação Concluído
3. Coletar feedback e iterar o design Concluído
4. Teste de origem. Concluído
5. Lançamento Concluído

Usar a API Launch Handler

Suporte ao navegador

Interfaces

A API Launch Handler define duas novas interfaces.

LaunchParams : um objeto que contém o targetURL a ser processado pelo consumidor. LaunchQueue : as filas são iniciadas até serem processadas pelo consumidor especificado.

O membro do manifesto launch_handler

Para especificar de forma declarativa o comportamento de inicialização do app, adicione o membro de manifesto launch_handler ao manifesto. Ele tem um subcampo chamado client_mode. Ele permite controlar se um cliente novo ou atual precisa ser iniciado e se ele precisa ser navegado. O exemplo a seguir mostra um arquivo com valores de exemplo que encaminhariam sempre todas as inicializações para um novo cliente.

{
  "launch_handler": {
    "client_mode": "navigate-new"
  }
}

Se não for especificado, launch_handler será usado como padrão para {"client_mode": "auto"}. Os valores permitidos para os subcampos são:

  • client_mode:
    • navigate-new: um novo contexto de navegação é criado em uma janela de app da Web para carregar o URL de destino da inicialização.
    • navigate-existing: o contexto de navegação mais recente em uma janela de app da Web é direcionado para o URL de destino da inicialização.
    • focus-existing: o contexto de navegação mais recente em uma janela de app da Web é escolhido para processar a inicialização. Um novo objeto LaunchParams com o targetURL definido como o URL de inicialização será enfileirado na window.launchQueue do documento.
    • auto: o comportamento depende do agente do usuário para decidir o que funciona melhor para a plataforma. Por exemplo, dispositivos móveis só oferecem suporte a clientes únicos e usariam existing-client, enquanto dispositivos de computador oferecem suporte a várias janelas e usariam navigate-new para evitar a perda de dados.

A propriedade client_mode também aceita uma lista (matriz) de valores, em que o primeiro valor válido será usado. Isso permite que novos valores sejam adicionados à especificação sem interromper a compatibilidade com versões anteriores com implementações atuais.

Por exemplo, se o valor hipotético "focus-matching-url" fosse adicionado, os sites especificariam "client_mode": ["focus-matching-url", "navigate-existing"] para continuar controlando o comportamento de navegadores mais antigos que não ofereciam suporte a "focus-matching-url".

Usar window.launchQueue

No código abaixo, a função extractSongID() extrai um songID do URL transmitido na inicialização. Ele é usado para tocar uma música em um app de música PWA.

if ('launchQueue' in window) {
  launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const songID = extractSongId(launchParams.targetURL);
      if (songID) {
        playSong(songID);
      }
    }
  });
}

Demonstração

Confira uma demonstração da API Launch Handler em ação na demonstração do Launch Handler de PWA. Confira o código-fonte do aplicativo para saber como ele usa a API Launch Handler.

  1. Instale o app Musicr 2.0.
  2. Envie um link para você mesmo em um aplicativo de chat do formulário https://launch-handler.glitch.me?track=https://example.com/music.mp3. É possível personalizar https://example.com/music.mp3 para qualquer URL que aponte para um arquivo de áudio, por exemplo, https://launch-handler.glitch.me?track=https://cdn.glitch.me/3e952c9c-4d6d-4de4-9873-23cf976b422e%2Ffile_example_MP3_700KB.mp3?v=1638795977190.
  3. Clique no link no app de chat e observe como o Musicr 2.0 abre e toca a música.
  4. Clique no link no app de chat novamente e observe que você não vai receber uma segunda instância do Musicr 2.0.

Feedback

A equipe do Chromium quer saber sobre suas experiências com a API Launch Handler.

Conte sobre o design da API

Há algo na API que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa implementar para implementar sua ideia? Tem dúvidas ou comentários sobre o modelo de segurança? Envie um problema de especificação no repositório do GitHub correspondente ou adicione sua opinião a um problema existente.

Informar um problema com a implementação

Você encontrou um bug na implementação do Chromium? Ou a implementação é diferente da especificação? Registre um bug em new.crbug.com. Inclua o máximo de detalhes possível, instruções para reprodução e digite Blink>AppManifest na caixa Components.

Mostrar suporte para a API

Você planeja usar a API Launch Handler? Seu apoio público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

Envie um tweet para @ChromiumDev usando a hashtag #LaunchHandler e diga onde e como você está usando.

Links úteis