114 lines
10 KiB
Markdown
114 lines
10 KiB
Markdown
---
|
|
name: store-screenshots
|
|
description: Produce store screenshots and the Play feature graphic for a mobile game in every required size and many languages - capture raw frames from the running game (web build via playwright, iOS Simulator via simctl, Android emulator or device via adb, or a folder of frames from any engine), write per-language marketing copy (incl. RTL Arabic and CJK fonts), render captioned scenes with device frames, review them in a local gallery, A/B variants for store listing experiments / Product Page Optimization, JPEG copies for Play, and upload to both stores. Use when the user needs App Store / Google Play screenshots, preview images, a feature graphic, localized screenshot captions, or screenshot sizes.
|
|
---
|
|
|
|
# Store screenshots
|
|
|
|
CLI: `storebound` (or `bunx storebound` in a project that has it, or `bun <toolchain>/cli/index.ts`). Needs `ffmpeg`, and `playwright` in the project
|
|
(`bun add -d playwright`; it uses Playwright's Chromium or an installed Google Chrome) for rendering and web capture.
|
|
iOS Simulator capture needs macOS + Xcode (`xcrun`); Android capture needs `adb` (platform-tools).
|
|
|
|
## Sizes (what each store wants)
|
|
| size key | pixels | where |
|
|
|---|---|---|
|
|
| ios69 | 1320 x 2868 | App Store 6.9" (`APP_IPHONE_67`), required |
|
|
| ios65 | 1284 x 2778 | App Store 6.5" (`APP_IPHONE_65`) |
|
|
| ipad13 | 2064 x 2752 | App Store 13" iPad (`APP_IPAD_PRO_3GEN_129`), required when the app runs on iPad; only with `apple.ipad: true` |
|
|
| play | 1080 x 1920 | Play phone (2-8, ratio at most 2:1) |
|
|
| tab7 | 1080 x 1920 | Play 7" tablet (tablet frames, Android tablet body) |
|
|
| tab10 | 1440 x 2560 | Play 10" tablet |
|
|
| feature | 1024 x 500 | Play feature graphic (required) |
|
|
|
|
Sources (re-check before a release; Apple renames display classes often):
|
|
- Apple "Screenshot specifications": https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications
|
|
(13" iPad: 2064 x 2752 or 2048 x 2732, landscape too, "Required if app runs on iPad"; 1-10 per size; JPEG / PNG,
|
|
no alpha or transparency).
|
|
- ASC API `ScreenshotDisplayType`: https://developer.apple.com/documentation/appstoreconnectapi/screenshotdisplaytype
|
|
(there is no "13 inch" value: the 13" iPad set is `APP_IPAD_PRO_3GEN_129`).
|
|
- Play graphics: https://support.google.com/googleplay/android-developer/answer/9866151 (screenshots 320-3840 px, at
|
|
most 2:1, JPEG or 24-bit PNG, 8 MB; feature graphic 1024 x 500).
|
|
|
|
**iPad.** Set `apple.ipad: true` only if the app runs on iPad (iPhone-only apps skip the iPad set). Then the default
|
|
sizes include `ipad13` (3:4 layout), `apple screenshots` uploads it, `validate` requires it, and tablet frames default
|
|
to the 13" iPad screen (1032 x 1352 CSS px @2x below a 24 px bar), so an `iPad Pro 13-inch` / `iPad Air 13-inch`
|
|
simulator screenshot fits after the bar is cropped. Play tablet sizes (tab7 / tab10) reuse the same tablet frames, drawn
|
|
in a plain Android tablet body instead of the iPad one.
|
|
|
|
## Steps
|
|
1. **Game switches.** Give the game URL params for screenshots: language, fixed seed, no ads / analytics / purchase
|
|
UI, skip tutorial, jump to a level, freeze at a moment. Frames must show real gameplay (store rule).
|
|
2. **Capture.** Configure `shots.capture` with a `source` (or pass `--source`), then
|
|
`storebound shots capture --lang en --dry` to see the plan, and without `--dry` to capture. Frames land in
|
|
`<shots.frames>/<lang>/<phone|tablet>/<shot>.png`, local, not committed.
|
|
- `web` (default): `baseUrl`, `query` with `{lang}`, shots: `path` / `waitFor` / `eval` / `delayMs` / `device`.
|
|
Phone 440 x 902 @3x and tablet 800 x 1240 @2x by default; the template draws the status bar above.
|
|
- `ios-sim` (Unity, Godot, Flutter, native, Capacitor: any Simulator build): `ios.device` (simulator name or UDID,
|
|
e.g. a 6.9" iPhone), `ios.bundleId`, optional `ios.app` (.app to install), `ios.args`. Per shot: `args` (launch
|
|
arguments, read them with UserDefaults / your engine) and / or `url` (deep link). Language goes in as
|
|
`-AppleLanguages` / `-AppleLocale`; status bar is forced to 9:41, full battery. After a cold boot the app is
|
|
launched once and given `ios.warmupMs` (default 8000) before the first shot; without it the first frame of a
|
|
fresh simulator is often blank. A simulator storebound boots is shut down afterwards (`--keep-booted` keeps it).
|
|
For iPad shots set `ios.devices.tablet` (e.g. "iPad Pro 13-inch (M5)") and `device: 'tablet' | 'both'` per shot.
|
|
- `android-emu`: `android.package`, optional `serial`, `activity`, `apk`. Per shot: `url` (VIEW intent) and / or
|
|
typed `extras`. Demo-mode status bar; per-app language on Android 13+ (older: pass `{lang}` in an extra).
|
|
Nothing is wiped or rebooted.
|
|
- `folder`: frames made any other way; `shots capture` (and `shots check`) only verify that every frame the scenes
|
|
use exists with the right aspect ratio and resolution.
|
|
`{lang}`, `{locale}`, `{shot}` are replaced in args, extras and URLs. Simulator / emulator screenshots lose
|
|
`cropTop` rows (the status bar) so they fit the template: by default the frame's bar share per device class
|
|
(162 px on a 6.9" iPhone, 48 px on a 13" iPad with `apple.ipad`); set `cropTop: 120` or `{ phone, tablet }` for
|
|
other devices, and `shots.phone` / `shots.tablet` to that device's screen in points. Capture warns when a frame's
|
|
aspect does not match. Give the game time to load: `delayMs` (simulator / emulator; 2500 default is short for a
|
|
cold start) or `waitFor` (web).
|
|
3. **Copy.** `store/shots/copy.json`: per language, per scene: `eyebrow`, `title` [white line, gold line], `sub`,
|
|
`badges` [[big, small]]. Short and true (only claim what is in the game); about 15 Latin characters per title line.
|
|
Natural marketing tone per language, not literal translation; use the game's own terms.
|
|
4. **Fonts.** `storebound shots fonts` downloads title/body fonts and a Noto subset for every non-Latin script found in
|
|
the copy (CJK, Arabic, Hebrew, Devanagari, Thai, Cyrillic/Greek). Re-run after copy edits.
|
|
5. **Scenes.** `shots.scenes`: palette (fire, violet, blast, green, night, sky, gold, candy or custom), frames (one
|
|
front phone + optional back phones with x / dy / scale / rotate), badge slots (y, side, icon, hot, stars).
|
|
6. **Render.** `storebound shots render --lang en` first, review `store/renders/en/sheet.png` (contact sheet, sizes
|
|
packed into a grid), then
|
|
all languages in the background: `storebound shots render > .storebound/render.log 2>&1 &`.
|
|
7. **JPEG for Play.** `storebound shots jpeg` (q92, about 4x smaller than PNG; App Store stays PNG).
|
|
8. **Check.** `storebound shots check` (read-only, exit 1 on errors): pixel sizes (Apple: a listed size, portrait or
|
|
landscape; Play screenshots 320-3840 px at most 2:1; feature graphic exactly 1024 x 500), alpha, Play JPEG /
|
|
24-bit PNG and 8 MB, counts per set (Apple 1-10, Play 2-8), text overflow flags (warnings). `--variants` also checks
|
|
A/B variant folders. `storebound validate` runs the same checks on the renders folder and lists errors as
|
|
blockers next to the store state (`--no-local` skips them).
|
|
9. **Review.** `storebound shots gallery` writes `<renders>/index.html`: one self-contained page (no network, open it
|
|
from disk) with every language x size x scene, app previews with posters, variant tabs, filters (language, size,
|
|
only issues, search) and light / dark. Tiles with store check errors are outlined red, warnings amber, with the
|
|
message under the tile. Show the owner this page (or a screenshot of it) before uploading.
|
|
10. **Upload.** `storebound play images` and `storebound apple screenshots` (both idempotent, background + log).
|
|
|
|
## A/B variants and store experiments
|
|
`shots.variants.<id>`: `scenes` (order / subset), `copy` (a JSON merged over the base copy, only what changes),
|
|
`palettes` (per scene). `storebound shots render --variant b` (or `--variants` for all) writes
|
|
`<renders>/b/<lang>/...`; `shots check --variants`, `shots gallery` (tabs) and `shots jpeg --variant b` cover them.
|
|
`play images --variant b` / `apple screenshots --variant b` upload a variant to the MAIN listing (replacing the base
|
|
images there), so only do that after a test has a winner. What the stores offer, honestly:
|
|
- **Google Play store listing experiments** (Play Console > Grow users > Store listing experiments): up to 2 variants
|
|
against the current listing; one default-graphics experiment or up to 5 localized experiments at a time; icon,
|
|
feature graphic, screenshots (+ descriptions for localized ones); stops automatically after 6 months. Console only:
|
|
the Play Developer API has no experiments endpoint, so storebound renders and checks the variant images and you
|
|
upload them in the experiment form yourself.
|
|
https://support.google.com/googleplay/android-developer/answer/6227309
|
|
- **App Store Product Page Optimization** (App Store Connect > your app > Product Page Optimization): up to 3
|
|
treatments against the original, one test at a time, up to 90 days; icon, screenshots and app previews, localized
|
|
per treatment; new metadata goes through App Review; alternate icons must ship in the binary; shown on iOS / iPadOS
|
|
15+. https://developer.apple.com/app-store/product-page-optimization/
|
|
The App Store Connect API has the resources (`appStoreVersionExperiments` v2, treatments, treatment localizations
|
|
with their own screenshot / preview sets), but storebound does not create or start experiments: set the test up in
|
|
App Store Connect and upload the treatment screenshots there (the variant folder already has the right sizes).
|
|
- Test one thing per experiment (usually the first screenshot or the order), give it real traffic, and do not read
|
|
results early.
|
|
|
|
## Gotchas
|
|
- Output is 24-bit RGB PNG: Play rejects alpha / palette PNGs, Apple rejects alpha.
|
|
- Arabic: `rtl: true` on the language; numbers stay LTR inside RTL text automatically.
|
|
- Japanese breaks by phrase, Korean at spaces; long words shrink the line rather than wrap.
|
|
- Check every language's sheet for overflow before uploading; German / Russian titles run long.
|
|
- Play: 8 per type max; Apple: 10 per set max.
|
|
- Do not include prices, "free" badges for paid items, or other platforms' UI.
|