Seu app está instalado? getinstaladoRelatedApps() vai avisar você!

O método getInstalledRelatedApps() permite que seu site verifique se o app Android/UWP ou PWA está instalado no dispositivo de um usuário.

Pete LePage

Alexey Rodionov

O que é a API getInstalledRelatedApps()?

O método getInstalledRelatedApps() retorna a lista de apps relacionados instalados.

Chamar navigator.getInstalledRelatedApps() retorna uma promessa que é resolvida com uma matriz de apps relacionados instalados no dispositivo do usuário.

const relatedApps = await navigator.getInstalledRelatedApps();
relatedApps.forEach((app) => {
  console.log(app.id, app.platform, app.url);
});

Ela permite que sua página verifique se seu app Android, app da Plataforma Universal do Windows (UWP) ou Progressive Web App (PWA) já está instalado no dispositivo de um usuário e permite personalizar a experiência do usuário se estiver.

Por exemplo, se o app já estiver instalado:

• Redirecionar o usuário de uma página de marketing de produto diretamente para seu app.
• Centralizar algumas funcionalidades, como notificações, no outro app para evitar notificações duplicadas.
• Não promover a instalação do PWA se o outro app já estiver instalado.

Tipos de apps compatíveis que você pode verificar

Verificar se o app Android está instalado

Seu site pode verificar se o app Android está instalado.

Informar ao app Android sobre seu site

Primeiro, atualize seu app Android para definir a relação entre seu site e o aplicativo Android usando o sistema Digital Asset Links. Isso verifica se apenas seu site pode verificar se o app Android está instalado.

No AndroidManifest.xml do seu app Android, adicione uma entrada asset_statements:

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

Em seguida, em strings.xml, adicione a seguinte declaração de recurso, atualizando site com seu domínio. Não se esqueça de incluir os caracteres de escape.

<string name="asset_statements">
  [{
    \"relation\": [\"delegate_permission/common.handle_all_urls\"],
    \"target\": {
      \"namespace\": \"web\",
      \"site\": \"https://example.com\"
    }
  }]
</string>

Depois de concluir, instale o app atualizado no dispositivo ou publique na Google Play Store ou em qualquer outra plataforma de distribuição de apps Android.

Informar seu site sobre o app Android

Em seguida, informe seu site sobre o app Android adicionando um manifesto de app da Web à página. O manifesto precisa incluir a propriedade related_applications, uma matriz que fornece os detalhes sobre o app, incluindo platform e id.

• platform precisa ser play
• id é o ID do pacote Android.

{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome"
  }]
}

Verificar se o app está instalado

Por fim, chame a função assíncrona navigator.getInstalledRelatedApps() para verificar se o app Android está instalado.

Verificar se o app do Windows (UWP) está instalado

Seu site pode verificar se o app do Windows (criado com UWP) está instalado.

Informar ao app do Windows sobre seu site

Você precisará atualizar seu app do Windows para definir a relação entre seu site e o aplicativo do Windows usando Processadores de URI. Isso verifica se apenas seu site pode verificar se o app do Windows está instalado.

Adicione o registro da extensão Windows.appUriHandler ao arquivo de manifesto do app Package.appxmanifest. Por exemplo, se o endereço do seu site for example.com, adicione a seguinte entrada ao manifesto do app:

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

Talvez seja necessário adicionar o namespace uap3 ao atributo <Package>.

Em seguida, crie um arquivo JSON (sem a extensão .json) chamado windows-app-web-link e forneça o nome da família de pacotes do app. Coloque esse arquivo na raiz do servidor ou no diretório /.well-known/. Você pode encontrar o nome da família de pacotes na seção "Pacotes" do designer de manifesto do app.

[{
  "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ]
}]

Confira esta demonstração.

Consulte Ativar apps para sites usando gerenciadores de URI de app para detalhes completos sobre a configuração de gerenciadores de URI.

Informar seu site sobre o app do Windows

Em seguida, informe seu site sobre o app do Windows adicionando um manifesto de app da Web à página. O manifesto precisa incluir a propriedade related_applications, uma matriz que fornece os detalhes sobre o app, incluindo platform e id.

