O método getInstalledRelatedApps()
permite que o site verifique se
o app iOS/Android/computador ou o PWA está instalado no dispositivo de um usuário.
O que é a API getInstallRelatedApps()?
O getInstalledRelatedApps()
permite que sua página
verifique se seu app para dispositivos móveis ou para 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, se houver.
Por exemplo, se o app já estiver instalado:
- Redirecionamento do 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.
Para usar a API getInstalledRelatedApps()
, você precisa fornecer informações ao app sobre
o site e depois sobre ele. Depois de definir a
relação entre os dois, verifique se o app está instalado.
Tipos de apps com suporte que você pode verificar
Tipo de aplicativo | Marcável de |
---|---|
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 Web Progressivo instalado no mesmo escopo ou em escopo diferente. |
Somente Android Chrome 84 ou mais recente |
Conferir 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, atualize o app Android para definir a relação entre o site e o app Android usando o sistema Digital Asset Links. Isso garante que somente 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, em strings.xml
, adicione a seguinte instrução de recurso, atualizando site
com
seu domínio. Inclua os caracteres de escape.
<string name="asset_statements">
[{
\"relation\": [\"delegate_permission/common.handle_all_urls\"],
\"target\": {
\"namespace\": \"web\",
\"site\": \"https://example.com\"
}
}]
</string>
Quando terminar, publique seu app Android atualizado na Play Store.
Informe 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 seu app, incluindo platform
e id
.
platform
precisa serplay
id
é o ID do seu app Android no Google Play.
{
"related_applications": [{
"platform": "play",
"id": "com.android.chrome",
}]
}
Conferir 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 usando UWP) está instalado.
Windows: Chrome 85 ou versão mais recente, Edge 85 ou mais recente
Informar o app do Windows sobre seu site
É necessário 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 seu site possa verificar se o app do Windows está instalado.
Adicione o registro da extensão Windows.appUriHandler
ao arquivo de manifesto
Package.appxmanifest
do app. 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 de arquivo .json
) chamado
windows-app-web-link
e forneça o nome da família de pacotes do seu app. Coloque
esse arquivo na raiz do servidor ou no diretório /.well-known/
. Esse
nome pode ser encontrado na seção "Empacotamento" do designer de manifesto
do app.
[{
"packageFamilyName": "MyApp_9jmtgj1pbbz6e",
"paths": [ "*" ]
}]
Consulte Ativar apps para sites que usam gerenciadores de URI de app para saber todos os detalhes sobre a configuração de gerenciadores de URI.
Informe 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 serwindows
id
é o nome da família de pacotes do seu app, anexado pelo valor<Application>
Id
no arquivoPackage.appxmanifest
.
{
"related_applications": [{
"platform": "windows",
"id": "MyApp_9jmtgj1pbbz6e!App",
}]
}
Conferir 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 fez a solicitação precisa estar no mesmo domínio e dentro do escopo do PWA, conforme definido pelo escopo no manifesto do app da Web.
Android: Chrome 84 ou mais recente
Conte ao seu PWA sobre ele mesmo
Informe ao PWA sobre ele mesmo adicionando uma entrada related_applications
no
manifesto do app da Web.
platform
precisa serwebapp
url
é o caminho completo para o manifesto do app da Web do 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()
de dentro do
escopo do PWA para verificar se ele está instalado. Se
getInstalledRelatedApps()
for chamado fora do escopo do PWA, ele vai retornar
falso. Consulte a próxima seção para obter detalhes.
Teste 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 dele. Por exemplo, uma página de destino veiculada por
/landing/
pode verificar se o PWA exibido por /pwa/
está instalado ou se a
página de destino é veiculada a partir de www.example.com
e o PWA é veiculado de
app.example.com
.
Android: Chrome 84 ou mais recente
Informe ao PWA sobre seu site
Primeiro, você precisará adicionar Digital Asset Links ao servidor em que o PWA é veiculado. Isso ajuda a definir a relação entre seu site e o PWA e garante que somente 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 reside, 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"
}
}
]
Informe seu site sobre o PWA
Em seguida, informe o site sobre o app de 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 o PWA, incluindo platform
e url
.
platform
precisa serwebapp
url
é o caminho completo para o manifesto do app da Web do 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.
Teste a demonstração
Como chamar getInstallRelatedApps()
Chamar navigator.getInstalledRelatedApps()
retorna uma promessa que
é resolvida 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, somente os três primeiros apps declarados no manifesto do app da Web serão considerados.
Como a maioria das outras APIs da Web avançadas, a API getInstalledRelatedApps()
só está disponível quando exibida por HTTPS.
Ainda tem dúvidas?
Ainda tem dúvidas? Verifique a tag getInstalledRelatedApps
no StackOverflow para ver se alguém já teve dúvidas semelhantes. Caso contrário, faça sua pergunta lá e não se esqueça de marcá-la com a tag progressive-web-apps
. Nossa equipe monitora frequentemente
essa tag 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 simples para reproduzir o bug e
insira
Mobile>WebAPKs
na caixa Componentes. O Glitch funciona muito bem para compartilhar repetições rápidas e fáceis.
Mostrar suporte à API
Você planeja usar a API getInstalledRelatedApps()
? Seu suporte
público ajuda a equipe do Chrome a priorizar recursos e mostra aos outros
fornecedores de navegadores como é importante oferecer suporte a eles.
- Conte como você planeja usar a API na conversa do Discourse da WICG.
- Envie um tweet para @ChromiumDev com a hashtag
#getInstalledRelatedApps
e conte para a gente onde e como você está usando a hashtag.
Links úteis
- Explicação pública sobre a API
getInstalledRelatedApps()
(link em inglês) - Rascunho das especificações
- Rastreamento de bugs
- Entrada ChromeStatus.com
- Componente Blink:
Mobile>WebAPKs
Até logo!
Agradecimentos especiais a Sunggook Chue da Microsoft por ajudar com os detalhes para testar apps do Windows e a Rayan Kanso pela ajuda com os detalhes do Chrome.