t1k:marketing:store:play-console-setup
| Field | Value |
|---|---|
| Module | store |
| Version | 0.14.9 |
| Effort | medium |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:store:play-console-setupPlay Console Setup
Section titled “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.
Executed by
Section titled “Executed by”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:
| Step | Agent |
|---|---|
Run store --manifest <file> --emit-diff and report the diff | t1k-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 result | t1k-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 --confirm | t1k-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.
When to use
Section titled “When to use”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 boundary you cannot automate
Section titled “The boundary you cannot automate”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:
- 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.
- 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.
Money and blast radius
Section titled “Money and blast radius”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.
Preview-first — how it works here
Section titled “Preview-first — how it works here”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.
Prerequisite — credentials
Section titled “Prerequisite — credentials”Service-account family, distinct from the Google Ads OAuth credentials in the same env file:
| Env var | Where it comes from |
|---|---|
PLAY_SERVICE_ACCOUNT_JSON | Absolute 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.
The studio base setup
Section titled “The studio base setup”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.
Manifest mode (the supported path)
Section titled “Manifest mode (the supported path)”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):
bun scripts/play-console-setup.cjs store --manifest stores/<slug>/store-manifest.json # previewbun scripts/play-console-setup.cjs store --manifest <m> --emit-diff # one store-diff/1 on stdoutbun scripts/play-console-setup.cjs store --manifest <m> --confirm --expect-diff-hash <storeDiffHash> # apply exactly that diff- one edit: details, listings, graphics, uploads (
aab,mapping,nativeSymbols), the track release,:validate, commit 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
requestsSha256and 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.--confirmwithout--expect-diff-hashexits 2. - Omitted = keep. Listings and details are PATCHed (a new locale is PUT whole);
nullin the manifest is adeleteop. 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 isskipped. - The track is replaced.
PUT tracks/<track>drops every live release not carried over; each is adeleteop under/$effect/track/<track>/releases/<status>:<codes>with the FULL live release asbefore. - 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.noReviewdeprecated 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 “usestore”. Commit sendschangesInReviewBehavior=ERROR_IF_IN_REVIEWunlesscancelInReview(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--manifestit exits 2; with--configsemantics (--from/--to --confirm) it keeps the bare---confirmpath and prints a warning. --configstill works and warnsdeprecated: use --manifest.
Op shapes, the diff-completeness rules, the engine identity closure and the real-transport confirmations:
references/manifest-mode.md.
Workflow (legacy --config path)
Section titled “Workflow (legacy --config path)”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.
Commands
Section titled “Commands”| Command | Does | Atomic? |
|---|---|---|
store | (manifest mode) the whole Play side: edit work, then iap, then Data Safety; --emit-diff, --confirm --expect-diff-hash | step 1 one edit; steps 2 and 3 per request |
clone | Copy contact details (and, with --iap, the product catalog) from another app. NOT gate-enabled | one edit, then per product |
plan | Live-vs-config diff, local asset validation | read-only (opens a throwaway edit, always discarded) |
apply | details + listings + images | one edit |
release | AAB upload + track assignment | one edit |
apply-release | Both of the above | one edit |
iap | One-time products, and subscriptions that do not yet exist | per product |
datasafety | POST the Data Safety CSV | single 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.
Staged rollout
Section titled “Staged rollout”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.
Hard rules
Section titled “Hard rules”icon, notappIcon. 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_grantarrives 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.
Adding a second store
Section titled “Adding a second store”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.