Publicando na Play Store, passo a passo

O guia completo para colocar um jogo JumPHP no Google Play e mantê-lo lá: o que é preciso gerar, o que é preciso guardar, o que é preciso conferir em um celular e o Play Console de ponta a ponta. Vale para os dois tipos de aplicativo:

O seu Claude conhece este guia (ele está no AGENTS.md do seu projeto e em docs/google-play.md): peça a ele “coloque o meu jogo no Google Play”. Ele cuida da parte técnica; as escolhas e os envios continuam sendo seus (veja o final).

0. Antes de começar

• Uma conta de desenvolvedor do Google Play: play.google.com/console, US$ 25 uma única vez, com verificação de identidade. É a sua conta: é você quem aceita os termos do Google.
• Uma conta pessoal nova precisa fazer um teste fechado com pelo menos 12 testadores por 14 dias antes de poder publicar em produção. Comece cedo.
• O nome do pacote (io.github.<sua conta do github>.<meu_jogo>): o identificador do aplicativo no Google Play. Ele nunca mais muda. O comando o pergunta na primeira vez.
• A licença do SDK do Android: é você quem a aceita, no seu terminal, na primeira vez (o SDK, ~1 GB, vai para ~/.jumphp). O seu Claude pede que você mesmo execute o comando (! bin/jumphp twa …).
• Uma política de privacidade em um endereço público: o Google a exige mesmo que o jogo não colete nada. Uma página curta basta: o jogo não coleta, não envia e não compartilha nenhum dado pessoal; sem conta, sem anúncios, sem rastreamento; as configurações e os saves ficam no aparelho; um endereço de contato. Coloque-a no site do jogo, games/meu-jogo/site/privacy.html: ela é servida em https://play.jumphp.net/meu-jogo/privacy.html (ou o PRIVACY.md do seu repositório público). Abra o endereço uma vez antes de entregá-lo ao Google: um erro 404 bloqueia a análise.

1. As chaves: faça backup primeiro

A primeira geração cria a sua chave de envio: ~/.jumphp/android/keys/<pacote>.keystore e a senha dela em <pacote>.env.

• Nunca no git, nem em uma nota ou mensagem. Faça backup dos dois arquivos em outro lugar (gerenciador de senhas, disco criptografado). Sem eles, uma nova geração cria outra chave e o Google Play recusa a atualização.
• Com a assinatura de apps pelo Google Play (o padrão), o Google guarda a própria chave, a que assina o aplicativo nos celulares. A sua apenas prova que os envios vêm de você; se for perdida, o Google pode substituí-la (Configuração > Assinatura de apps), mas isso leva dias.
• Há, portanto, duas impressões digitais SHA-256: a da sua chave (exibida pelo comando) e a da chave do Google (Play Console > Configuração > Assinatura de apps, depois do primeiro envio).

2. Gerar o aplicativo

bin/jumphp twa meu-jogo --url https://jumphp.net/meu-jogo     # o aplicativo web
bin/jumphp android meu-jogo                                    # ou o aplicativo nativo

• Cada geração faz número de versão + 1 (o Google Play recusa um número já enviado; uma tentativa fracassada consome um número, não tem problema).
• Faça o commit imediatamente do arquivo de versão: games/meu-jogo/android/twa-manifest.json (aplicativo web) ou games/meu-jogo/android/app.json (aplicativo nativo). Nunca o dist/.
• O nome sob o ícone: pwa: {short_name: …} no game.yaml (12 caracteres aparecem por inteiro). O ícone: assets/icon.png.

3. Somente aplicativo web: o site se responsabiliza pelo aplicativo

O Android só abre a página em tela cheia se o site declarar o aplicativo: o nome do pacote e as duas impressões digitais (a sua e a do Google). Só com a sua, o aplicativo instalado a partir do seu .apk funciona, mas o instalado a partir do Google Play abre com uma barra de endereço (ou uma escolha “Abrir com”).

No Studio, página do jogo, seção Aplicativo Android (ou o seu Claude: update_project). O site as publica em https://jumphp.net/.well-known/assetlinks.json. No seu próprio servidor: https://seu-dominio/.well-known/assetlinks.json.

4. Testá-lo em um celular de verdade

Com a depuração USB ativada e o adb:

adb install -r games/meu-jogo/dist/android/meu-jogo-<versão>.apk
adb shell pm get-app-links <pacote>          # aplicativo web: “jumphp.net: verified”
adb exec-out screencap -p > captura.png      # olhe: o jogo precisa estar lá

