KappS Base de conhecimento · Blog

Android App Links em 2026: tutorial de verificação passo a passo

Blog Tutorial

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:host não aceita curingas. Alcance subdomínios com filtros separados e restrinja o intervalo com android:path, android:pathPrefix ou android:pathPattern para que o app não reivindique URLs que não consegue renderizar.
  • http não é verificável. Apenas https participa da verificação automática. Manter um filtro http só 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 301 ou 302 na 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.

  1. 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.
  2. Redirecionamento ou tipo de conteúdo errado. curl -sI mostra um 3xx, text/html ou uma página de erro em cache de CDN. Corrija o cabeçalho, limpe o cache e verifique novamente.
  3. 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.
  4. 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-links novamente.
  5. 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 … all redefine 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.json com 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.

Clique para escolher um arquivo · clique com o botão direito → Colar, ou pressione Ctrl/⌘+V para colar uma captura de tela

Você também pode arrastar um arquivo para esta caixa.

Respondemos ao e-mail que você fornecer. Seus dados ficam com KappS.

✔ Enviado

Recebemos sua mensagem e responderemos em até 24 horas.


← Voltar para editar