game-mobile-store-integration

name	game-mobile-store-integration
version	1.1.1
description	Wires mobile games to App Store and Google Play: StoreKit 2 / Play Billing with server-side receipt validation, AdMob/LevelPlay/MAX mediation, and Game Center / Play Games Services v2. Use when the user mentions IAP, receipt validation, App Store Connect, Play Console, rewarded ads, GameKit, or Play Games. Not for Godot export/signing (mobile-development), Steam, Stripe, or console stores. Never grant entitlement from the client SDK alone.
risk	safe
source	opus
date_added	2026-06-27T00:00:00.000Z

Mobile Store Integration

Connect a mobile game to the store platforms it ships on: purchase flows, receipt validation, ad monetization, and social/achievement services on iOS (App Store / StoreKit / Game Center) and Android (Google Play / Billing / Play Games Services).

This skill owns the store-platform contract itself — product configuration, the validation server, ad mediation strategy, and social services — which applies across Unity, Unreal, native, and Godot alike. The mobile-development skill owns the Godot engine-side export and runtime (Billing 5 plugin, StoreKit bridge, AndroidRuntime).

When to Use

• In-App Purchases: configuring consumables, non-consumables, auto-renewing subscriptions; the buy → validate → grant flow.
• Receipt validation: verifying purchases server-side against Apple/Google to defeat client tampering.
• Ad monetization: integrating banner/interstitial/rewarded ads via a mediation layer (AdMob, Unity LevelPlay, AppLovin MAX).
• Social services: Game Center / Play Games Services authentication, achievements, leaderboards, and cloud saved games.
• Store submission: App Store Connect / Play Console product setup, metadata, review-readiness.

Do Not Use

If the task is…	Use instead
Godot export, signing, AAB/IPA build, Godot billing plugin wiring	mobile-development
Steam achievements/leaderboards/Workshop/Cloud on PC	steamworks-sdk
Web/server credit-card payments, Stripe subscriptions	stripe-integration
Console store/online cert (Switch/PS/Xbox)	console-porting-certification

Prerequisites

• A paid Apple Developer Program membership (for App Store Connect / StoreKit 2 / Game Center).
• A Google Play Developer account (one-time $25 registration fee) with a configured app in the Play Console.
• A backend server you control for receipt validation — never grant entitlement on the client alone.
• For Google Play Developer API: a Google Cloud service account with the Android Publisher role and a downloaded JSON key.
• For Apple App Store Server API: an issuer ID, key ID, and downloaded .p8 key from App Store Connect → Users and Access → Keys.
• For ad mediation: accounts on each ad network (AdMob, Unity LevelPlay, AppLovin MAX) plus the mediation SDK integrated into your build.
• Store products (IAPs, achievements, leaderboards) defined in App Store Connect / Play Console before the client API references their IDs.

Procedure

1. Purchase Flow (the only correct shape)

client: request products  ──►  store SDK returns localized price
client: user taps buy     ──►  store SDK runs the payment sheet
store:  returns a signed receipt / purchase token
   │
   ▼  send token to YOUR server (never grant on the client alone)
server: verify with Apple/Google API  ──►  grant entitlement, record txn
   │
   ▼
client: finish/acknowledge the transaction  ◄── only after server confirms

Cardinal rule: the client never decides a purchase is valid. A jailbroken/rooted device can fake any client-side "success." Entitlement is granted by your server after it verifies the receipt with the platform.

2. Configure In-App Purchase Products

Type	iOS (StoreKit)	Android (Play Billing)	Must be
Consumable (gems, lives)	Consumable	INAPP, consumed after grant	Consumed so it can be re-bought
Non-consumable (remove ads, unlock)	Non-Consumable	INAPP, acknowledged	Restorable; never consumed
Auto-renewing subscription	Auto-Renewable	SUBS	Server-tracked renewal state

