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

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.

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 o seguinte comando de uma linha:

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;

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.

Compatível com:

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

Compatível com:

• Somente 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

Falar 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 seu PWA é veiculado. 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 web app que vai realizar a verificação (não o manifesto do web app 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.

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.