Pubblicare sul Play Store, passo passo

Le istruzioni complete per mettere un gioco JumPHP su Google Play e mantenercelo: cosa bisogna costruire, cosa bisogna conservare, cosa verificare su un telefono, e la Play Console da cima a fondo. Vale per le due specie di app:

Il tuo Claude conosce questa guida (è nell'AGENTS.md del tuo progetto, e in docs/google-play.md): chiedigli «metti il mio gioco su Google Play». Si occupa della parte tecnica; le scelte e gli invii restano tuoi (vedi la fine).

0. Prima di iniziare

• Un account sviluppatore Google Play: play.google.com/console, 25 $ una tantum, con una verifica dell'identità. È il tuo account: sei tu ad accettare le condizioni di Google.
• Un nuovo account personale deve fare un test chiuso con almeno 12 tester per 14 giorni prima di poter pubblicare in produzione. Avvialo presto.
• Il nome del pacchetto (io.github.<il tuo account github>.<mon_jeu>): l'identificatore dell'app su Google Play. Non cambia mai più. Il comando lo chiede la prima volta.
• La licenza dell'SDK Android: sei tu ad accettarla, nel tuo terminale, la prima volta (l'SDK, ~1 GB, va in ~/.jumphp). Il tuo Claude ti chiede di avviare tu stesso il comando (! bin/jumphp twa …).
• Un'informativa sulla privacy a un indirizzo pubblico: Google la richiede anche se il gioco non raccoglie nulla. Basta una pagina breve: il gioco non raccoglie, non invia e non condivide alcun dato personale; niente account, niente pubblicità, niente tracciamento; impostazioni e salvataggi restano sul dispositivo; un indirizzo di contatto. Mettila nel sito del gioco, games/mon-jeu/site/privacy.html: viene servita a https://play.jumphp.net/mon-jeu/privacy.html (oppure il PRIVACY.md del tuo repository pubblico). Apri l'indirizzo una volta prima di darlo a Google: un errore 404 blocca la revisione.

1. Le chiavi: salvale per prima cosa

La prima costruzione crea la tua chiave di caricamento: ~/.jumphp/android/keys/<pacchetto>.keystore e la sua password in <pacchetto>.env.