1. Define products in the store console first — App Store Connect → In-App Purchases, or Play Console → Monetize → Products. The client API only references IDs that already exist there.
2. Consumables must be consumed (Android) / finished (iOS) after the server grants them — otherwise the user can't buy again.
3. Non-consumables & subscriptions must support Restore Purchases (Apple requires a visible restore path). Re-query entitlements on fresh installs / new devices.
4. Acknowledge within the window: Google Play auto-refunds any purchase not acknowledged within 3 days. Acknowledge (or consume) only after your server grants.
5. Display store-returned localized prices — never hardcoded strings. Currencies, tiers, and taxes vary by region.

3. Implement Server-Side Receipt Validation

Apple (StoreKit 2)

1. Use StoreKit 2 only — StoreKit 1 and /verifyReceipt are deprecated.
2. On the server, verify the JWS signature against Apple's root CA — don't just decode the payload.
3. Check bundleId, environment (sandbox vs production), and transactionId in the verified payload.
4. Use the App Store Server API + App Store Server Notifications v2 as the source of truth for subscription state, refunds, and revocations.
5. Persist every transactionId to detect replays.

Google (Play Billing)

1. Ship the current Play Billing Library major — Play enforces a minimum version yearly and blocks updates on stale majors.
2. Verify the purchase token with the Google Play Developer API:
   • purchases.products.get for one-time purchases
   • purchases.subscriptionsv2.get for subscriptions
3. Use a service account with the Android Publisher role; authenticate with the downloaded JSON key.
4. Acknowledge/consume server-side via the API after granting.
5. Subscribe to Real-time Developer Notifications (RTDN) over Pub/Sub for renewals, cancels, refunds.

Both platforms

• Persist every transaction id / purchase token to detect replays — the same token submitted twice must not double-grant.
• Validate the bundle id / package name and product id in the receipt match your app — don't trust the client's claim of what was bought.

4. Integrate Ad Mediation

Game ── rewarded ad request ──► Mediation SDK (AdMob / LevelPlay / MAX)
                                      │ real-time bidding across networks
                                      ▼ highest-paying fill wins
                              onUserEarnedReward ──► grant reward ONCE

1. Use a mediation layer, not a single ad network — it fills inventory and raises eCPM via real-time bidding (waterfalls are legacy; prefer bidding-first setups). Don't hand-integrate five SDKs separately. LevelPlay is Unity's mediation (formerly ironSource).
2. Rewarded ads: grant the reward only in the onUserEarnedReward / completion callback, exactly once. Never grant on "ad opened" or on the close callback.
3. Preload interstitials/rewarded ahead of the moment you show them; a cold request at the show point fails to fill and feels broken.
4. Respect ATT (App Tracking Transparency) on iOS and consent (UMP/GDPR/CMP) before initializing ad SDKs, or you violate policy and lose fill.
5. Attribution is privacy-preserving now: AdAttributionKit (successor to SKAdNetwork) on iOS, Privacy Sandbox Attribution Reporting alongside GAID on Android. Don't build UA measurement on device-ID fingerprinting.
6. Don't interrupt active gameplay with interstitials; show at natural breaks (level end), and cap frequency.

5. Wire Social Services (Game Center / Play Games)

Use Play Games Services v2 on Android — v1 sign-in is shut down; v2 does automatic sign-in at launch with no consent screen for basic auth.

Capability	Game Center (iOS)	Play Games Services v2 (Android)
Sign-in	GKLocalPlayer.authenticate	GamesSignInClient / one-tap
Achievements	GKAchievement (percent → 100 = unlocked)	incremental or standard, defined in console
Leaderboards	GKLeaderboard submit/load	LeaderboardsClient submit/load
Cloud saves	iCloud / GKSavedGame	Snapshots API (handle conflict resolution)

1. Define achievements/leaderboards in App Store Connect / Play Console first; the API only references IDs that already exist there.
2. Authenticate early and silently; degrade gracefully if the user declines or is offline — never block game entry on a social sign-in.
3. For cloud saves, you must implement conflict resolution (two devices, divergent saves). The Snapshots/GKSavedGame API surfaces conflicts; don't blind-overwrite.

