TWA (Trusted Web Activity): o que é, os dois problemas no teste fechado e o que fazer

Seu app foi gerado a partir de um site, passou 14 dias em teste fechado com 12 testadores e o Google respondeu que "os testadores não interagiram o suficiente". Ou abriu com uma barra de endereço no topo. Nos dois casos a causa costuma ser a mesma: o app é um TWA. Este guia explica o que isso significa, como confirmar e quais são as duas saídas.

1. O que é um TWA e quem gera um sem saber

Trusted Web Activity é uma forma de empacotar um site como app Android. O APK quase não tem código próprio: ele abre o Chrome do aparelho em modo de tela cheia, sem a interface do navegador, apontando para o seu site. Para o usuário parece um app. Para o sistema, é o Chrome rodando em outro processo.

A maioria das pessoas que tem um TWA não escolheu isso. É o formato padrão de várias ferramentas:

• PWABuilder (o "Google Play package" que ele baixa é um TWA)
• Bubblewrap, a CLI oficial do Google para o mesmo fim
• Plataformas no-code e de IA que exportam Android a partir do site: Base44, Lovable, Bubble, Manus e parte dos fluxos do FlutterFlow quando o projeto é web

Se o seu app veio de uma dessas, a chance de ser TWA é alta. Mais adiante mostramos como confirmar.

2. Dois problemas diferentes, que costumam ser confundidos

Quase toda discussão sobre TWA trava porque mistura dois itens independentes. Corrigir o primeiro não resolve o segundo.

O que é fato documentado

• TWA: "o conteúdo é renderizado pelo navegador do usuário", em tela cheia. developer.android.com
• WebView: exibe páginas "como parte do layout da sua activity". developer.android.com
• Capacitor no Android usa o WebView do sistema. capacitorjs.com
• As métricas de engajamento do Play Console registram se o app foi aberto em primeiro plano. Android Developers Blog

O que o Google não publica

O Google não documenta como calcula o engajamento dos testadores no teste fechado. Por isso ninguém consegue provar que TWA "sempre reprova", e nós não afirmamos isso. A hipótese que explica o que vemos em campo é que o uso dentro do Chrome não é atribuído ao pacote do app, mas ela é uma hipótese.

Você pode conferir no seu próprio aparelho qual activity está em primeiro plano enquanto usa o app:

adb shell dumpsys activity activities | grep ResumedActivity

3. Os dois sintomas

Barra de endereço no topo do app

O TWA só esconde a interface do Chrome quando o site prova que confia no app. Essa prova é o arquivo /.well-known/assetlinks.json, hospedado no seu domínio, com a impressão digital (SHA-256) da chave que assina o APK. Se o arquivo não existe, está em outro lugar, ou tem a impressão digital errada, o Chrome mostra a barra de endereço. É o sinal visual de que o vínculo está quebrado. A correção está na seção 7.

"Os testadores não interagiram o suficiente com o seu app"

É a mensagem que o Google devolve no pedido de acesso à produção quando considera o uso dos testadores insuficiente. O critério exato não é público. Em apps TWA nós já vimos essa resposta depois de ciclos completos, com 12 testadores e 14 dias. A barra de URL é outro item: corrigir o arquivo tira a barra, mas não muda onde o conteúdo é renderizado.

4. Os 6 problemas técnicos que reprovam um TWA

Além da medição de engajamento, há pontos técnicos que aparecem repetidamente nas análises que fazemos antes de iniciar um ciclo. Todos têm base na documentação do Google.

5. Como saber se o seu app é TWA

1. Pela origem. Se o pacote veio do PWABuilder, Bubblewrap, Base44, Lovable ou Bubble, assuma que é.
2. Pelo nome do pacote. Padrões como app.lovable.*, com.base44.*, space.manus.* são de exportadores no-code.
3. Pelo comportamento. Abra o app e puxe a tela de apps recentes. Se aparecer como aba do Chrome, ou se em algum momento surgir uma barra de endereço, é TWA.
4. Pelo arquivo. Abra o APK ou AAB em qualquer analisador e procure por TrustedWebActivity, androidbrowserhelper, androidx.browser.trusted, CustomTabsIntent ou LauncherActivity. Qualquer um deles confirma.

