Instalar apps da Web com o novo elemento de instalação HTML

Patrick Brosset

Publicado em 12 de maio de 2026

A instalação de apps da Web sempre exigiu JavaScript. Quando você usa o evento beforeinstallprompt, o fluxo de instalação fica totalmente no script. O novo <install> elemento muda isso: solte um único elemento HTML na página e o navegador renderiza um botão de instalação confiável para você, sem necessidade de JavaScript.

A equipe do Microsoft Edge, em colaboração com a equipe do Chrome, implementou o <install> elemento no Chromium. Agora ele está disponível para teste por trás de uma flag no Chrome ou no Edge a partir da versão 148 e como um teste de origem que pode ser usado nos dois navegadores a partir da versão 148 e até a 153.

Teste e saiba como ele se compara à API Web Install imperativa (navigator.install()), que tem o próprio teste de origem.

O problema

A instalação de apps da Web é fragmentada. Cada navegador tem o próprio conjunto de pontos de entrada, por exemplo, ícones da barra de endereço, itens de menu e avisos. Os desenvolvedores têm controle limitado sobre quando e como o fluxo de instalação é exibido.

Criar uma experiência semelhante a uma app store que permita aos usuários instalar outros apps no seu site é mais difícil, porque a instalação tem sido historicamente restrita à página atual.

O <install> elemento

O conteúdo e a apresentação do novo elemento HTML <install> são controlados pelo navegador. Semelhante a outros elementos de permissão, como <geolocation>, o controle do navegador sobre o texto do rótulo, o idioma e a aparência do botão significa que ele pode confiar no clique do usuário como um sinal genuíno de intenção.

É improvável que um usuário que clica em um botão com o rótulo "Instalar aplicativo maravilhoso" se surpreenda quando um aviso de instalação aparecer.

Como o navegador renderiza o botão, você recebe uma instalação confiável com código mínimo e sem necessidade de orquestrar a cerimônia beforeinstallprompt em JavaScript.

Instalar o app atual

Se a página atual tiver um link para um manifesto com um id campo, um único elemento será tudo o que você precisa:

<install></install>

O navegador renderiza o botão com texto e iconografia padronizados e, quando o usuário clica nele, o fluxo de instalação normal do navegador é iniciado.

Instalar um app diferente

Para instalar um app da Web que esteja em uma origem diferente da página atual, use o atributo installurl para apontar para o outro app da Web:

<install installurl="https://awesome-app.com/"></install>

Se a página em https://awesome-app.com tiver um link para um manifesto que define um campo id, é tudo o que você precisa fazer.

Se não houver um campo id, use o atributo manifestid para fornecer um manifesto id calculado:

<install installurl="https://awesome-app.com/"
  manifestid="https://awesome-app.com/?source=pwa">
</install>

Para receber o id do manifesto calculado:

1. Abra o DevTools.
2. Acesse a guia Application.
3. Na seção Identity, copie o valor Computed App ID.

Usar o botão <install> para instalar outros apps de origem significa que você pode criar uma página de catálogo que permite aos usuários instalar vários apps, cada um com o próprio botão <install>.

Fornecer conteúdo substituto

Se o navegador não oferecer suporte ao elemento <install>, qualquer HTML que você colocar dentro do elemento será exibido:

<install installurl="https://awesome-app.com/">
  <a href="https://awesome-app.com/">Launch Awesome App</a>
</install>

Detectar suporte

Se o conteúdo substituto não for suficiente para seu caso de uso e você preferir implementar uma experiência do usuário diferente em navegadores que não oferecem suporte ao <install> elemento, use JavaScript para detectar o suporte:

if ('HTMLInstallElement' in window) {
  // The <install> element is supported.
}

Processar eventos

O elemento <install> dispara eventos que podem ser detectados para erros de sucesso, dispensa, e validação:

const button = document.querySelector('install');

button.addEventListener('promptaction', () => {
  console.log('Installation succeeded');
});

button.addEventListener('promptdismiss', () => {
  console.log('User dismissed the install prompt');
});

button.addEventListener('validationstatuschanged', (e) => {
  if (e.target.invalidReason === 'install_data_invalid') {
    console.error('Invalid install data:', e.target.invalidReason);
  }
});

Teste hoje mesmo

Para testar o <install> elemento hoje, você tem duas opções:

• Teste o elemento localmente apenas no seu dispositivo.
• Teste o elemento em condições reais, com seus usuários, inscrevendo-se no teste de origem.

Testar localmente

Para testar o elemento no seu dispositivo hoje:

1. Use o Chrome ou o Edge versão 148 ou mais recente.
2. Acesse about://flags/#web-app-install-element em uma nova guia.
3. Defina o elemento de instalação do app da Web como Ativado.
4. Reinicie o navegador.

Teste no seu site ativo usando o teste de origem

O teste de origem permite que usuários reais no seu site de produção usem o recurso sem precisar ativar a flag primeiro.

1. Abra a página de registro do teste de origem do elemento <install> .
2. Faça login.
3. Clique em Registrar.
4. Insira a origem do seu site e preencha o restante do formulário.
5. Depois que o formulário for enviado, você receberá uma string de token.
6. Adicione o token às páginas do seu site usando uma tag <meta>:

<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">

Como alternativa, você pode enviar o token como um cabeçalho de resposta HTTP:

Origin-Trial: YOUR_TOKEN_HERE

O teste de origem está disponível para o Chrome e o Edge nas versões 148 a 153, e o mesmo token vai funcionar nos dois navegadores. Para saber mais sobre testes de origem, consulte:

• Introdução aos testes de origem, para o Chrome.
• Teste APIs e recursos experimentais usando testes de origem, para o Edge.

Veja na prática

Confira a demonstração da loja de elementos <install> Element Store demo, um catálogo de PWA que usa o elemento <install> para permitir a instalação de vários apps de exemplo.

Comparação com a API Web Install

O elemento <install> não é a única maneira de experimentar como melhorar as instalações de apps na Web.

Anteriormente, fizemos experimentos com a API Web Install (navigator.install()), que é uma API JavaScript imperativa que também permite que seu site acione a instalação de apps da Web de mesma origem ou de origem cruzada. Para saber mais, consulte A API Web Install está pronta para testes.

A API Web Install também tem o próprio teste de origem.

Confira como as duas abordagens se comparam:

Deixe sua opinião

Estamos buscando feedback ativamente sobre as duas abordagens. Dependendo das suas necessidades, nós poderíamos adicionar suporte ao elemento <install>, ou à API navigator.install(), ou a ambos.

Para compartilhar feedback sobre o elemento <install>, abra um problema no repositório do WICG dedicado a essa proposta.

Para compartilhar feedback sobre a API navigator.install(), adicione um comentário ao problema Feedback do desenvolvedor: navigator.install versus <install> elemento issue.

Recursos

• Explicação: o elemento <install>
• Demonstração: o repositório de elementos <install>
• Instruções de uso e origem da demonstração
• Entrada de status da plataforma Chrome
• A API Web Install está pronta para testes (blog do Edge)
• Explicação da API Web Install