Skip to content

t1k:marketing:store:asc-setup

FieldValue
Modulestore
Version0.14.9
Efforthigh
Tools—
/t1k:marketing:store:asc-setup

Every The1Studio title shares the same store setup except for its name, its bundle ID, and its ASO copy. This skill holds the shared part once and takes a small per-game file for the rest.

A per-game file is about 12 lines. Everything else is inherited.

Per-game values (name, bundle ID, ASO copy) and the decision to commit are judgment and stay on a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”). Only the read-only runs of scripts/store-auto.cjs / scripts/asc-engine.cjs are cheap-tier:

StepAgent
Run store-auto.cjs resolve --config <file> and report the merged base + per-game configt1k-fact-fetcher — a local merge with no network call; the work is running the script and relaying its output
Run asc-engine.cjs store --manifest <file> --emit-diff and report the diff (legacy --config: store-auto.cjs run WITHOUT --confirm)t1k-metrics-reporter — preview only, it writes nothing to App Store Connect

Stays reasoning-tier: writing the per-game file, every --confirm run (it edits a live App Store Connect app), the ATT/App Privacy checklist, and the manual Console-only steps.

Base — templates/studio-base.jsonPer-game — your file
copyright {{YEAR}} TheOneGameStudioapp name
support / marketing / privacy / privacy-choices URLsbundle ID, SKU
releaseType: AFTER_APPROVALsubtitle, keywords
contentRights: DOES_NOT_USE_THIRD_PARTY_CONTENTdescription, promo text
primaryCategory: GAMES (+ simulation/casual)subcategories, if different
age rating — 25 fields, resolves to 4+screenshots
App Privacy — 6 data typesversion string
App Review contact — name, phone, emaildemo account, if the title has one

{{YEAR}} is substituted at run time, so the copyright never goes stale. Anything in the per-game file overrides the base; a deep merge, so you override one subcategory without restating the block.

App Store Connect → Users and Access → Integrations → Team Keys. Role App Manager or higher; a Developer-role key cannot see the app and returns an empty filter[bundleId] rather than a 403.

Env varValue
ASC_ISSUER_IDUUID at the top of the Integrations page
ASC_KEY_ID10-char id on the key’s row
ASC_PRIVATE_KEYabsolute path to AuthKey_XXXXXXXXXX.p8

The .p8 downloads exactly once. Store it mode 600, outside any git repo.

The path with an approval is the manifest path: one store-manifest/1 file per app (t1k-marketing-store-manifest), ONE engine entry, one diff, one hash.

Terminal window
set -a; source ~/.config/t1k/ads.env; set +a
# 1. read-only: print the plan. stdout is exactly ONE store-diff/1 JSON document, logs go to stderr
bun <skill>/scripts/asc-engine.cjs store --manifest stores/mygame/store-manifest.json --emit-diff > asc.diff.json
jq -r .stateFingerprint,.requestsSha256 asc.diff.json # what was looked at, what would be sent
# 2. a human approves the diff (the gate skill does this). storeDiffHash = sha256 of that one canonical line:
HASH=$(tr -d '\n' < asc.diff.json | sha256sum | cut -d' ' -f1)
bun <skill>/scripts/asc-engine.cjs store --manifest stores/mygame/store-manifest.json --confirm --expect-diff-hash "$HASH"

store is the ONLY command in manifest mode. In order it: creates the version if the manifest’s stores.asc.versionString has none, pushes listings, settings (categories, age rating, copyright, releaseType, contentRights, URLs), App Review details and screenshots. It reads ALL before-state first (GET only; the read phase is enforced GET-only at run time), prints path: before -> after per change, and returns before any write when --confirm is absent. With --confirm it recomputes the diff, requires its hash to equal --expect-diff-hash (otherwise exit 3, nothing written) and then sends the very request list the hash covers. It prints one store-applied/1 document on stdout (applied = the ops completed; the ASC apply is not atomic, a stop leaves a prefix and exits 1).

ExitMeaning
0ok (a preview and --emit-diff too)
1error: any API error (including an empty-bodied 5xx), an ambiguous or non-editable target, a mid-run 409
2usage or policy: an old subcommand, --config, any flag outside --manifest --emit-diff --confirm --expect-diff-hash --help --quiet --verbose, --confirm without --expect-diff-hash, bundleid/clone
3--expect-diff-hash does not match what the store looks like now: re-plan

Under --manifest the old subcommands (apply, screenshots, reviewdetails, plan, run) exit 2 (“use store”). bundleid and clone are not gate-enabled: they exit 2 under --manifest and only run with --config, where a bare --confirm still works and is announced as ungated. store-auto.cjs resolve --manifest <file> and privacy --manifest <file> stay available (read-only).

The diff names every effect, not just fields: /$effect/createVersion, /$effect/replaceSet/<locale>/<display> (screenshots; delete-then-upload, nonAtomic), skipped ops for values the engine will not send (whatsNew on a first release, URLs with no primary-locale localization, a missing age-rating declaration, an empty screenshot directory), unsupported for manifest iap items that list asc (no command), manual for App Privacy. A password is <env:NAME>, unverifiable, never a value. Targets are picked deterministically and recorded in targets: the appInfo not READY_FOR_DISTRIBUTION (two of them is exit 1), the version whose versionString equals the manifest’s (none: a create-version op, unless ANOTHER editable version exists: exit 1 naming both versions, since Apple allows one editable version and the create would 409; one in a non-editable state: exit 1; one WAITING_FOR_REVIEW: every op writing to it is inReview).

Legacy --config path (deprecated, kept working)

Section titled “Legacy --config path (deprecated, kept working)”

resolve, plan, apply, run, screenshots, reviewdetails, bundleid, clone with --config still work, warn on stderr and are not gated. run’s preview prints the settings diff (GET only) and never creates a version; run covers settings + App Review details only. Commands and examples: references/legacy-config-path.md.

