Store Compliance

Credentials, handled safely

Rules, in priority order:

1. Never put a key in osg/osg.config.ts. That file is committed. There is no credential field in it, on purpose.
2. Never paste a key into a command line. It lands in shell history and in your transcript.
3. Point at a file, and gitignore the file. Apple's key is a .p8, Google's is a service account JSON. Add both to .gitignore before you download them.
4. Never echo, cat or print a key file, and never read one into your own context to "check it". You do not need to see it to use it.
5. If the user pastes a key into the conversation anyway, tell them to rotate it.

Set the environment variables the CLI documents, then run the command. Confirm the exact names with osg upload --help for the release in use:

export OSG_ASC_ISSUER_ID=...          # App Store Connect API issuer id, a UUID
export OSG_ASC_KEY_ID=...             # the key id
export OSG_ASC_KEY_FILE=./secrets/AuthKey_XXXX.p8
npx -y open-screenshot-generator@0 upload

$env:OSG_ASC_ISSUER_ID = '...'
$env:OSG_ASC_KEY_ID    = '...'
$env:OSG_ASC_KEY_FILE  = './secrets/AuthKey_XXXX.p8'
npx -y open-screenshot-generator@0 upload

PowerShell has no inline environment prefix, so VAR=x command does not work there. Set them on their own lines, as above.

For Google Play, one variable pointing at the service account JSON:

export OSG_PLAY_KEY_FILE=./secrets/play-service-account.json
npx -y open-screenshot-generator@0 upload --store play

The Apple key needs the App Manager role. The Play service account has to be invited in Play Console and the Android Developer API has to be enabled on the project.

What each store actually does with the upload

App Store Connect reserves each asset, uploads it in chunks to pre signed URLs, then commits it with a checksum. Every one of those calls returns 2xx for a wrong sized image. Apple then processes the asset asynchronously and it fails minutes to hours later. The upload therefore polls the delivery state and reports what Apple actually concluded, which is the only reason it can be trusted when it says the upload worked. Do not treat a fast success message from any other tool as acceptance.

Screenshots hang off a set scoped to (version, localization, display type), so a mixed project is grouped by resolved display type and each group gets its own set.

Screenshots are frozen once a version is submitted. Only a version in an editable state accepts them, and writing to one in review comes back 409. The version has to leave review first. Nothing is preselected for you, because arming an upload against a frozen version is worse than asking.

Google Play opens a staged edit, uploads into listings/<language>/<imageType>, validates, then commits. Nothing is public until the commit, and a thrown error discards the whole edit, so a failed run cannot leave a half updated listing. Some accounts refuse automatic review submission and say so in the commit error; the client retries without sending for review and reports that it did.

Troubleshooting

Apple returns 401 or 403. Either the key is wrong or the key does not have the App Manager role. The two are indistinguishable in practice, so check both rather than guessing.

Play returns 403. Almost always setup, not code: the service account was never invited in Play Console, or the Android Developer API is not enabled.

Play returns 404. A package name typo, or an app that has never been published. Play refuses API edits before the first release.

Apple accepted it and then the screenshot disappeared. The asset delivery state went to FAILED. That is a size or a format problem, and osg verify catches every case of it before the upload.

"This version cannot be edited." It is in review or already released. Create the next version in App Store Connect first.

Verify passes and the store still complains about content. The mechanical rules are what verify covers. Review guidelines are not mechanical: do not show a device frame inside the screenshot of a different device, do not show competing platforms' branding, do not put an award or a rating in the image that the app did not earn, and do not show UI that is not in the shipped build. Those are human review calls and they are also the ones that cost a week.

A screenshot shows content that is not in the build. That is the most common human review rejection of all. If the design invented a stat, a chart or a testimonial, change it.

Related skills

• store-screenshots for producing the set in the first place
• app-preview-video for the video rules, which are stricter than the image rules
• store-localization for per locale caps and folders
• editor-tools for fixing what verify flagged, one element at a time