CRT/storebound
1
0
Fork 0
Code Issues Pull requests Releases 1 Packages 1 Activity Actions
storebound/skills/play-first-release/SKILL.md

12 KiB
Raw Blame History

name description
play-first-release Step-by-step first (and later) Google Play release of a mobile app or 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 app or game 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.

Do it, don't ask (first rule in AGENTS.md / docs/agents-core.md): you run every step below yourself, API steps with storebound and UI steps in Play Console with your browser tool, and verify each. The owner only presses the public or irreversible buttons (Send changes for review, production release or rollout, agreements, deleting products) and answers the compliance facts no file proves, all in one batch at the start.

Steps (API = storebound, UI = Play Console, driven by you with your browser tool)

  1. UI · Create the app. storebound console plan play-app-record (then drive the form with your browser tool, or the scripted storebound console fill play-app-record). The form is /console/u/0/developers/<developerId>/create-new-app: App name (max 30), App package name (play.packageName, max 150; press the read-only "Check availability": "Package name available"; fixed for good), default language, App or Game and Free or Paid (material radios: click the inner [role=radio], then no "Select …" hint may be left), and the declarations, which the owner ticks before pressing Create app. Free can never become Paid. storebound console verify play-app-record checks the form first. Afterwards the app lives at /console/u/0/developers/<developerId>/app/<appId>/app-dashboard: run storebound console verify play-app-record --url "<that URL>" (dry diff of play.appId), then the same with --write to save it (the App content forms deep-link from it). Missed the redirect: storebound play app-id (the app list shows 10 per page and a new app is not on page 1; search the package name, pipe the captures in). Owner step after every Create app: a service account's app-level permissions do NOT cover apps created later. Granting them is the owner's (a permission grant; agents in auto mode are blocked from it too): give the exact path in the same message as the Create app button, Users and permissions > the service account > Add app > the new app > Admin (or at least: view app information, manage store presence, release to testing tracks, manage testing tracks, manage production releases, manage policy declarations, manage orders and subscriptions) > Apply > Save changes. Then run storebound apps check --store play yourself.
  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. Put the keystore path and passwords in ANDROID_KEYSTORE, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, ANDROID_KEY_PASSWORD (env or .storebound/credentials.json) and storebound play build signs with it (build-and-sign skill).
  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). storebound play build --version-name 1.0.0 --dry, then without --dry: Gradle bundleRelease (Flutter: flutter build appbundle) with the next free versionCode, AAB in build/android/. Capacitor, React Native, Flutter and Unity exports are found automatically.
  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 upload --track internal --dry, then without --dry (asks first; play release app-release.aab does the same with more track options). 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). Run --dry first and show the owner the plan (details and per language old -> new per field; draft languages skipped until listing reviewed, --include-drafts only on the owner's word); then run it yourself with --yes: it PUTs only what changes.
  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). Required: the 512 x 512 icon, the 1024 x 500 feature graphic and at least 2 phone screenshots (Play Console Help answer 9866151). 7" / 10" tablet screenshots are optional (no tablet featuring without them): a phone-only project gets an info line, not an error; play.tablets: true renders and requires them, false never asks. Tablet screenshots already on Play stay unless the owner runs --prune.
  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. storebound console plan play-app-content --json lists every card of /app-content/overview in order (Privacy policy, Ads, Sign in details, Content ratings, Target audience and content, Data safety, Advertising ID, Government apps, Financial features, Health apps), each card's page and start button (aria-label "Start declaration"), its own plan (console plan play-privacy-policy, play-ads, play-sign-in-details, play-content-rating, play-target-audience, play-advertising-id, play-government-apps, play-financial-features, play-health-apps) and ONE owner batch (ownerBatch, printed first): the open answers (write them into the config: console.contentRating.details, console.appContent, social, products[].randomRewards; rerun the plan) and, before you start, the IARC Terms of Use box on the questionnaire's page 1 (an agreement; page 1's Next does nothing until it is ticked). Then console plan play-app-content --all walks every card in order without a stop: you press each card's Save (a declaration save: Google gets nothing before "Send changes for review", the owner's, verified 2026-10-13). Data safety goes through the API (step 9). Behind a sign-in: you type the demo account from .storebound/credentials.json (reviewDemoAccount, never printed; the owner only when it is not there; review-access); with accounts: the delete-account URL (account-deletion); subscriptions: storebound play subscriptions (store-subscriptions).
  11. UI · Store settings (App category). play listing cannot set it (the Play API has no category field), so a new app shows "Not selected": set play.category (Play's name, e.g. "Strategy"; storebound check warns without it), then storebound console plan play-store-settings: /store-settings > the FIRST Edit > App or game > the Category dropdown's [role=option] with exactly that name > Save. Contact details come from play listing.
  12. API + UI · Production. storebound play release --version-code N --production draft, then in the Console (you, with your browser tool): a) storebound console plan play-production-countries: tracks/production > Countries / regions tab > Edit countries / regions > the mat-checkbox "Select all rows" (or play.countries) > Save; a "Go to Publishing overview?" dialog follows. edits.countryAvailability is read-only in the API; storebound validate --play reports "production has 0 countries". b) storebound console plan play-production-release: Releases tab > Edit release > Next (a missing deobfuscation file is only a warning) > Save. c) Publishing overview > "Submit N changes for review" > dialog "Send N changes for review?" > Send changes for review: the owner's final button, and it needs a real click (a JS .click() did nothing on it). While a review is already running, "Submit N changes for review" opens "Do you want to restart your review?" with Restart review instead: that restarts the running review with the new changes. It is the owner's button too (never the agent's); Cancel leaves the running review alone. Managed publishing is off by default: the app goes live automatically once Google approves it. If the owner wants to pick the moment, they turn on Publishing overview > Managed publishing first; record it in play.managedPublishing (play release and the plan warn while it is off).
  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 2023-11-13 need a closed test with at least 12 opted-in testers for 14 days in a row before they can apply for production (Play Console Help answer/14151465); organization accounts skip that rule. Set play.accountType and play.accountCreated so storebound scan reminds you.

  • 16 KB page sizes: apps with native code (Unity, Flutter, React Native, NDK) must support 16 KB pages; from 2027-02-01 Play blocks updates that don't. storebound scan flags old Unity / React Native / NDK / AGP versions and lists prebuilt .so files; check the built app with zipalign -v -c -P 16 4 app.apk.

  • 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.