O método getInstalledRelatedApps()
permite que seu site verifique se
o app iOS/Android/desktop ou o PWA está instalado no dispositivo de um usuário.
O que é a API getInstalledRelatedApps()?
O getInstalledRelatedApps()
possibilita que sua página
verifique se seu app para dispositivos móveis ou computador ou, em alguns casos, se o Progressive
Web App (PWA) já está instalado no dispositivo do usuário, além de permitir
personalizar a experiência do usuário.
Por exemplo, se o app já estiver instalado:
- Redirecionar o usuário de uma página de marketing de produto diretamente para o app.
- Centralizar algumas funcionalidades, como notificações no outro app, para evitar notificações duplicadas.
- Não promover a instalação do seu PWA se o outro app já estiver instalado.
Para usar a API getInstalledRelatedApps()
, informe o app sobre
seu site e, em seguida, informe o site sobre o app. Depois de definir a
relação entre os dois, você pode verificar se o app está instalado.
Tipos de apps compatíveis que você pode verificar
Tipo de app | Pode ser verificado em |
---|---|
App para Android |
Somente Android Chrome 80 ou mais recente |
App Windows (UWP) |
Somente Windows Chrome 85 ou mais recente Edge 85 ou mais recente |
App da Web progressivo Instalado no mesmo escopo ou em um escopo diferente. |
Somente para Android Chrome 84 ou mais recente |
Verificar se o app Android está instalado
Seu site pode verificar se o app Android está instalado.
Android: Chrome 80 ou mais recente
Informar o app Android sobre seu site
Primeiro, você precisa atualizar o app Android para definir a relação entre o site e o aplicativo Android usando o sistema Digital Asset Links. Isso garante que apenas seu site possa verificar se o app Android está instalado.
No AndroidManifest.xml
do app Android, adicione uma entrada
asset_statements
:
<manifest>
<application>
…
<meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
…
</application>
</manifest>
Em seguida, no strings.xml
, adicione a declaração de recurso a seguir, 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, publique o app Android atualizado na Play Store.
Informar seu site sobre o app Android
Em seguida, informe o site sobre o app Android
adicionando um manifesto do 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 serplay
id
é o ID do aplicativo do Google Play para seu app Android.
{
"related_applications": [{
"platform": "play",
"id": "com.android.chrome",
}]
}
Verificar se o app está instalado
Por fim, chame navigator.getInstalledRelatedApps()
para verificar se o
app Android está instalado.
Teste a demonstração
Verificar se o app Windows (UWP) está instalado
O site pode verificar se o app do Windows (criado com o UWP) está instalado.
Windows: Chrome 85 ou mais recente, Edge 85 ou mais recente
Informar o app do Windows sobre seu site
Você vai precisar atualizar o app do Windows para definir a relação entre o site e o aplicativo do Windows usando gerenciadores de URI. Isso garante que apenas o site possa verificar se o app para 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 site for
example.com
, adicione a seguinte entrada no 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 seu
atributo <Package>
.
Em seguida, crie um arquivo JSON (sem a extensão .json
) chamado
windows-app-web-link
e informe 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 "Embalagem" no designer de
manifesto do app.
[{
"packageFamilyName": "MyApp_9jmtgj1pbbz6e",
"paths": [ "*" ]
}]
Consulte Ativar apps para sites usando gerenciadores de URI do app para mais detalhes sobre a configuração de gerenciadores de URI.
Informar o site sobre o app para Windows
Em seguida, informe o site sobre o app para Windows
adicionando um manifesto de app da Web à página. O manifesto precisa
incluir a propriedade related_applications
, uma matriz que fornece os detalhes
do app, incluindo platform
e id
.
platform
precisa serwindows
id
é o nome da família de pacotes do app, anexado pelo valorId
<Application>
no arquivoPackage.appxmanifest
.
{
"related_applications": [{
"platform": "windows",
"id": "MyApp_9jmtgj1pbbz6e!App",
}]
}
Verificar se o app está instalado
Por fim, chame navigator.getInstalledRelatedApps()
para verificar se o
app para Windows está instalado.
Verificar se o Progressive Web App 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 dentro do escopo do seu PWA, conforme definido pelo escopo no manifesto do app da Web.
Android: Chrome 84 ou mais recente
Informar o PWA sobre ele mesmo
Informe o PWA sobre ele mesmo adicionando uma entrada related_applications
ao
manifesto do app da Web.
platform
precisa serwebapp
url
é o caminho completo para o manifesto de app da Web do seu PWA
{
…
"scope": "/",
"start_url": "/",
"related_applications": [{
"platform": "webapp",
"url": "https://example.com/manifest.json",
}],
…
}
Verificar se o PWA está instalado
Por fim, chame navigator.getInstalledRelatedApps()
no
escopo da sua PWA para verificar se ela está instalada. Se
getInstalledRelatedApps()
for chamado fora do escopo da sua PWA, ele
vai retornar falso. Consulte a próxima seção para obter detalhes.
Confira a demonstração
Verificar se o Progressive Web App está instalado (fora do escopo)
O 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 exibida por
/landing/
pode verificar se o PWA exibido por /pwa/
está instalado ou se
a página de destino é veiculada por www.example.com
e o PWA é exibido por
app.example.com
.
Android: Chrome 84 ou mais recente
Informar o PWA sobre seu site
Primeiro, você vai precisar adicionar Digital Asset Links ao servidor em que o PWA é veiculado. Isso ajudará a definir a relação entre o site e o PWA e garante que apenas ele possa 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 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, adicione um manifesto de app da Web à página para informar seu site sobre o app PWA. O manifesto precisa
incluir a propriedade related_applications
, uma matriz que fornece os detalhes
sobre sua PWA, incluindo platform
e url
.
platform
precisa serwebapp
url
é o caminho completo para o manifesto de 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 navigator.getInstalledRelatedApps()
para verificar se o
PWA está instalado.
Confira a demonstração
Como chamar getInstallRelatedApps()
Chamar navigator.getInstalledRelatedApps()
retorna uma promessa que
se resolve com uma matriz dos apps instalados no dispositivo do usuário.
const relatedApps = await navigator.getInstalledRelatedApps();
relatedApps.forEach((app) => {
console.log(app.id, app.platform, app.url);
});
Para evitar que os sites testem um conjunto excessivamente amplo dos próprios apps, apenas os três primeiros apps declarados no manifesto do app da Web serão considerados.
Como a maioria das outras APIs da Web, a API getInstalledRelatedApps()
só está disponível quando é servida pelo HTTPS.
Ainda tem dúvidas?
Ainda tem dúvidas? Verifique a tag getInstalledRelatedApps
no StackOverflow
para saber se alguém já fez perguntas semelhantes. Caso contrário, faça sua pergunta e use 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 das especificações?
- Registre um bug em https://new.crbug.com. Inclua o máximo
de detalhes possível, forneça instruções simples para reproduzir o bug e
insira
Mobile>WebAPKs
na caixa Components. O Glitch é ótimo para compartilhar reprosões rápidas e fáceis.
Mostrar suporte à 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 conversa sobre a WCG (em inglês).
- Envie um tweet para @ChromiumDev usando a hashtag
#getInstalledRelatedApps
e nos informe onde e como você está usando.
Links úteis
- Explicação pública da API
getInstalledRelatedApps()
- Especificação do rascunho
- Rastreamento de bug
- Entrada de ChromeStatus.com
- Componente do Blink:
Mobile>WebAPKs
Obrigado
Agradecemos especialmente 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.