SHA-256 no assetlinks.json após o Play App Signing: tire a barra do navegador do TWA

Este guia trata de uma única correção: a associação entre o seu site e a versão que o Google Play entrega. Ele não cobre a criação do TWA em si nem a revisão do app pelo Play, que têm guias próprios com links abaixo. Cada página do Google citada aqui foi verificada em 16 de outubro de 2026, e as fontes estão listadas no final.

Por que a barra do navegador aparece só na instalação pelo Play

O Chrome verifica um TWA comparando o certificado que assinou o app instalado com as impressões digitais que o seu site publica. Quando essa verificação falha, o guia de início rápido de TWA do Chrome diz que o navegador passa a exibir o seu site como uma Custom Tab. Esse fallback é a barra de endereço que você vê.

Com o Play App Signing, geralmente existem dois certificados. Você assina o pacote que envia com a sua chave de upload, e o Google assina os APKs que entrega com a chave de assinatura do app. A página Android concepts for web developers do Chrome diz que a impressão digital da chave de assinatura do app é a que corresponde ao seu app quando ele é baixado da Play Store. Um arquivo que lista apenas o seu certificado local, portanto, passa na sua mesa e falha em todo celular que instalou pelo Play.

As duas chaves nem sempre são diferentes. A documentação de assinatura de apps do Android descreve configurações em que a mesma chave serve como chave de assinatura do app e como chave de upload. Por isso, a correção é comparar os certificados reais, não presumir qual deles você tem.

Encontre o SHA-256 da assinatura do app no Play Console

A própria documentação do Google dá atualmente dois nomes para o mesmo lugar. Os dois começam em Protected with Play, no menu à esquerda do seu app.

Guias mais antigos, incluindo algumas páginas do Google, ainda dizem Release > Setup > App signing ou Setup > App integrity. Se você só encontrar esses nomes, está procurando a mesma página com um nome antigo.

Leia a impressão digital de uma chave que você mesmo guarda

Para a sua chave de upload ou uma chave de debug, o keytool do Java imprime o mesmo formato. Substitua o arquivo do keystore e o alias pelos seus e copie a linha marcada como SHA256:

keytool -list -v -keystore my-upload-key.jks -alias upload

Se você gerencia muitos apps, a Google Play Developer API também pode retornar o hash do certificado dos APKs que o Play gerou (o campo certificateSha256Hash da lista de APKs gerados). Para uma correção pontual, copiar do Play Console é mais simples.

Escreva e sirva um assetlinks.json correto

O arquivo é um array JSON de declarações. Para um TWA, a relação é delegate_permission/common.handle_all_urls, e o alvo é o seu app Android: o namespace android_app, o seu application ID exato e um array de impressões digitais SHA-256. Um arquivo mínimo fica assim:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

Substitua com.example.twa pelo seu application ID e cada placeholder por um SHA-256 completo, separado por dois-pontos. Apague a segunda entrada se você só precisa que as instalações pelo Play sejam verificadas. Somente JSON estrito: sem comentários, sem vírgulas sobrando no final, sem valores SHA-1.

Como o Google exige que o arquivo seja servido

• Local exato. https://your-domain/.well-known/assetlinks.json, com o ponto em .well-known. example.com e www.example.com são origens diferentes; publique o arquivo em cada uma que o seu app abre. Uma cópia em um subdiretório, como /app/.well-known/, não conta.
• Um HTTP 200 direto. A documentação do Digital Asset Links do Google diz: “Any response from the server besides HTTP 200 is treated as an error, and will result in an empty statement list.” (qualquer resposta do servidor diferente de HTTP 200 é tratada como erro e resulta em uma lista de declarações vazia).
• Sem redirecionamentos. Respostas 301 e 302 não são seguidas. Isso inclui um salto de http para https e um salto do domínio sem www para o www.
• HTTPS com uma cadeia de certificados válida, e o cabeçalho Content-Type: application/json. Uma página de login ou uma página de erro em HTML que responde com 200 não é um arquivo válido.

Confira a resposta ao vivo em qualquer terminal. A primeira linha de status precisa ser 200 e o tipo de conteúdo precisa ser JSON, sem nenhum 3xx antes:

curl -sI https://example.com/.well-known/assetlinks.json

Mais de uma impressão digital, mais de um app

O guia de associação de sites do Android diz sobre o array de impressões digitais: “This field supports multiple fingerprints, which can be used to support different versions of your app, such as debug and production builds.” (o campo aceita várias impressões digitais, para diferentes versões do app, como as de debug e de produção). Adicione uma impressão digital de upload ou de debug apenas para as versões em que você realmente quer que esse site confie. Uma versão com um application ID diferente, como um pacote de debug separado, precisa de uma declaração própria no array.

