Skip to content

t1k:marketing:store:play-console-setup

FieldValue
Modulestore
Version0.14.9
Effortmedium
Tools—
/t1k:marketing:store:play-console-setup

Drives the repeatable half of putting a game on Google Play from one config file per game. This skill owns the store-side of new-game onboarding: the listing, graphics, declarations, build upload and rollout. It does not own ad-network or mediation wiring, and it does not decide what the listing copy should say — bring finished ASO copy to it.

Deciding what goes on the store listing and whether to pass --confirm is judgment and stays on a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”). Only the read-only runs of scripts/play-console-setup.cjs are cheap-tier:

StepAgent
Run store --manifest <file> --emit-diff and report the difft1k-metrics-reporter — read-only: it opens a throwaway edit, reads, deletes the edit and prints one store-diff/1 document; writes nothing store-visible
Run store --manifest <file> (no --confirm) and report Google’s edits.validate resultt1k-metrics-reporter — writes only inside its own edit (uploads included), validates, then deletes the edit in a finally; the iap and Data Safety steps issue no non-GET
Legacy: plan --config <file> and apply / release / apply-release WITHOUT --confirmt1k-metrics-reporter — plan opens a throwaway edit on the live app and always discards it, even on error; the others validate then discard (also on error); nothing is committed

Stays reasoning-tier: every --confirm run (it commits to a live store listing and rollout), clone in every mode (not gate-enabled, below), the legacy iap / datasafety (--confirm writes with no diff), authoring the manifest and listing copy, staged-rollout percentages, and the Data Safety answers.

Activate on: “set up play store for <game>”, “play console setup”, “publish to play”, “update the store listing”, “upload the AAB”, “push screenshots”, “roll out to 10%”, “fill the data safety form”, “create IAP on Play”, “onboard <game> to Play Console”.

Do not use for: App Store Connect / iOS (different API entirely), listing copy authoring (→ ASO/copywriting skills), or post-launch revenue reporting (→ admob, applovin-max, crawldata).

The Play Developer API has no endpoint that creates an application. Every automated path starts from a package name that already exists. Before this skill can do anything, a human does this once per game in the Console:

  1. All apps -> Create app — name, default language, app-or-game, free-or-paid. Free-or-paid is irreversible once the app has been published; a free app can never become paid.
  2. Content rating questionnaire (IARC), app category, target audience, ads declaration, country distribution, Play App Signing enrolment.

That is roughly two minutes of clicking plus the rating questionnaire. Everything after it — the part that is long, repetitive, and easy to get subtly wrong across locales — is what the script does. Full automatable/manual table: references/api-surface.md.

A store-listing push is not a spend operation, but it is a live, public, user-facing write against a shipped product, and two of its actions are not cleanly reversible:

  • A production track release reaches real users. Halting a rollout does not un-install it from anyone who already updated.
  • Patching a live subscription changes prices for people who are already paying. The script refuses to touch an existing subscription for this reason.

So rules/ad-network-mcp-write-safety.md applies in full: preview first, one app at a time, explicit confirmation naming the app and the track, never a blind loop over a list of games.

Nothing store-visible changes unless --confirm is passed, and the preview is not a local guess. The script opens a real edit, applies the changes INSIDE it (uploads included), runs Google’s own edits.validate, then discards the edit. What validates in preview is what commits with --confirm. iap and Data Safety (and store’s iap and Data Safety steps) are outside the edit and issue no non-GET in a preview.

Run plan first anyway when you want the live-vs-config diff without the apply step: it opens a throwaway edit to read the live state, then always discards it (also on error) and never validates or commits it.

Service-account family, distinct from the Google Ads OAuth credentials in the same env file:

Env varWhere it comes from
PLAY_SERVICE_ACCOUNT_JSONAbsolute path to the service-account key JSON

One-time setup — Cloud project link, key creation, and the per-app Play Console grants that are the usual source of a confusing 403: references/service-account-setup.md.

Every new The1Studio Android game starts from one base, read from Smash Fest: Beach Crush: category Casual, no tags, the ten App content declarations, and a Data safety and content-rating pre-fill. The pre-fill is not a copy: each game confirms the data types and the sexual-content and digital-goods answers against its real build before submit. Contact email, website and privacy policy are NOT part of the base. Each game uses those of the store that publishes it, and a store with no recorded details must be asked. The base values, which half can run unattended, the dependency order, and the traps: references/studio-base-setup.md. Read it before onboarding a new game.

One manifest per game (t1k-marketing-store-manifest) replaces the per-game *.play.json. ONE command covers the whole Play side, in a fixed order (gate contract docs/store-gate-contract.md section 3):

