Seu app está instalado? A API Get Installed Related Apps vai te ajudar!

Pete LePage

Alexey Rodionov

A API Get Installed Related Apps permite receber a lista de apps relacionados instalados com detalhes sobre eles.

Ele permite verificar se o Progressive Web App (PWA), o app Android ou o app da Plataforma Universal do Windows (UWP) está instalado no dispositivo atual, tanto no próprio PWA quanto em uma página da Web relacionada (por exemplo, um site de marketing de produtos).

O Bubblewrap é um conjunto de bibliotecas de código aberto e uma ferramenta de linha de comando (CLI) para Node.js. O Bubblewrap foi desenvolvido pela equipe do Google Chrome para ajudar os desenvolvedores a gerar, criar e assinar um projeto Android que inicia o PWA como uma Atividade confiável na Web (TWA).

O PWABuilder é um projeto de código aberto desenvolvido pela Microsoft que permite aos desenvolvedores empacotar e assinar PWAs para publicação em várias lojas, incluindo Microsoft Store, Google Play Store, App Store e Meta Quest Store. Para isso, basta inserir o URL de um PWA, inserir/editar os metadados do app e clicar no botão "Gerar".

O PWABuilder usa o Bubblewrap para empacotar PWAs para Android e ChromeOS.

Se o app já estiver instalado, você poderá personalizar a experiência do usuário.

Exemplo:

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

Para usar a API Get Installed Related Apps, informe ao app sobre a página e à página sobre o app. Depois de definir a relação entre os dois, você pode verificar se o app relacionado está instalado.

Para evitar que os sites testem um conjunto muito amplo de apps próprios, apenas os três primeiros apps declarados no manifesto do app da Web serão considerados.

Assim como a maioria das outras APIs da Web avançadas, a API Get Installed Related Apps só está disponível quando veiculada por HTTPS.

O que é a API Get Installed Related Apps?

Chamar o método assíncrono navigator.getInstalledRelatedApps() retorna uma promessa que é resolvida com uma matriz de objetos contendo detalhes sobre apps que estão:

• instalado no dispositivo atual,
• definido no campo related_applications do manifesto do app da Web.
• ter uma relação verificada com uma página em que o método navigator.getInstalledRelatedApps() é chamado. Consulte as próximas seções para mais detalhes.

const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

Chamar console.log(installedRelatedApps) retorna algo como:

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

Por exemplo, para verificar se há apps relacionados instalados no dispositivo do usuário, use esta linha de código:

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

Se você souber o ID do pacote, use o seguinte comando de uma linha para receber o número da versão do app Android relacionado instalado:

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

Isso significa que o método navigator.getInstalledRelatedApps() ainda vai retornar apps relacionados instalados, mesmo que a versão deles seja inferior a min_version ou que o certificado de assinatura não corresponda a nenhum fingerprints declarado no campo related_applications do manifesto do app Web.

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.

Somente Android: Chrome 80 ou mais recente

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 conferir 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 usando UWP) está instalado.

Somente no Windows: Chrome 85 ou mais recente, Edge 85 ou mais recente

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 conferir 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": [ "*" ]
}]

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 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.

Confira esta demonstração.

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.

Compatível com:

Android: Chrome 84 ou versões mais recentes

Computador (Windows, macOS, Linux, ChromeOS): Chrome 140 ou mais recente, Edge 140 ou mais recente

Fale sobre o PWA

Adicione uma entrada related_applications no 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 ID do app da Web declarado no campo id do manifesto do app da Web ou calculado pelo navegador (necessário para computadores, não para Android).

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

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 navigator.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 a página de destino é veiculada de www.example.com e o PWA de app.example.com.

Compatível com:

Somente Android: Chrome 84 ou versões mais recentes

Informar seu PWA sobre seu site

Primeiro, adicione links de recursos digitais ao servidor de onde sua PWA é veiculada. Isso ajuda a definir a relação entre seu site e o 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"
    }
  }
]

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.

Links úteis

• Explicação pública da API Get Installed Related Apps
• 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.