• O aplicativo deve abrir na tela de título do jogo.
• Um .apk assinado com a sua chave não se instala por cima do mesmo aplicativo vindo do Google Play (INSTALL_FAILED_UPDATE_INCOMPATIBLE): desinstale antes (os saves do aplicativo são perdidos).
• O aplicativo web abre e fecha logo em seguida, com uma escolha “Abrir com”: o celular tem dois Chrome, em geral por causa de um espaço clone / segundo espaço / app duplo (Xiaomi, Samsung…). O aplicativo do JumPHP pede o Chrome do perfil principal, o que resolve o caso para os jogadores; no seu celular de teste, excluir o espaço clone apaga todos os aplicativos que ele contém.
• O fato de o jogo abrir no Chrome não prova que o aplicativo funciona: teste o aplicativo.

5. O Play Console, na primeira vez

A lista “Configurar o seu app” do painel (X de 11) mostra o que falta fazer; “Enviar para análise” fica desativado enquanto faltar alguma coisa.

1. Criar o app: nome, idioma padrão, Jogo, Sem custo, as declarações.
2. Conteúdo do app (Política > Conteúdo do app), cada declaração:
   • Política de privacidade: o endereço público da etapa 0;
   • Anúncios: sem anúncios (o JumPHP não adiciona nenhum);
   • Acesso ao app: tudo é acessível sem nenhum acesso especial (sem conta);
   • Público-alvo: as idades para as quais o jogo foi feito. Escolher idades abaixo de 13 anos coloca o aplicativo no programa Em família (regras mais rígidas, menos visibilidade): só faça isso se o jogo for realmente feito para crianças;
   • Classificação de conteúdo (questionário IARC): categoria Jogo; responda com honestidade para o seu jogo (violência de desenho animado ou fantasiosa, sangue, medo, jogos de apostas, conteúdo criado pelos jogadores, interações entre jogadores, localização, compras);
   • Segurança dos dados: um jogo JumPHP sem conta nem estatísticas não coleta nem compartilha nenhum dado (os saves ficam no aparelho; se o seu jogo chama um serviço web, declare);
   • ID de publicidade: não usado;
   • Apps governamentais, recursos financeiros, saúde: não.
3. Configurações da Play Store (Crescer > Presença na loja > Configurações): a categoria (Arcade, Ação, Quebra-cabeça…) e o e-mail de contato. Os dois são obrigatórios: sem eles, “Your app cannot be published yet”. O e-mail é público.
4. Ficha principal: título (30 caracteres), descrição curta (80), descrição completa (4000), ícone 512 × 512 PNG (bin/jumphp build o gera: dist/web/icon-512.png), imagem de 1024 × 500, pelo menos 2 capturas de celular (bin/jumphp shot meu-jogo, ampliadas por um fator inteiro, ou tiradas em um celular). Guarde as imagens no jogo (games/meu-jogo/store/) para refazê-las nas versões seguintes.
5. Testes: Testar e lançar > Testes > Testes internos (ou Teste fechado para os 12 testadores de uma conta nova) > Criar nova versão > o .aab > notas da versão > Salvar > Revisar > Iniciar lançamento. Os testadores: uma lista de endereços; cada um abre o link de convite logado com aquela conta do Google e toca em Tornar-se testador.
6. Aplicativo web: depois desse primeiro envio, adicione a impressão digital da chave do Google (etapa 3), instale pelo link de teste e confira a tela cheia.
7. Produção: Produção > Países / regiões > Adicionar, selecione, Salvar (uma versão sem países é recusada), depois Criar nova versão > o .aab > notas > Avançar > Salvar.
8. Visão geral da publicação > Enviar para análise, confirme. A análise leva de algumas horas a 7 dias; o console e o e-mail da conta avisam quando o aplicativo estiver no ar.

6. As notas da versão

Um bloco por idioma, com as tags em uma linha própria:

<pt-BR>
Primeira versão.
</pt-BR>
<en-US>
First release.
</en-US>

7. As versões seguintes

• Aplicativo web: o jogo se atualiza com o site (você faz o push e ele é publicado): sem novo aplicativo. Um novo aplicativo só se o nome, o ícone, as cores, o endereço inicial ou o pacote mudarem: bin/jumphp twa meu-jogo.
• Aplicativo nativo: cada mudança do jogo é um novo aplicativo: bin/jumphp android meu-jogo --version-name 1.1.

Depois: faça o commit do arquivo de versão, teste o .apk em um celular e então Play Console > a mesma faixa > Criar nova versão > o novo .aab > notas > Enviar para análise. As declarações continuam valendo, a menos que o jogo mude o que elas descrevem (jogo online, compras, dados): atualize-as antes.

8. As armadilhas encontradas

O que o seu Claude não faz sem você

• aceitar a licença do SDK do Android, os termos do Google ou responder ao questionário de classificação sem lhe dizer as respostas dele;
• escolher o público-alvo (dizer que o jogo é “para crianças” muda as regras e a visibilidade);
• enviar para produção sem o seu aval para esse envio específico;
• excluir um espaço clone ou desinstalar um aplicativo do seu celular (dados são perdidos);
• colocar as chaves, as senhas ou o dist/ no git.