Se você criou o TWA com Bubblewrap ou PWABuilder

Em um projeto Bubblewrap existente, adicione a impressão digital do Play e gere o arquivo de novo:

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

Gerar o arquivo não é publicá-lo: envie o novo assetlinks.json para o seu site e confira com o curl. O bubblewrap validate avalia o seu PWA em relação a critérios de qualidade; ele não verifica a associação de assinatura, então passar nele não prova nada sobre a impressão digital. As instruções atuais do PWABuilder dizem o mesmo sobre a assinatura, “Once you've uploaded your .aab file, Google Play re-signs your app” (depois que você envia o arquivo .aab, o Google Play assina o app novamente), e mandam adicionar a impressão digital do Play ao arquivo gerado. Corrigir a impressão digital é uma mudança no seu site, não no binário do app.

Verifique a associação e teste a instalação pelo Play

Há quatro camadas envolvidas: o arquivo no seu site, a Digital Asset Links API do Google, a verificação de links do próprio Android e o navegador que abre o seu TWA. Passar em uma camada não prova a seguinte, então confira na ordem e termine no dispositivo.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

O App Links Assistant do Android Studio (Tools > App Links Assistant) verifica a associação de Android App Links e o seu manifesto. Ele é útil para isso, mas não diz se o seu TWA abre em tela cheia; só o teste no dispositivo diz.

Avançado: o estado de verificação do próprio Android

No Android 12 e versões mais recentes, o guia de verificação do Android documenta estes comandos para App Links. Substitua o pacote, rode os dois primeiros, espere alguns minutos e leia o estado:

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified descreve a verificação de domínio do Android, não se o seu TWA abre sem a interface do navegador. Códigos de 1024 ou mais são erros específicos do verificador, não um diagnóstico de SHA-256 errado. Para o TWA em si, use o log do Chrome mostrado acima.

A impressão digital confere, mas a barra continua

Uma barra visível não prova que o SHA-256 está errado. Quando a verificação acima retorna linked: true e a barra continua lá, analise estas causas.

Quanto tempo até um arquivo corrigido fazer efeito

O Google não publica um tempo de espera único para TWAs, porque há vários caches envolvidos e cada um tem as próprias regras:

• O seu servidor ou CDN pode ainda servir o arquivo antigo. Limpe o cache e confirme a resposta ao vivo com o curl.
• A Digital Asset Links API informa por quanto tempo cada resposta continua válida no campo maxAge.
• O Android App Links tem um tempo próprio. O guia de verificação do Android diz que, no Android 15 e versões mais recentes, as mudanças podem levar até sete dias para chegar a todos os dispositivos, e que, no Android 14 e versões anteriores, o arquivo normalmente é lido quando o app é instalado ou atualizado.
• O navegador pode manter o próprio estado. Um desenvolvedor relatou ter resolvido depois de limpar os dados do Chrome.

Então limpe o cache, confirme o arquivo ao vivo e reinstale pelo Google Play. Em um dispositivo de teste, uma instalação nova ou a limpeza dos dados do navegador podem descartar um estado em cache; isso é uma etapa de diagnóstico, não algo para pedir a todos os usuários. Não planeje com base em um número fixo de horas.

Rejeição, revisão e teste fechado

Um assetlinks.json ausente ou errado não está documentado como causa de rejeição por si só. O que a documentação descreve é o fallback para uma Custom Tab com a interface do navegador. A revisão é uma questão separada: a política de funcionalidade do Google Play diz “We don’t allow apps that crash, force close, freeze, or otherwise function abnormally,” (não permitimos apps que travam, fecham à força, congelam ou funcionam de forma anormal), e isso vale seja qual for o status da sua associação. Uma impressão digital correta resolve a barra; ela não resolve a revisão. Se você recebeu uma rejeição, comece pela política citada no e-mail.

Alguns artigos mais antigos dizem que o Chrome faz um TWA travar quando ele falha nas verificações de qualidade. O Chromium removeu esse código QualityEnforcer em 4 de maio de 2023, então trate esse conselho como histórico, não como uma descrição dos navegadores atuais.

Se você recebeu uma rejeição, trabalhe a partir do motivo indicado no aviso: a rejeição por Broken Functionality explica passo a passo o aviso de funcionalidade mais comum. Não reconstrua o seu TWA como WebView só por causa de uma barra do navegador. Se o seu app saiu de um construtor de IA, publicar um app de vibe coding no Google Play cobre o caminho completo do projeto até o Play.

Perguntas frequentes

Conclusão

Os nomes dos menus do Play Console são o fato que muda mais rápido nesta página. Se os caminhos acima não corresponderem mais ao seu Console, procure Play app signing em Protected with Play ou pesquise "app signing" no Console.