Android App Links em 2026: tutorial de verificação passo a passo
Um Android App Link é o único mecanismo de link direto que o Google trata como prova de propriedade: seu app declara um host HTTPS que está disposto a tratar, publica uma declaração Digital Asset Links nesse host, e o Android verifica se os dois correspondem antes de abrir seu app em vez do navegador. Dois artefatos decidem o resultado — um arquivo /.well-known/assetlinks.json que você controla e a impressão digital SHA-256 de assinatura dentro dele — e a maioria das falhas vem de um deles estar ligeiramente errado, não de algo exótico.
Este tutorial segue a ordem em que o trabalho realmente acontece: declarar o intent filter autoVerify, publicar a lista de declarações assetlinks.json, escolher a impressão digital correta quando o Play App Signing reassina seu build, instalar e ler o estado de verificação, diagnosticar as falhas comuns em produção, projetar um fallback que não engane os usuários e manter a verificação de links do app ativa durante rotações de chave e mudanças de domínio. A regra por trás de tudo isso: a verificação é uma promessa de que o domínio e o app têm o mesmo dono, então a única forma legítima de passar é realmente ser dono dos dois.
1. O que um link verificado prova e o que ele não prova
Três ideias se confundem, e separá-las evita a maioria das decisões de design ruins.
- Um link direto é qualquer intent que abre uma tela dentro do seu app. Ele pode vir de um esquema personalizado como
myapp://product/42, que qualquer app no dispositivo pode registrar, então um app malicioso pode reivindicar o mesmo esquema e receber a URL no seu lugar. - An App Link is an HTTPS URL —
https://shop.example.com/product/42— that Android has verified you are entitled to handle, because that host publishes a statement naming your package and your signing certificate. The user sees a normal web URL, the browser can always open it, and only one app can win the verification. - Fallback web é a mesma URL aberta no navegador quando o app não está instalado. Uma estratégia de links bem construída faz as três peças concordarem, para que a URL resolva para o conteúdo desejado com ou sem o app presente.
O que a verificação não faz: não prova que o app está instalado, não concede nenhum direito sobre o conteúdo do domínio e não substitui a autenticação. Se uma tela exibe dados da conta, a checagem do token no servidor continua sendo o que os protege. A verificação só responde "este app pode abrir links para este host" — nada mais.
Uma consequência prática: mantenha esquemas personalizados no máximo para transferências internas e nunca dependa deles para redefinição de senha ou redirecionamentos de pagamento, porque a propriedade do esquema não é exigível.
2. Etapa 1 — declarar os filtros de intent autoVerify no manifesto
Comece em AndroidManifest.xml. O filtro deve ser um filtro https com android:autoVerify="true", e precisa da ação VIEW mais as categorias DEFAULT e BROWSABLE:
<intent-filter android:autoVerify="true"> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="https" android:host="shop.example.com" /> </intent-filter>
Detalhes que decidem se isso funciona na prática:
- Um filtro por host. A verificação é avaliada por host, e a orientação do Google é um
<intent-filter>separado para cada domínio. Agrupar cinco hosts em um único filtro faz um host problemático contaminar os demais. - Os hosts são literais. O
android:hostnão aceita curingas. Alcance subdomínios com filtros separados e restrinja o intervalo comandroid:path,android:pathPrefixouandroid:pathPatternpara que o app não reivindique URLs que não consegue renderizar. httpnão é verificável. Apenashttpsparticipa da verificação automática. Manter um filtrohttpsó gera solicitações duplicadas no seletor.- Declare apenas o que você roteia. Um filtro que corresponde ao host inteiro enquanto o app trata três caminhos envia todas as outras URLs para uma tela em branco — e esse comportamento aparece nas avaliações da loja muito antes de aparecer no seu painel de falhas.
Se o seu app usa tanto um domínio de marketing quanto um domínio de app, decida de forma consciente qual deles é o canônico para compartilhamento. Cada host que você adiciona é um arquivo para publicar e um certificado para manter sincronizado.
3. Passo 2 — publique o /.well-known/assetlinks.json
A lista de extratos fica em exatamente um caminho, via HTTPS, sem nenhum redirecionamento na frente:
https://shop.example.com/.well-known/assetlinks.json
O corpo é um array JSON de declarações. Para um app comum que trata todas as URLs do host, uma declaração basta:
[{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.shop", "sha256_cert_fingerprints": [ "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5" ] } }]
Vários pacotes, ou um pacote com múltiplos certificados, simplesmente adicionam mais declarações ao mesmo array. Os detalhes de exibição importam tanto quanto o conteúdo:
- Tipo de conteúdo. Sirva como
application/json. Algumas versões do Android e algumas configurações de edge de CDN são rígidas quanto a isso. - Sem redirecionamentos. Um
301ou302na frente do arquivo faz a busca falhar, e a falha é silenciosa no dispositivo. Este é o erro de hospedagem mais comum — uma regra global de "forçar HTTPS" ou "remover barra final" quebra isso silenciosamente. - Sem autenticação, sem barreira anti-bot. O verificador do Google busca o arquivo anonimamente. Um desafio de WAF ou um bloqueio geográfico retorna uma página de erro HTML onde se espera JSON.
- JSON válido, sem comentários. Uma vírgula final ou um comentário
//perdido invalida o arquivo inteiro e todas as declarações nele contidas.
Before you debug anything on the device, fetch the file the way the verifier would: curl -sI https://shop.example.com/.well-known/assetlinks.json should show 200 and no Location header, and the body should parse. Google publishes a statement list generator and tester that will validate the structure and the fingerprint format for you — use it before shipping.
4. Etapa 3 — usar a impressão digital que o dispositivo realmente vê
É aqui que a maioria das verificações falha, e o motivo é o Play App Signing. Ao aderir, o Google fica com a chave de assinatura do app e reassina cada artefato que entrega. O certificado instalado no dispositivo do usuário é, portanto, o certificado de assinatura do app — não a chave de upload que você tem na máquina de build.
- Instalações pelo Play exigem o certificado SHA-256 da chave de assinatura do app, encontrado no Play Console em Integridade do app → Assinatura do app (o bloco "Certificado da chave de assinatura do app").
- Builds locais e instalados por sideload são assinados com sua chave de upload ou de depuração e precisam dessa impressão digital — leia-a com
keytool -list -v -keystore <keystore>e copie a linha SHA-256. - Envie os dois. Listar o certificado de assinatura do app e o certificado de upload no mesmo array
sha256_cert_fingerprintsé normal e esperado; isso permite que as instalações da Play verifiquem enquanto seus builds de QA continuam funcionando.
Mais duas armadilhas na mesma área. Se você usa um keystore de depuração, a impressão digital dele é específica da máquina que o gerou — serve para seus próprios testes, é inútil no arquivo publicado. E se você algum dia usar a atualização de chave do Play, o certificado muda: a lista de declarações precisa ser atualizada antes de o upgrade ser lançado, ou os links quebram para novas instalações enquanto as antigas continuam funcionando.
Copie as impressões digitais do console em vez de digitá-las novamente. Um único par de dígitos hexadecimais trocado gera um arquivo que é JSON válido, é servido com 200 e ainda assim falha na verificação sem nenhuma mensagem de erro em lugar algum.
5. Etapa 4 — instalar e ler o estado real de verificação
A verificação é tentada quando o app é instalado e novamente após atualizações, então você precisa do app instalado a partir do canal que está testando — uma instalação de teste interno do Play se comporta de forma diferente de um adb install de uma build assinada para upload.
No Android 12 e superior, consulte a plataforma diretamente:
adb shell pm get-app-links com.example.shop
Você recebe um relatório por domínio: o domínio, se o usuário o aprovou e o estado da verificação — verified quando a lista de declarações correspondeu, denied ou legacy_failure quando não correspondeu. Em versões mais antigas, o equivalente é um dump dos registros de verificação de domínio:
adb shell dumpsys package d
Se um host aparecer como negado e você acabou de corrigir o arquivo, force uma nova tentativa em vez de reinstalar às cegas:
adb shell pm set-app-links --package com.example.shop --domain shop.example.com all
Depois, teste o fluxo que o usuário executa. Um link digitado no navegador, um link tocado em um cliente de e-mail e um link dentro de outro app nem sempre resolvem da mesma forma, e só um deles pode passar pelo seletor. Verifique também a tela Abrir por padrão do app nas configurações do sistema: o usuário pode desativar um link verificado, e seu código deve sobreviver a isso sem quebrar.
6. Etapa 5 — diagnostique as falhas que você realmente vai encontrar
Quase toda falha em produção se encaixa em um de cinco grupos. Verifique-os nesta ordem; cada um leva segundos.
- Fingerprint errado. O arquivo é interpretado, o host está correto, e o certificado na declaração é a chave de upload enquanto o dispositivo tem a build assinada pelo Play. Compare o fingerprint do console caractere por caractere com o do arquivo.
- Redirecionamento ou tipo de conteúdo errado.
curl -sImostra um3xx,text/htmlou uma página de erro em cache de CDN. Corrija o cabeçalho, limpe o cache e verifique novamente. - Nome do pacote ou host incompatível. Um ID de aplicação alterado para uma build white-label, ou um filtro que ainda lista um host de staging que não serve mais o arquivo. Faça um grep do manifesto para cada host e confirme que cada um tem uma declaração ativa.
- A verificação nunca foi executada. A instalação ocorreu offline, ou o app nunca foi aberto desde a instalação. Abra o app uma vez com conectividade e execute
pm get-app-linksnovamente. - Substituição pelo usuário. O domínio foi desativado nas configurações — às vezes meses antes, às vezes por uma ferramenta de migração de fabricante.
pm set-app-links … allredefine isso para testes; para usuários reais, a solução é orientação, não imposição.
Mantenha um teste rápido de uma linha no seu checklist de lançamento: busque o arquivo, faça o parse e confirme que a fingerprint é igual à que o console mostra no momento. Uma mudança de domínio ou uma atualização de chave que pula essa verificação é exatamente como uma configuração de link funcional morre em silêncio.
7. Passo 6 — crie um fallback que diga a verdade
Os App Links tornam o app o manipulador preferido; não o tornam o único. Projete primeiro o lado web, porque é o caso que sempre existe.
- A URL precisa funcionar sem o app. Um link de compartilhamento que só funciona quando instalado é um link quebrado, e isso também quebra os rastreadores que o indexam.
- Detecte, depois ofereça — não sequestre. Um banner pequeno com "Abrir no app" e um link para a loja converte melhor do que um redirecionamento automático que prende usuários que querem deliberadamente o navegador.
- Mantenha o caminho do link direto idêntico ao caminho da web. Se o app renderiza
/product/42, a página web no mesmo caminho deve mostrar o mesmo produto; a tabela de mapeamento que você evita construir é justamente a que vai quebrar no próximo trimestre. - Trate o caso de instalação pendente. O link direto diferido — em que um novo usuário instala e cai no item compartilhado — precisa de um mecanismo no servidor ou de install-referrer. O Firebase Dynamic Links, ferramenta que a maioria das equipes usava para isso, foi descontinuado, então planeje a Install Referrer API ou um equivalente próprio em vez de assumir um serviço hospedado.
E resista à tentação de tornar a verificação invisível. Se o app não consegue renderizar uma URL, deixar o navegador cuidar disso é um resultado melhor do que uma tela de "não encontrado" no app, e preserva o SEO do domínio.
8. Manter a verificação ativa entre versões e domínios
A verificação não é uma configuração única. É um acordo permanente entre três partes móveis: o manifesto, o arquivo publicado e o certificado com o qual a loja realmente assina. Qualquer coisa que toque em uma delas é um item do checklist de lançamento.
- Atualização de chave ou nova assinatura. Atualize o
assetlinks.jsoncom o novo certificado e publique-o antes do lançamento gradual, depois mantenha o antigo listado até que a versão anterior seja totalmente desativada. - Mudança de domínio. Publique os arquivos no novo host primeiro e faça a alteração do manifesto depois. Um filtro que aponta para um host sem arquivo tira os links do ar imediatamente.
- Domínios de marca e regionais. Cada host é uma declaração própria e um arquivo próprio. Automatize a implantação para que um novo domínio regional não possa ser publicado sem um.
- Verificações de propriedade. O arquivo é uma declaração pública de que você controla o domínio. Publique-o apenas para domínios que a sua organização possui e opera, e nunca hospede a declaração de outra parte em nome dela — é exatamente esse o padrão que a detecção de abuso procura, e isso coloca em risco tanto o domínio quanto a conta do app.
Guarde os filtros do manifesto, o modelo JSON publicado e as impressões digitais atuais em um só lugar, gerados a partir de uma única fonte de verdade. Quando são três edições manuais separadas, eles divergem em até dois ciclos de lançamento.
9. Onde o KappS se encaixa
Atuamos no lado operacional do lançamento: mantendo contas, versões e registros da loja em um estado que resiste à revisão da plataforma — preparando e enviando material em conformidade, nunca burlando uma verificação. Na verificação de links, isso geralmente significa:
- Higiene de lançamento. Certificados e IDs de aplicação consistentes entre o console, a build e a lista de declarações publicada, para que a impressão digital que o dispositivo vê seja a que você documentou.
- Prontidão da conta. Verificação de desenvolvedor, perfil de pagamento e dados fiscais alinhados à entidade legal por trás da conta, para que um lançamento não fique travado por uma revisão não relacionada.
- Revisão de domínio e hospedagem. Verificar se o caminho well-known realmente entrega JSON sem redirecionamentos, sem desafio de WAF e sem página de erro em cache na frente.
O que não fazemos: publicar declarações para domínios que o cliente não possui, falsificar uma fingerprint ou ajudar um app a reivindicar um host ao qual não tem direito. A verificação existe justamente para proteger os usuários disso, e não é um serviço que oferecemos.
Fontes (documentação oficial): Android Developers — Verify Android App Links; Add Android App Links; especificação Digital Asset Links; Play Console Help — App signing key certificate and key upgrade; Android Developers — Adb shell pm commands for app links.
Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.
Recebemos sua mensagem e responderemos em até 24 horas.
← Voltar para editar