Apps, CLI apps, graphic apps and IDE plugins are made in apps/<id>; bin/jumphp, the tools, the workflows, the IDE and the docs find a project in games/ or apps/. New projects get config/project.yaml (under project:); the engine, bin/jumphp, the tools and the IDE still read config/game.yaml (under game:). JUMPHP_APP is read before JUMPHP_GAME. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01X3cUrphmz1MoDiCrUbAHuo
12 KiB
Publishing a game on Google Play, step by step
How to put a JumPHP game on the Play Store and keep it there: what to build, what to keep, what to check on a phone, and the Play Console from the first upload to the review. It holds for both kinds of Android app:
| The web app (Trusted Web Activity) | The native app | |
|---|---|---|
| Command | bin/jumphp twa <game> --url https://<the game online> |
bin/jumphp android <game> |
| What it is | the game's page in Chrome, full screen | PHP + SDL + the game inside the app, offline |
| The game updates | with the site, at once (no new app) | with a new version of the app |
| Out | games/<game>/dist/android/ |
games/<game>/dist/android-native/ |
| Details | android.md | android-native.md |
Both make an .aab (for Google Play) and an .apk (for a phone), signed with the same kind of upload key: with the
same package and key, the native app can later replace the web app as a new version.
0. Before anything
- A Google Play developer account: play.google.com/console, 25 $ once, an identity check. It is the user's own: an agent never creates it, never accepts Google's terms in it, never answers its questionnaires without telling the user what it answered.
- A new personal account must run a closed test with at least 12 testers for 14 days before it may publish in production. Start it early.
- The package name (
io.github.<github user>.<game id with _>, e.g.io.github.me.space_rocks): the app's id on Google Play. It never changes. The command asks it the first time. - The Android SDK license: downloaded the first time (~1 GB in
~/.jumphp/android-sdk) once the user accepts Google's license, in their own terminal (! bin/jumphp twa ...in Claude Code). Never accept it for them. - A privacy policy at a public address (Google asks for it even when the game collects nothing). A short page
is enough: the game collects, sends and shares no personal data, no account, no ads, no tracking; settings and
saves stay on the device (deleting the app or the site's data erases them); a contact address. Put it in the
game's site,
games/<game>/site/privacy.html(served athttps://<domain>/privacy.htmlbybin/jumphp deploy, athttps://play.jumphp.net/<game>/privacy.htmlon the playground), or link thePRIVACY.mdof the public repository. Open the address once before giving it to Google: a 404 there blocks the review.
1. The keys: back them up first
The first build makes the upload key: ~/.jumphp/android/keys/<package>.keystore and its password in
<package>.env.
- Never in git, never in a note, an issue or a chat. Back up both files somewhere else (a password manager, an encrypted disk). Without them, a new build makes a new key and Google Play refuses the update.
- With Play App Signing (the default), Google keeps its own key, the one that signs the app on the phones. The upload key only proves the uploads are yours; if it is lost, Google can replace it (Setup > App signing), but it takes days.
- Two SHA-256 fingerprints exist, both needed by the web app (§3): the upload key's (printed by the build) and Google's app signing key's (Play Console > Setup > App signing, after the first upload).
2. Build
bin/jumphp twa my-game --url https://jumphp.net/my-game # the web app
bin/jumphp android my-game # or the native app
- Each build is version code + 1 (Google Play refuses a code it already has; a failed build still uses a
number, which is harmless).
--same-version(web app) rebuilds without changing it. - Commit the version file at once:
games/<game>/android/twa-manifest.json(web app) orgames/<game>/android/app.json(native app). Never commitdist/. - The name under the icon: project.yaml
pwa: {short_name: ...}(12 characters show whole on most phones). The icon:assets/icon.png.
3. The web app only: the site vouches for the app
Android opens the page full screen only if the site lists the app: https://<host>/.well-known/assetlinks.json
with the package and both fingerprints (upload key + Google's). With only the upload key's, the version
installed from your .apk works and the one installed from Google Play opens with an address bar (or a "open
with" chooser).
- on the JumPHP playground: Studio > the game > Android app, or MCP
update_project(android_package,android_fingerprints); it serveshttps://jumphp.net/.well-known/assetlinks.json; - on one's own server:
dist/android/assetlinks.jsonintosite/.well-known/(bin/jumphp deploysends it).
Check it: curl -s https://<host>/.well-known/assetlinks.json shows the package and the two fingerprints.
4. Try it on a real phone
adb devices -l # USB debugging on, the computer allowed
adb install -r games/<game>/dist/android/<game>-<version>.apk # (dist/android-native/ for the native app)
adb shell pm get-app-links <package> # web app: "<host>: verified"
adb logcat -c; adb shell am start -n <package>/.LauncherActivity # web app (the native app: from its icon)
adb logcat -d -v time | grep -E "TwaLauncher|ResolverActivity|Abort background|AndroidRuntime"
adb exec-out screencap -p > var/debug/phone.png # look at it; var/ is not in git
- The app must open on the game's title screen. Look at the screenshot.
- An
.apksigned with the upload key does not install over the same app installed from Google Play (INSTALL_FAILED_UPDATE_INCOMPATIBLE: two different signing keys). Uninstall first, after asking (it erases the app's saves). - The web app opens then closes at once, with an "Open with" chooser in the log (
ResolverActivity, thenAbort background activity starts): the phone has two Chrome, usually because of a dual space / clone space / second space (Xiaomi XSpace, Samsung Dual Messenger, user 999 inadb shell pm list users). JumPHP's web app asks for the Chrome of the main profile (createTwaLauncher()withcom.android.chrome, added bytools/twa.sh), which fixes it for players. On a test phone, removing the clone space (adb shell pm remove-user <id>) erases every app in it: only with the user's explicit yes. - The site and Chrome alone working (the game's address opens in Chrome) does not prove the app works: test the app.
5. The Play Console, the first time
The console asks the same things for every app; the dashboard's "Set up your app" list (n of 11) shows what is left, and Send for review stays greyed out until every item is done.
- Create app: the name, the default language, Game, Free, the declarations (policies, US export laws).
- App content (Policy > App content), every declaration:
- Privacy policy: the public address of §0;
- Ads: no ads (JumPHP adds none);
- App access: all functionality available without special access (no account);
- Target audience and content: the ages the game is made for. Choosing ages under 13 puts the app in the Families programme (stricter rules, less visibility): do not tick young ages unless the game is really made for children and the user wants it; ask the user, never decide it;
- Content rating (IARC questionnaire): category Game; answer for the game honestly (cartoon or fantasy violence, blood, fear, gambling, user-generated content, chat between players, location, purchases). A JumPHP game online with the relay has players interacting: say so if the game has online play;
- Data safety: a JumPHP game without accounts or analytics collects and shares no data (saves stay on the device; the HTTP requests a game makes are its own: check the game's code);
- Advertising ID: not used;
- Government, financial features, health: no.
- Store settings (Grow > Store presence > Store settings): category (Arcade, Action, Puzzle...) and the contact e-mail. Both are required: without them "Your app cannot be published yet". The e-mail is public: use the one the user gives, never guess.
- Main store listing: title (30 characters), short description (80), full description (4000), icon 512 × 512
PNG (
bin/jumphp buildmakesdist/web/icon-512.png), feature graphic 1024 × 500, at least 2 phone screenshots (bin/jumphp shot <game>, scaled up by a whole factor, oradb exec-out screencap). Keep the pictures in the game (e.g.games/<game>/store/) to redo them for the next versions. - Testing: Test and release > Testing > Internal testing (or Closed testing for the 12 testers of a new account)
Create release > upload the
.aab> release notes > Save > Review > Start rollout. Testers: an e-mail list; each tester opens the invitation link signed in with that Google account and taps Become a tester. - Web app: after this first upload, copy Google's app signing fingerprint (Setup > App signing) into the site's assetlinks (§3), then install from the test link and check it opens full screen.
- Production: Production > Countries / regions > Add, select them, Save (a release without countries is
refused), then Create release > the
.aab> release notes > Next > Save. - Publishing overview > Send for review, confirm. The review takes from a few hours to 7 days; the console and the account's e-mail say when the app is live.
Sending to production, accepting terms, answering the content questionnaire: only with the user's explicit yes for that step, after showing them what will be sent.
6. Release notes
One block per language, the tags on their own lines:
<fr-FR>
Première version.
</fr-FR>
<en-US>
First release.
</en-US>
7. The next versions
- Web app: the game updates with the site (push, publish): no new app. A new app only when the name, the icon,
the colours, the start address or the package change:
bin/jumphp twa <game>again. - Native app: each change of the game is a new app:
bin/jumphp android <game> --version-name 1.1.
Then: commit the version file, try the .apk on a phone (§4), Play Console > the same track > Create release > the
new .aab > notes > (countries already set) > Send for review. The declarations stay valid unless the game
changes what they describe (online play, purchases, data): update them first then.
8. Pitfalls met
| Symptom | Cause, fix |
|---|---|
| The app opens with an address bar | the site's assetlinks lacks a fingerprint (Google's after Play App Signing) or the package; §3 |
| The web app opens and closes at once | two Chrome on the phone (clone space); §4 |
INSTALL_FAILED_UPDATE_INCOMPATIBLE |
the installed app comes from Google Play (another signing key): uninstall first (ask) |
| Google Play: "version code already used" | build again (version + 1) |
| Google Play refuses the update's key | the upload key was lost or remade: restore the backup, or ask Google to reset it |
| "Your app cannot be published yet" | Store settings: category and contact e-mail |
| Send for review greyed out | an item of "Set up your app" is not done; a release without countries |
| A description is empty after filling it by automation | type it, then reload and check the text |
| "Upload at least 1 asset" | the picture is in the library but not attached to the listing: add it from the library panel |
| A tester's chip is not added | type the address then Enter (the chip), then Save and confirm |
| The privacy policy is refused | its address answers 404, or is not public: open it in a private window |
| The playground published nothing after a push | check get_project (published_commit) or the page itself; sync_project |
9. Never
- the keys, their passwords,
dist/,var/, debug screenshots or tokens in git; - accepting the Android SDK license, Google's terms or a questionnaire for the user without telling them;
- sending to production without the user's yes for that release;
- removing a phone's user / clone space, or uninstalling an app, without asking (data is lost);
- saying the game is "for children" unless the user wants it (it changes the rules and the visibility).