run covers this too, but it is worth knowing on its own. App Review reads a contact block per version — one appStoreReviewDetails record, holding the four contact fields, the optional demo account, and free-text notes for the reviewer. The base carries the studio contact, so a title that needs nothing special gets it for free:

Terminal window
# preview: live -> config, field by field. writes nothing.
bun <skill>/scripts/asc-engine.cjs reviewdetails --config <resolved>
# write only what differs
bun <skill>/scripts/asc-engine.cjs reviewdetails --config <resolved> --confirm
# contact block of another app's most recent version that has one.
# copies contact fields ONLY — never the demo credentials, never notes.
bun <skill>/scripts/asc-engine.cjs reviewdetails --config <resolved> --from <appleId>

A demo password never lives in a config file. Config files are committed. Name an env var instead, and export it before the run:

"reviewDetails": {
"demoAccountRequired": true,
"demoAccountName": "qa@the1studio.org",
"demoAccountPasswordEnv": "MYGAME_DEMO_PASSWORD"
}

The engine reads $MYGAME_DEMO_PASSWORD and refuses to run if it is unset — rather than sending an empty password and leaving you to find out at review. It also refuses outright if it finds a literal demoAccountPassword in the config.

1. Creating the app record. There is no POST /v1/apps — GET and PATCH only. Do it at appstoreconnect.apple.com → + → New App. SKU is permanent; Bundle ID locks at first submission.

2. App Privacy. No endpoint exists — verified, not assumed: the app resource exposes 41 relationships and none is privacy-shaped, and /v1/appDataUsages, /v1/appDataUsagesPublishState and /v1/appDataUsageCategories all return 404 "resource does not exist". store-auto.cjs privacy prints the exact declaration to tick in the Console instead of pretending to push it.

ATT — read this before publishing a privacy label

Section titled “ATT — read this before publishing a privacy label”

The base declares all six data types used for tracking. That obliges the build to show the App Tracking Transparency prompt (ATTrackingManager). A label that says tracking with a build that never prompts is rejected on the mismatch. If a title genuinely ships no ad SDKs, override appPrivacy in its game file rather than declaring data it does not collect — an inaccurate privacy label is grounds for removal, not just rejection.

  • whatsNew is rejected on a first version. 409 STATE_ERROR — release notes need a prior release to describe, and the PATCH is atomic, so it takes description, keywords and promo text down with it. The engine detects a never-released app and skips the field. It starts applying at version 2.
  • ES256 must be raw R‖S, not DER. Node’s default crypto.sign emits DER and Apple answers a bare 401 with no body. The engine passes dsaEncoding: 'ieee-p1363'.
  • name and subtitle live on appInfoLocalizations; everything else lives on appStoreVersionLocalizations. Two objects, two PATCHes — the usual reason a “successful” apply leaves the subtitle unchanged.
  • appStoreAgeRating is derived, not settable. The base holds the 25 input fields; sending the resolved rating back is a 409.
  • Screenshot upload is replace-all per locale per display type. The engine deletes the existing set first, so an interrupted run leaves it empty, not stale. Re-run it.
  • APP_IPHONE_67 covers both 6.7” and 6.9”. There is no _69 enum.
  • A preview never creates a version. editableVersion with its create flag set POSTs /v1/appStoreVersions, so every command ties create to Boolean(argv.confirm) (applySettings, screenshots, reviewdetails; apply returns to its plan before reaching it). store never calls it: a missing version is a create-version op in the diff and a request only after the hash gate. A literal create flag set to true anywhere turns store-auto-preview-readonly.test.cjs red.
  • An HTTP error always fails, even with an empty body. parse() once returned {} for any empty body, so a 5xx GET read as “no items” and a failed PATCH/DELETE read as success. An empty body is success only for a 2xx; everything else throws and the command exits 1.
  • One appInfo, one version, for every command. plan, apply, run, clone and store share one pick (pickAppInfo, pickVersion in asc-engine.cjs); the old infos[0] in plan/apply and “first editable in API order” made two commands write to different records.
  • engine.scriptSha256 covers asc-engine.cjs, asc-store.cjs, store-auto.cjs and the manifest skill files they load (the static list ENGINE_FILES in asc-store.cjs, guarded by a test). A new require of a kit file must be added there, or asc-store.test.cjs fails; a module update changes the hash and a pending apply exits 3 (engine changed): re-plan.
  • Token lifetime is capped at 20 minutes. The engine mints 19 and re-mints on demand, so a long screenshot upload does not die partway.
  • A missing app reports as “no app record”, not 403. filter[bundleId] returns empty both when the app does not exist and when the key’s role cannot see it; the API cannot distinguish them, so the error names both causes.
  • App Review details are per VERSION, so a new version may need the pass again. One appStoreReviewDetails record exists per appStoreVersion. Whether Apple carries a previous version’s block forward when a new version is created is not verified here — reviewdetails prints the live state either way, so run the preview and read it rather than assuming. If it shows all =, nothing to do; if it shows a pending POST, it did not carry over.
  • Apple does not always return a stored demo password. The engine reports the live value as unknown rather than = in that case, because an absent value is not a match — a = there would be a green that proves nothing.
  • The studio contact block is the base’s; a game overrides only what differs. reviewDetails deep-merges like every other block, so one game can change contactEmail and inherit the rest.

The base was derived from a live, shipping app and verified field-by-field. When the studio changes a shared fact — a new privacy URL, a different copyright entity — change templates/studio-base.json and every future app inherits it. Existing apps do not update retroactively; re-run run --confirm per app.

  • references/api-surface.md — every endpoint, automatable vs manual
  • the studio-local play-console-setup skill — the Android half