Iniciar a API Handler

Controle como seu app é iniciado.

Thomas steiner

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

Status atual

Step Status
1. Criar explicação Concluído
2. Criar rascunho inicial das especificações Concluído
3. Reunir feedbacks e iterar no design Completos
4. Teste de origem Completos
5. Lançamento Concluído

Como usar a API Launch Handler

Suporte ao navegador

O Gerenciador de inicialização está disponível apenas no ChromeOS.

Compatibilidade com navegadores

  • 110
  • 110
  • x
  • x

Origem

Interfaces

A API Launch Handler define duas novas interfaces.

LaunchParams : um objeto que contém o targetURL que será processado pelo consumidor. LaunchQueue : a fila é iniciada até ser processada pelo consumidor especificado.

O membro do manifesto launch_handler

Para especificar de maneira declarativa o comportamento de inicialização do app, adicione o membro 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 esse cliente precisa ser navegado. O exemplo abaixo mostra um arquivo com valores exemplares que sempre encaminha todas as inicializações para um novo cliente.

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

Se não for especificado, launch_handler será definido como {"client_mode": "auto"} por padrão. 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 item que interagiu mais recentemente com o contexto de navegação em uma janela de app da Web é redirecionado para o URL de destino da inicialização.
    • focus-existing: o contexto de navegação que interagiu mais recentemente 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 início será colocado na fila no window.launchQueue do documento.
    • auto: o comportamento depende do user agent para decidir o que funciona melhor na plataforma. Por exemplo, os dispositivos móveis oferecem suporte apenas a clientes únicos e usam existing-client, enquanto os dispositivos desktop oferecem suporte a várias janelas e usam 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 prejudicar a compatibilidade com versões anteriores das 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 eram compatíveis com "focus-matching-url".

Como usar window.launchQueue

No código a seguir, a função extractSongID() extrai um songID do URL transmitido na inicialização. É usado para reproduzir uma música no PWA do player de música.

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

Demonstração

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

  1. Instale o app Musicr 2.0 em um dispositivo ChromeOS.
  2. Envie um link para si mesmo em um aplicativo de chat no formato https://launch-handler.glitch.me?track=https://example.com/music.mp3. Você pode 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 faixa.
  4. Clique no link no app de chat novamente e observe que você não verá uma segunda instância do Musicr 2.0.

Feedback

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

Fale sobre o design da API

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

Informar um problema com a implementação

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 simples para reprodução e digite Blink>AppManifest na caixa Componentes. O Glitch funciona muito bem para compartilhar repetições rápidas e fáceis.

Mostrar suporte para a API

Você planeja usar a API Launch Handler? Seu suporte público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegador como esse suporte é essencial.

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

Links úteis