storebound/skills/play-first-release/SKILL.md

name

description

play-first-release

Step-by-step first (and later) Google Play release of a mobile game - Play Console app creation, service account + API access, signing, AAB upload to internal testing, store listing, graphics, data safety, App content declarations, production draft and sending for review. Use when the user wants to publish, release, upload or set up an Android game/app on Google Play, push a Play listing or AAB, or hits Play Developer API errors (edits, "outside of this Edit", draft app releases).

Google Play: first release

The CLI is storebound (on PATH while the plugin is enabled; otherwise bunx storebound in a project that has it, or bun <toolchain>/cli/index.ts; agents can also use the storebound mcp tools). It reads storebound.config.ts in the project (create with storebound init) and credentials from env or .storebound/credentials.json (gitignored). Every write command has --dry. Run storebound check first.

Ask the owner before anything public or irreversible: production releases, "Send for review", publishing, deleting products. Sending a first release for review is the owner's action in the Console, not yours.

Steps (API = storebound does it, UI = Play Console by hand)

1. UI · Create the app. Play Console > Home > Create app: name, default language, Game, Free, declarations. The package name is fixed by the first uploaded AAB.
2. UI · API access. Google Cloud project (any) > enable "Google Play Android Developer API" > create a service account > JSON key (keep it outside the repo). Play Console > Users and permissions > Invite new users > the service account email > app permissions: view app information, manage store presence, release to testing tracks, manage testing tracks, release to production (only if you want API production drafts), manage orders (for purchase checks). Put the key path in PLAY_SERVICE_ACCOUNT. Permissions can take a few minutes to apply.
3. Local · Signing. Generate an upload key (keytool -genkeypair -v -storetype PKCS12 -keystore upload.p12 -alias upload -keyalg RSA -keysize 4096 -validity 10950), keep keystore + passwords out of git and back them up (encrypted, two places). Play App Signing holds the real app key; a lost upload key can be reset via the Console. Check the AAB signer before uploading: keytool -printcert -jarfile app-release.aab.
4. Local · Version. versionName (e.g. 1.0.0) and a versionCode that always increases (storebound play next-version-code prints the next free one; use exactly that code in later steps). Capacitor: set them in android/app/build.gradle (or env-driven) before ./gradlew bundleRelease.
5. UI or API · First upload. The very first AAB may need the Console (Testing > Internal testing > Create new release) so Play links the package name; after that: storebound play release app-release.aab (internal, completed). Add testers (internal testing list) and license testers (Settings > License testing) so test purchases are free.
6. API · Listing text. Fill store/listing.md (one section per language), then storebound play listing. It also sets contact email + website (website = the domain serving app-ads.txt).
7. API · Graphics. Render (store-screenshots skill), storebound shots jpeg, then storebound play images > .storebound/play-images.log 2>&1 & and follow the log (it is slow: one edit per language).
8. API · In-app products. store-iap-setup skill (storebound play products). Needs a build with the BILLING permission on any track first.
9. API · Data safety. Answers in dataSafety of the config, storebound play data-safety, then check the summary in Policy and programs > App content > Data safety.
10. UI · App content. store-declarations skill: privacy policy, ads, app access, content rating (IARC), target audience, advertising ID, government / financial / health / news, data safety review.
11. UI · Store settings. Category + tags, contact details.
12. API + UI · Production. storebound play release --version-code N --production draft, then in the Console: Production > Countries/regions > Add countries > select all > Save; Production > the draft release > Edit > Next > Save; Publishing overview > Send changes for review (owner).
13. Verify. storebound validate --play (no blockers), storebound play status (tracks, listings, products), Console dashboard has no open tasks, Publishing overview shows "In review".

Gotchas

• Updates after the first release: staged rollout with release-management (play rollout).

• Draft app: until the first release is reviewed, the API only accepts status: draft ("Only releases with status draft may be created on draft app"). Create the production draft via API, finish in the Console (step 12).

• "A change was made to the application outside of this Edit": any Console save or other edit commit invalidates an open API edit. storebound redoes the edit automatically (3 retries) and uses one edit per language for images, but do not save things in the Console while uploads run.

• Uploads (AAB, 100+ images) take minutes: run them in the background with a log file and watch progress lines.

• Personal developer accounts created after Nov 2023 need a closed test with 12+ testers for 14 days before production; organization accounts skip that rule.

• Phone screenshots: 2-8, sides 320-3840 px, long side at most 2x the short side (1080 x 1920 fine, 1080 x 2400 not). Feature graphic 1024 x 500 required. PNG without alpha, or JPEG (q92 is 4x smaller and uploads faster).

• Play listing limits: title 30, short 80, full 4000, release notes 500 (checked locally before upload).

• The legacy inappproducts API returns 403 "Please migrate to the new publishing API": use monetization.onetimeproducts (what storebound play products does).

• Wrong path casing on the new product endpoints returns an HTML 404, not JSON (oneTimeProducts camelCase for list and batchUpdateStates).

• Website in the listing must be the exact domain whose /app-ads.txt lists your ad networks.