Cordova e Capacitor não aparecem nessa lista de propósito. Os dois embutem um WebView dentro do processo do app (no Cordova você encontra org/apache/cordova/engine/SystemWebView; no Capacitor, com.getcapacitor.BridgeActivity). O conteúdo é exibido dentro do próprio app.

6. As duas saídas

Como é a migração para Capacitor

O back-end não muda. O front-end passa a ser empacotado dentro do app e exibido em um WebView, no processo do próprio app. O caminho oficial do Capacitor é copiar o build do site para a pasta webDir:

npm i @capacitor/core @capacitor/cli @capacitor/android
npx cap init "Nome do App" com.seudominio.app --web-dir dist

npm run build          # gera o build estático do seu front-end
npx cap add android
npx cap sync

# usar o MESMO applicationId do TWA atual
# assinar com a MESMA chave de upload · versionCode maior
# publicar na mesma faixa de teste fechado

• SPA ou site estático (React, Vue, Angular, export do Next): é o caso simples. As chamadas de API continuam indo para o seu servidor.
• Site com renderização no servidor: exige separar o front-end ou avaliar a opção server.url, que carrega uma URL externa no WebView. A documentação do Capacitor avisa que ela é voltada a live reload e não a produção, então trate como exceção. capacitorjs.com/docs/config
• Ícone e splash: @capacitor/assets gera tudo a partir de um PNG de 1024 px.
• Com o mesmo applicationId e a mesma chave de upload, os testadores recebem como atualização pelo mesmo link de teste fechado.
• Essa alteração é feita pelo seu time de desenvolvimento.

7. Se for só a barra de URL: corrigir o assetlinks.json

Se o seu app já é nativo, Capacitor ou Cordova e mesmo assim tem uma tela que abre no Chrome com barra, ou se você decidiu manter o TWA, o vínculo precisa estar certo. O erro mais comum em 2026 é ter só uma impressão digital no arquivo.

Com o Play App Signing ligado (padrão para apps novos), existem duas chaves: a de upload, que assina o que você envia, e a de assinatura do app, que o Google usa para reassinar o que vai para os aparelhos. O Chrome no aparelho vê a segunda. Se o arquivo só tem a primeira, o vínculo falha.

[
  { "relation": ["delegate_permission/common.handle_all_urls"],
    "target": { "namespace": "android_app",
      "package_name": "com.seudominio.app",
      "sha256_cert_fingerprints": ["AA:BB:...:CHAVE-DO-APP"] } },
  { "relation": ["delegate_permission/common.handle_all_urls"],
    "target": { "namespace": "android_app",
      "package_name": "com.seudominio.app",
      "sha256_cert_fingerprints": ["11:22:...:CHAVE-DE-UPLOAD"] } }
]

Depois, valide pela API oficial, que responde se o Google enxerga o vínculo:

https://digitalassetlinks.googleapis.com/v1/statements:list
  ?source.web.site=https://SEU-DOMINIO
  &relation=delegate_permission/common.handle_all_urls

O vínculo foi corrigido e voltou a quebrar

Acontece mais do que parece. O arquivo é corrigido, a barra some, e semanas depois ela volta. As duas causas que mais vemos:

• Uma nova publicação do site apagou a pasta. O build do front-end substitui tudo e a pasta .well-known não faz parte dele. Coloque o arquivo dentro do projeto (em geral na pasta public/) para ele ser publicado junto, sempre.
• O site responde a página inicial para qualquer endereço. É o comportamento padrão de aplicações de página única. Sem o arquivo, o endereço do assetlinks devolve o HTML do site com status 200. Para quem olha rápido parece que está no ar; para o Google, o conteúdo é inválido.

Confira o tipo do conteúdo, não só se o endereço abre:

curl -I https://SEU-DOMINIO/.well-known/assetlinks.json
# certo:  content-type: application/json
# errado: content-type: text/html   (o site devolveu a página inicial)

Nesse caso a API oficial responde com o erro abaixo, e o app volta a abrir com a barra do navegador em toda instalação nova:

"errorCode": ["ERROR_CODE_WRONG_CONTENT_TYPE"]
expected 'Content-Type: application/json' but found text/html

