In-App Purchase

In-App Purchase (IAP) lets your players buy things directly from inside the app — either coin packs to spend on hints, or a one-time Remove Ads purchase to hide ads forever. Google Play and the App Store handle the payments and take their standard commission.

The two product types

The app supports two kinds of products:

• Coins pack — a consumable product. Every time a player buys it, they receive the number of coins you set. Buyers can purchase the same pack as many times as they like.
• Remove Ads — a non-consumable product. It's bought once, and from that moment on, ads are permanently hidden for that player. Any purchase of any Remove Ads product flips the same "no more ads" flag.

You can create as many coin packs as you want (a typical setup has 3–5 different sizes). You should have at most one Remove Ads product.

How the workflow goes

Setting up IAP takes three coordinated steps — you define your products in three places with the same product IDs:

1. Create the products on the Setup Page.
2. Create the same products on Google Play Console (for Android).
3. Create the same products on App Store Connect (for iOS).

The product IDs must match exactly across all three places, or purchases won't work.

Step 1 — Define your products on the Setup Page

Open the Setup Page in your browser and go to the In-App Purchase section. Turn on Enable In-App Purchase at the top.

Click + Add product to add your first product, then fill in:

• Product ID — a unique identifier for this product, like coins_500 or remove_ads. Lowercase letters, digits, dots and underscores only — no spaces. Once you've submitted this ID to a store and it's been approved, you can never rename it, so pick something you're happy with.
• Display title — the label shown on the store screen inside the app (e.g. "500 Coins" or "Remove Ads"). This is separate from the title the stores show on the actual payment popup, which you'll set on Google Play and the App Store.
• Type — pick Coins or Remove Ads.
• Coins granted (only shown for Coins products) — how many coins the player receives when they buy this pack.

Click + Add product again for each additional product you want. Click Remove on any card to delete it.

Suggested lineup:

• coins_100 → "100 Coins" — grants 100
• coins_500 → "500 Coins" — grants 500
• coins_2000 → "2000 Coins" — grants 2000
• remove_ads → "Remove Ads" — hides ads permanently

Step 2 — Create the same products on Google Play

1. Open the Google Play Console and select your app.
2. In the left menu, go to Monetize with Play → In-app products for the coin packs.
3. Click Create product and enter the exact same Product ID you set on the Setup Page (e.g. coins_500).
4. Give it a title, a description, and a price.
5. Set the product to Active.
6. Repeat for each coin pack.
7. For Remove Ads, do the same but under Monetize with Play → In-app products, choosing the Managed product / non-consumable type.

Important. Google Play won't let you create in-app products until you've uploaded at least one signed AAB (a signed build of your app) to a testing track. See Publishing → Build & Publish if you haven't done that yet.

Step 3 — Create the same products on App Store Connect

1. Open App Store Connect and select your app.
2. Go to In-App Purchases → Manage.
3. Click + to add a new product.
4. Choose the type:
   • Consumable for coin packs.
   • Non-Consumable for Remove Ads.
5. Enter the exact same Product ID you used in Step 1 and Step 2.
6. Fill in the reference name, display name, description and price.
7. Submit the product for review.
8. Repeat for each product.

Step 4 — Run sync

Once you've defined your products on the Setup Page (Step 1), run the sync command in your terminal:

make sync

You can run this immediately — you don't need to wait until Steps 2 and 3 are done on the stores. The app will start looking for those product IDs as soon as it launches; the stores just need to have them registered by the time a real user tries to buy.

Testing your purchases

Real purchases only work when the app is signed and installed via a store testing track. Never test IAP with a debug build — the store SDK won't see your products.

On Google Play:

1. Upload a signed AAB to an Internal testing track (see Build & Publish).
2. In Play Console, go to Setup → License testing and add your Google account email as a License tester.
3. Install the app on your device from the internal testing link.
4. When you buy something, Google shows a "Test payment — you will not be charged" dialog.

On App Store Connect:

1. Upload a build via TestFlight.
2. Go to Users and Access → Sandbox → Testers and create a Sandbox tester account with a fake email.
3. On your iPhone, go to Settings → App Store → Sandbox Account and sign in with that account.
4. Install the app from TestFlight and try a purchase — you'll be charged nothing.

Common problems

• "Product not found" — the product ID on the Setup Page doesn't match the one on the store, or the store product isn't set to Active yet.
• Products load but nothing happens on tap — you're testing in a debug build. Upload to an internal testing track and install from there.
• Everything works but no ads-hidden after buying Remove Ads — the purchase went through, but the app didn't detect it. Force-close the app and reopen it; the flag is checked at launch.