Terminal window
bun scripts/play-console-setup.cjs store --manifest stores/<slug>/store-manifest.json # preview
bun scripts/play-console-setup.cjs store --manifest <m> --emit-diff # one store-diff/1 on stdout
bun scripts/play-console-setup.cjs store --manifest <m> --confirm --expect-diff-hash <storeDiffHash> # apply exactly that diff
  1. one edit: details, listings, graphics, uploads (aab, mapping, nativeSymbols), the track release, :validate, commit
  2. iap (products then subscriptions, no edit) 3. Data Safety (no edit). Step 1 is transactional; 2 and 3 are not.
  • Read first, one plan, one gate. All before-state is read (GET) first; the diff, the requestsSha256 and the requests executed come from the SAME in-memory list. The hash is verified before the first write of any step: a mismatch deletes the edit and exits 3. --confirm without --expect-diff-hash exits 2.
  • Omitted = keep. Listings and details are PATCHed (a new locale is PUT whole); null in the manifest is a delete op. Only the image types a locale LISTS are touched (compared by sha256, replace-set, equal sets make no op). In-app products are PATCHed per changed field; an existing subscription is skipped.
  • The track is replaced. PUT tracks/<track> drops every live release not carried over; each is a delete op under /$effect/track/<track>/releases/<status>:<codes> with the FULL live release as before.
  • Flags that shaped a write are manifest fields, so the hash binds them. These exit 2 under --manifest: --no-review / --send-for-review (play.release.noReview deprecated no-op / sendForReview), --cancel-in-review (cancelInReview), --track, --aab, --user-fraction, --release-notes, --locale, --config; the old subcommands (apply, release, iap, datasafety, plan) exit 2 “use store”. Commit sends changesInReviewBehavior=ERROR_IF_IN_REVIEW unless cancelInReview (Google’s own default cancels an in-flight review).
  • Exits: 0 ok, 1 error (any non-404 read failure, a mid-run conflict), 2 usage/policy, 3 drift.
  • Not gate-enabled: clone (copies details from another app). Under --manifest it exits 2; with --config semantics (--from/--to --confirm) it keeps the bare---confirm path and prints a warning.
  • --config still works and warns deprecated: use --manifest.

Op shapes, the diff-completeness rules, the engine identity closure and the real-transport confirmations: references/manifest-mode.md.

The legacy --config path (write the config, plan, push listing and graphics, release a build, Data Safety and IAP) is in references/legacy-config-workflow.md. New games use store --manifest above.

CommandDoesAtomic?
store(manifest mode) the whole Play side: edit work, then iap, then Data Safety; --emit-diff, --confirm --expect-diff-hashstep 1 one edit; steps 2 and 3 per request
cloneCopy contact details (and, with --iap, the product catalog) from another app. NOT gate-enabledone edit, then per product
planLive-vs-config diff, local asset validationread-only (opens a throwaway edit, always discarded)
applydetails + listings + imagesone edit
releaseAAB upload + track assignmentone edit
apply-releaseBoth of the aboveone edit
iapOne-time products, and subscriptions that do not yet existper product
datasafetyPOST the Data Safety CSVsingle call

Legacy flags: --confirm (write; takes no value, --confirm false is a usage error), --send-for-review (commit and send for review; the default is a saved draft, --no-review is a deprecated no-op), --cancel-in-review (allow the commit to cancel an in-flight review), --track, --aab, --locale, --verbose. Exit codes: 0 ok, 1 error, 2 usage. The legacy commit sends changesInReviewBehavior=ERROR_IF_IN_REVIEW, so a legacy --confirm fails fast when a version is in review; --cancel-in-review sends CANCEL_IN_REVIEW_AND_SUBMIT (Google’s own default) to cancel it deliberately. Bare invocation and --help print usage, exit 0.

A 10% production rollout is a release block, not a flag:

{ "track": "production", "status": "inProgress", "userFraction": 0.1 }

userFraction is valid only with inProgress or halted. Pairing it with completed is rejected at commit time, after the AAB has already uploaded. Raise the fraction by editing the config and re-running release without a new aab — set versionCodes instead so you promote the build already up there.

  • icon, not appIcon. The image path segment comes from the AppImageType enum; a wrong segment returns a bare 404, not a validation message.
  • Commit fails when someone has the Console open with an uncommitted draft. Either finish or discard that change in the browser, then re-run.
  • Version codes must strictly increase. Re-uploading the same AAB fails with apkUpgradeVersionConflict.
  • Image pushes are replace-all per locale per type. A config missing a screenshot set leaves that set alone; a config with one replaces it whole.
  • Data Safety is a full replacement, never a merge. Post the complete CSV.
  • invalid_grant arrives as an HTTP 400, and means clock drift, a revoked key, or a deleted service account — in that order of likelihood. The JWT uses absolute timestamps, so check NTP before regenerating a key.
  • A 403 right after setup is usually propagation. Give the Play-side grant a few minutes before debugging it.

The config shape is deliberately store-neutral above the release block. An App Store Connect path would reuse listings/graphics and swap the transport; that belongs in a sibling skill, not in this one.