A documentação do Android descreve o efeito: quando a verificação falha, o navegador exibe o site como uma Custom Tab, com a interface do navegador no topo da página. developer.android.com. Vale conferir o endereço depois de cada publicação do site e antes de pedir acesso à produção.

8. O que o Google conta, o que ele responde e onde ver

Boa parte da confusão em torno de um teste fechado recusado vem de misturar coisas diferentes. Estes são os pontos que mais aparecem nas conversas com desenvolvedores, cada um com o que a documentação do Google diz.

Testador é a conta Google inscrita, não a conta criada dentro do app

O requisito do Google é ter "no mínimo, 12 testadores inscritos por pelo menos 14 dias consecutivos". Inscrito é a conta Google que aceitou participar da faixa de teste. O número de cadastros que aparece no painel administrativo do seu app é outra coisa: depende de o app exigir cadastro e de qual acesso foi entregue para o teste. Se você forneceu um único login de teste, vai ver uma única conta em uso no seu painel, mesmo com todos os testadores inscritos e usando o app. support.google.com

Se quiser que cada testador use uma conta própria dentro do app, envie uma lista de logins ou deixe o cadastro aberto e avise antes do ciclo começar.

A resposta "mais testes" não diz o motivo

Quando o Google não libera a produção, a orientação oficial é "continue executando o teste fechado". A mesma página lista os motivos possíveis: "menos de 12 testadores que aceitaram participar ou engajamento insuficiente durante o período de teste". Ele não informa qual dos dois se aplica ao seu app. Se os 12 testadores estavam inscritos pelos 14 dias, o ponto a investigar é o engajamento, e é aí que a estrutura do app entra (seção 2). support.google.com

Recusa por política é outro fluxo

É comum ouvir que "se o problema fosse no app, o Google nem deixaria testar de novo". Não é assim que a documentação descreve. A análise de política acontece quando você envia o app ou uma atualização para revisão. Quando ela reprova, o status é "Atualização rejeitada" e a orientação é "Corrija o problema e reenvie o app ou envie uma contestação". O pedido de acesso à produção é uma etapa separada, que olha para o teste. support.google.com

Onde aparece o feedback dos testadores

O feedback de quem está na faixa de teste é privado: não aparece na página pública do app. No Play Console ele fica em Monitorar e melhorar → Notas e avaliações → Feedback de teste. A documentação avisa: "Você precisa resumir o feedback do teste ao solicitar o acesso de produção". Abra essa tela antes de preencher o formulário. support.google.com

"TWA é oficial do Google, então não pode ser o problema"

TWA é uma tecnologia oficial e legítima, e ninguém aqui diz o contrário. A questão não é legitimidade, é onde o conteúdo roda. A documentação do Chrome diz que as páginas de um TWA são renderizadas pelo navegador do usuário e que o app hospedeiro não tem acesso direto ao conteúdo web. Capacitor é outra estrutura, não um ajuste do TWA: não se "injeta" um no outro. Migrar é empacotar o mesmo front-end em um projeto Capacitor, com o mesmo applicationId e a mesma chave de upload, e enviar como atualização (seção 6). developer.chrome.com

Fontes oficiais desta seção

• Requisitos de teste de apps para novas contas pessoais de desenvolvedor (Ajuda do Play Console): os 12 testadores por 14 dias, o pedido de acesso à produção, os motivos para "mais testes" e o feedback de teste.
• Publicar o app: status de atualização e de revisão (Ajuda do Play Console): "Em revisão", "Atualização rejeitada" e o que fazer.
• Trusted Web Activity: visão geral (developer.chrome.com): onde o conteúdo é renderizado.
• Guia de integração de Trusted Web Activity (developer.android.com): a verificação do vínculo e o que acontece quando ela falha.
• Digital Asset Links (developers.google.com): o formato do arquivo e a API de validação.
• WebView (developer.android.com): páginas da Web como parte do layout da activity.

Perguntas frequentes

Referências: Play Console e engajamento (Android Developers Blog) · Trusted Web Activities (developer.android.com) · Custom Tabs Engagement Signals (developer.chrome.com) · Digital Asset Links (developers.google.com) · Requisitos de teste fechado (support.google.com) · Status de publicação e revisão (support.google.com) · Visão geral de TWA (developer.chrome.com)

← Voltar para o blog