Resolver problemas com links de apps

Este guia descreve problemas comuns e como resolvê-los. Também é possível usar as ferramentas de solução de problemas na página de links diretos do Play Console ou no assistente de links do app do Android Studio. Para mais informações, consulte Ferramentas para desenvolvedores de links de apps.

  • Problema: você clica em um link que deveria abrir o app, mas ele é aberto em um navegador da Web ou mostra uma caixa de diálogo de desambiguação.
  • Solução:
    • Verifique o arquivo assetlinks.json: confira se o arquivo é um JSON válido, acessível em https://<your-domain>/.well-known/assetlinks.json e veiculado por HTTPS sem redirecionamentos. Use um validador on-line.
    • Verifique a impressão digital SHA-256: confira se o sha256_cert_fingerprints em assetlinks.json corresponde exatamente à impressão digital da chave de assinatura da versão do app (use a do Play Console se você usa a Assinatura de Apps do Google Play). A assinatura precisa estar em letras maiúsculas.
    • Verifique autoVerify: confira se o <intent-filter> no seu AndroidManifest.xml inclui android:autoVerify="true".
    • Verifique se há redirecionamentos do lado do servidor: redirecionamentos de http para https ou de um domínio que não seja www para www podem causar falhas na verificação.
    • Forçar a nova verificação: execute os comandos adb no guia Testar links de apps para receber um novo resultado de verificação.
    • Diagnosticar a resolução de links (Android 17 ou mais recente): execute adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>" para inspecionar quais apps candidatos, filtros de intent de manifesto e regras de links dinâmicos de apps correspondem ao URL. Para mais detalhes, consulte Diagnosticar a resolução de links com a flag debug-link.

As regras dinâmicas no Android 15 ou mais recente não estão sendo atualizadas

  • Problema: você atualizou as regras no arquivo assetlinks.json, mas os novos links não estão sendo processados pelo app.
  • Solução:
    • Forçar a nova verificação: a maneira mais confiável de testar mudanças é forçar uma nova busca com adb shell pm verify-app-links --re-verify <your-package-name>.
    • Verifique se há erros de digitação: revise cuidadosamente os correspondentes de padrão nas regras para identificar erros de sintaxe.
    • Verifique as regras de filtro do manifesto: revise as regras de filtro de intent no manifesto do app para garantir que o caminho do link não esteja sendo filtrado. Se o link estiver sendo filtrado, torne o filtro de intent no manifesto do app menos restritivo.
    • Diagnosticar regras de correspondência (Android 17 ou mais recente): execute adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>" para inspecionar quais regras foram avaliadas e determinar se uma regra de exclusão (allow = 1) impediu a abertura do app. Consulte Diagnosticar a resolução de links com a flag debug-link.

Corrigir erros comuns de implementação

Se não for possível verificar os Links do App Android, confira os seguintes erros comuns. Nesta seção, usamos example.com como um marcador de posição de nome de domínio. Ao realizar essas verificações, substitua example.com pelo nome de domínio real do servidor.

Configuração incorreta do filtro de intent
Verifique se você incluiu um URL que não pertence ao seu app em um elemento <intent-filter>.
Configuração incorreta do servidor

Verifique a configuração JSON do servidor e se o valor de SHA está correto.

Além disso, verifique se example.com. (com o ponto final) exibe o mesmo conteúdo que example.com.

Redirecionamentos do lado do servidor

O sistema não vai verificar nenhum Link do App Android para seu app se você configurar um redirecionamento como este:

  • http://example.com a https://example.com
  • example.com a www.example.com

Esse comportamento protege a segurança do app.

Robustez do servidor

Verifique se os apps cliente podem se conectar ao servidor.

Links não verificáveis

Para fins de teste, é possível adicionar links não verificáveis intencionalmente. No Android 11 e versões anteriores, esses links fazem com que o sistema não verifique todos os Links do App Android do seu app.

Assinatura incorreta em assetlinks.json

Verifique se a assinatura está correta e corresponde à usada para assinar o app. Os erros comuns incluem:

  • Assinar o app com um certificado de depuração e ter apenas a assinatura de lançamento em assetlinks.json.
  • Ter uma assinatura em letras minúsculas em assetlinks.json. A assinatura precisa estar em letras maiúsculas.
  • Se você estiver usando a Assinatura de apps do Google Play, verifique se está usando a assinatura que o Google usa para assinar cada uma das suas versões. Para verificar esses detalhes, incluindo um snippet JSON completo, siga as instruções sobre como declarar associações de sites.

Capturar um relatório do bug

Para problemas complexos que são difíceis de reproduzir, capture um relatório do bug e analise-o. Isso pode fornecer insights valiosos sobre o processo de verificação e quaisquer erros no nível do sistema.