6. Prepare for Store Submission

1. iOS: app must have at least one IAP submitted with the app's first review if monetization is core; provide a sandbox tester account flow; privacy nutrition labels and ATT usage string are mandatory.
2. Android: upload a signed AAB; create products in Play Console (they're inactive until the app is published to a track); use license testers for unpaid sandbox purchases.
3. Stay on the platform treadmill: Play raises the required target API level every August; Apple raises the minimum Xcode/SDK every spring. A store-compliant build today is rejectable next year without touching your code.
4. Alternative billing / external purchase links (EU DMA, Google user-choice billing, US anti-steering entitlements) are region- and program-gated compliance work — don't treat them as the default flow, and keep the standard store flow working everywhere.
5. Test purchases in sandbox/test tracks before production — real charges in review get the build rejected.

Pitfalls

1. Client-side entitlement: granting the item because the client SDK said "purchased." Always validate on a server you control.
2. Not consuming consumables: user buys 100 gems once and can never buy again. Consume after grant.
3. No restore path: Apple rejects apps with non-consumables/subscriptions that lack Restore Purchases.
4. Ignoring the Google acknowledge window: unacknowledged purchases auto-refund in 3 days — the user is charged then refunded and you look broken.
5. Granting rewarded reward on the wrong callback: granting on close instead of onUserEarnedReward lets users skip the ad and still get paid.
6. Initializing ad SDKs before consent/ATT: policy violation, lost fill, possible removal.
7. Trusting receipt fields blindly: always re-verify bundle/package id and product id against your catalog; check for replayed transaction ids.
8. Hardcoding prices: always show the store-returned localized price, never a string you typed — currencies, tiers, and taxes vary by region.
9. Blocking launch on social sign-in: make Game Center/Play Games optional and async.
10. Using Play Games Services v1: v1 sign-in is shut down. Use v2 only.
11. Using StoreKit 1 / /verifyReceipt: deprecated. Build on StoreKit 2 and JWS signature verification.
12. Stale Play Billing Library major: Play blocks updates on outdated majors. Track the yearly minimum bump.

Verification

• Every purchase is verified server-side before entitlement is granted.
• Consumables are consumed/finished after grant; non-consumables & subs support Restore.
• Google purchases are acknowledged within 3 days; Apple transactions finished after server confirm.
• Transaction ids / purchase tokens are persisted and replay is rejected.
• Rewarded reward granted exactly once in the earned-reward callback.
• ATT (iOS) and consent (UMP/GDPR) handled before ad SDK init.
• Achievements/leaderboards exist in the store console before the API references them.
• Cloud saves implement conflict resolution.
• Localized store prices are displayed, not hardcoded strings.
• Purchases tested in sandbox / license-tester tracks before production.
• Play Games Services v2 used (not v1) on Android.
• StoreKit 2 used (not StoreKit 1) on iOS.
• Play Billing Library on the current major version.

Related Skills

• mobile-development — Godot engine-side export, signing, and the in-engine billing/ads plugins this contract sits behind.
• steamworks-sdk — The PC/Steam equivalent for ownership, achievements, leaderboards, and Cloud.
• stripe-integration — Web/server payments when selling outside the mobile stores.
• console-porting-certification — Console store and online service equivalents when porting beyond mobile.

References

• Apple StoreKit 2, App Store Server API, and App Store Server Notifications v2 documentation.
• Google Play Billing Library and Google Play Developer API (purchases & subscriptions) documentation.
• Google Mobile Ads (AdMob) mediation, Unity LevelPlay, and AppLovin MAX integration guides.
• Apple AdAttributionKit and Android Privacy Sandbox Attribution Reporting documentation.
• Apple GameKit (Game Center) and Google Play Games Services v2 documentation.