• Mai in git, né in una nota o in un messaggio. Salva i due file altrove (gestore di password, disco cifrato). Senza di essi, una nuova costruzione crea un'altra chiave e Google Play rifiuta l'aggiornamento.
• Con la firma dell'app da parte di Google Play (predefinita), Google conserva la propria chiave, quella che firma l'app sui telefoni. La tua dimostra solo che i caricamenti vengono da te; se la perdi, Google può sostituirla (Configurazione > Firma dell'app), ma ci vogliono giorni.
• Ci sono quindi due impronte SHA-256: quella della tua chiave (mostrata dal comando) e quella della chiave di Google (Play Console > Configurazione > Firma dell'app, dopo il primo caricamento).

2. Costruire l'app

bin/jumphp twa mon-jeu --url https://jumphp.net/mon-jeu     # l'app web
bin/jumphp android mon-jeu                                   # oppure l'app nativa

• Ogni costruzione fa numero di versione + 1 (Google Play rifiuta un numero già caricato; un tentativo fallito consuma un numero, non è grave).
• Fai subito il commit del file di versione: games/mon-jeu/android/twa-manifest.json (app web) oppure games/mon-jeu/android/app.json (app nativa). Mai dist/.
• Il nome sotto l'icona: pwa: {short_name: …} in game.yaml (12 caratteri si vedono per intero). L'icona: assets/icon.png.

3. Solo app web: il sito fa da garante dell'app

Android apre la pagina a schermo intero solo se il sito dichiara l'app: il nome del pacchetto e le due impronte (la tua e quella di Google). Con la sola tua, l'app installata dal tuo .apk funziona, ma quella installata da Google Play si apre con una barra degli indirizzi (o una scelta «Apri con»).

Nello Studio, pagina del gioco, sezione App Android (oppure il tuo Claude: update_project). Il sito le pubblica in https://jumphp.net/.well-known/assetlinks.json. Sul tuo server: https://tuo-dominio/.well-known/assetlinks.json.

4. Provarla su un vero telefono

Con il debug USB attivato e adb:

adb install -r games/mon-jeu/dist/android/mon-jeu-<version>.apk
adb shell pm get-app-links <paquet>          # app web : « jumphp.net: verified »
adb exec-out screencap -p > capture.png      # guarda: il gioco deve esserci

• L'app deve aprirsi sulla schermata del titolo del gioco.
• Un .apk firmato con la tua chiave non si installa sopra la stessa app arrivata da Google Play (INSTALL_FAILED_UPDATE_INCOMPATIBLE): disinstalla prima (i salvataggi dell'app vanno persi).
• L'app web si apre e si chiude subito, con una scelta «Apri con»: il telefono ha due Chrome, in genere a causa di uno spazio clone / secondo spazio / doppia app (Xiaomi, Samsung…). L'app di JumPHP richiede il Chrome del profilo principale, il che risolve il caso per i giocatori; sul tuo telefono di prova, eliminare lo spazio clone cancella tutte le app che contiene.
• Che il gioco si apra in Chrome non dimostra che l'app funzioni: prova l'app.

5. La Play Console, la prima volta

L'elenco «Configura la tua app» della dashboard (X su 11) mostra cosa resta da fare; «Invia per revisione» resta disattivato finché manca qualcosa.

1. Creare l'app: nome, lingua predefinita, Gioco, Gratuita, le dichiarazioni.
2. Contenuti dell'app (Criteri > Contenuti dell'app), ogni dichiarazione:
   • Informativa sulla privacy: l'indirizzo pubblico del passo 0;
   • Annunci: nessuna pubblicità (JumPHP non ne aggiunge);
   • Accesso all'app: tutto è accessibile senza accesso particolare (niente account);
   • Pubblico di destinazione: le età per cui il gioco è fatto. Scegliere età sotto i 13 anni fa entrare l'app nel programma Famiglie (regole più severe, meno visibilità): fallo solo se il gioco è davvero fatto per i bambini;
   • Classificazione dei contenuti (questionario IARC): categoria Gioco; rispondi onestamente per il tuo gioco (violenza da cartone animato o fantastica, sangue, paura, gioco d'azzardo, contenuti creati dai giocatori, scambi tra giocatori, posizione, acquisti);
   • Sicurezza dei dati: un gioco JumPHP senza account né statistiche non raccoglie né condivide alcun dato (i salvataggi restano sul dispositivo; se il tuo gioco chiama un servizio web, dichiaralo);
   • ID pubblicitario: non utilizzato;
   • App governative, funzionalità finanziarie, salute: no.
3. Impostazioni dello store (Crescita > Presenza sullo store > Impostazioni): la categoria (Arcade, Azione, Rompicapo…) e l'indirizzo e-mail di contatto. Entrambi sono obbligatori: senza di essi, «Your app cannot be published yet». L'indirizzo è pubblico.
4. Scheda principale dello store: titolo (30 caratteri), descrizione breve (80), descrizione completa (4000), icona 512 × 512 PNG (bin/jumphp build la crea: dist/web/icon-512.png), immagine 1024 × 500, almeno 2 screenshot per telefono (bin/jumphp shot mon-jeu, ingranditi di un fattore intero, oppure presi da un telefono). Tieni le immagini nel gioco (games/mon-jeu/store/) per rifarle nelle versioni successive.
5. Test: Test e release > Test > Test interni (oppure Test chiuso per i 12 tester di un nuovo account) > Crea release > l'.aab > note di rilascio > Salva > Rivedi > Avvia il lancio. I tester: un elenco di indirizzi; ciascuno apre il link di invito connesso con quell'account Google e tocca Diventa tester.
6. App web: dopo questo primo caricamento, aggiungi l'impronta della chiave di Google (passo 3), installa dal link di test e verifica lo schermo intero.
7. Produzione: Produzione > Paesi / regioni > Aggiungi, seleziona, Salva (una release senza paesi viene rifiutata), poi Crea release > l'.aab > note > Avanti > Salva.
8. Panoramica della pubblicazione > Invia per revisione, conferma. La revisione richiede da qualche ora a 7 giorni; la console e l'e-mail dell'account dicono quando l'app è online.

6. Le note di rilascio

Un blocco per lingua, i tag su una riga a sé:

<fr-FR>
Première version.
</fr-FR>
<en-US>
First release.
</en-US>

7. Le versioni successive

• App web: il gioco si aggiorna con il sito (fai il push, viene pubblicato): nessuna nuova app. Una nuova app solo se cambiano il nome, l'icona, i colori, l'indirizzo di partenza o il pacchetto: bin/jumphp twa mon-jeu.
• App nativa: ogni modifica del gioco è una nuova app: bin/jumphp android mon-jeu --version-name 1.1.

Poi: fai il commit del file di versione, prova l'.apk su un telefono, poi Play Console > la stessa traccia > Crea release > il nuovo .aab > note > Invia per revisione. Le dichiarazioni restano valide, a meno che il gioco non cambi ciò che descrivono (gioco online, acquisti, dati): aggiornale prima.

8. Le trappole incontrate

Cosa il tuo Claude non fa senza di te

• accettare la licenza dell'SDK Android, le condizioni di Google, o rispondere al questionario di classificazione senza dirti le sue risposte;
• scegliere il pubblico di destinazione (dire che il gioco è «per bambini» cambia le regole e la visibilità);
• inviare in produzione senza il tuo consenso per quell'invio;
• eliminare uno spazio clone o disinstallare un'app dal tuo telefono (si perdono dei dati);
• mettere le chiavi, le password o dist/ in git.