• platform precisa ser windows
• id é o nome da família de pacotes do seu app, anexado pelo valor <Application> Id no arquivo Package.appxmanifest.

{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App"
  }]
}

Verificar se o app está instalado

Por fim, chame a função assíncrona navigator.getInstalledRelatedApps() para verificar se o app do Windows está instalado.

Verificar se o PWA já está instalado (no escopo)

O PWA pode verificar se já está instalado. Nesse caso, a página que faz a solicitação precisa estar no mesmo domínio e no escopo do seu PWA, conforme definido no manifesto do app da Web.

Fale sobre o PWA

Adicione uma entrada related_applications ao manifesto do app da Web do PWA para que ele saiba sobre si mesmo.

• platform precisa ser webapp
• url é o caminho (pode ser relativo) para o manifesto do app da Web do seu PWA.
• id é o caminho completo para o app da Web (obrigatório para computador, não necessário para Android)

{
  …
  "scope": "/",
  "start_url": "/",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com"
  }],
  …
}

Verificar se o PWA está instalado

Por fim, chame a função assíncrona navigator.getInstalledRelatedApps() no escopo do seu PWA para verificar se ele está instalado. Se getInstalledRelatedApps() for chamado fora do escopo do seu PWA, ele vai retornar []. Consulte a próxima seção para obter detalhes.

Verificar se o Progressive Web App está instalado (fora do escopo)

Seu site pode verificar se o PWA está instalado, mesmo que a página esteja fora do escopo do PWA. Por exemplo, uma página de destino veiculada de /landing/ pode verificar se o PWA veiculado de /pwa/ está instalado ou se sua página de destino é veiculada de www.example.com e seu PWA é veiculado de app.example.com.

Informar seu PWA sobre seu site

Primeiro, adicione links de recursos digitais ao servidor de onde seu PWA é fornecido. Isso ajuda a definir a relação entre seu site e seu PWA e verifica se apenas seu site pode verificar se o PWA está instalado.

Adicione um arquivo assetlinks.json ao diretório /.well-known/ do domínio em que o PWA está localizado, por exemplo, app.example.com. Na propriedade site, forneça o caminho completo para o manifesto do app da Web que vai realizar a verificação (não o manifesto do app da Web do seu PWA).

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

Informar seu site sobre o PWA

Em seguida, informe seu site sobre o app PWA adicionando um manifesto de app da Web à página. O manifesto precisa incluir a propriedade related_applications, uma matriz que fornece os detalhes sobre seu PWA, incluindo platform e url.

• platform precisa ser webapp
• url é o caminho completo para o manifesto do app da Web do seu PWA.

{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json"
  }]
}

Verificar se o PWA está instalado

Por fim, chame a função assíncrona navigator.getInstalledRelatedApps() para verificar se o PWA está instalado.

Ainda tem dúvidas?

Ainda tem dúvidas? Confira a tag getInstalledRelatedApps no StackOverflow para saber se mais alguém teve dúvidas semelhantes. Se não for, faça sua pergunta lá e marque com a tag progressive-web-apps. Nossa equipe monitora essa tag com frequência e tenta responder às suas perguntas.

Feedback

Você encontrou um bug na implementação do Chrome? Ou a implementação é diferente da especificação?

• Registre um bug em https://new.crbug.com. Inclua o máximo de detalhes possível, forneça instruções para reproduzir o bug e insira Mobile>WebAPKs na caixa Componentes.

Mostrar suporte para a API

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

• Compartilhe como você planeja usar a API na thread do WICG Discourse.
• Envie um tweet para @ChromiumDev usando a hashtag #getInstalledRelatedApps e conte para nós onde e como você está usando.

Links úteis

• Explicação pública da API getInstalledRelatedApps()
• Rascunho de especificação
• Bug de rastreamento
• Entrada do ChromeStatus.com
• Componente Blink: Mobile>WebAPKs

Obrigado

Agradecemos a Sunggook Chue, da Microsoft, por ajudar com os detalhes para testar apps do Windows, e a Rayan Kanso, por ajudar com os detalhes do Chrome.