Skip to main content
A real-money item is a shop item the player pays for in the App Store or Google Play. The store charges the player; Flock asks the store whether the purchase is real, then delivers the item. Your game makes the same call it makes for any item: Shop.PurchaseAsync(item.Id) in Unity, the shop provider’s Purchase (the Flock Purchase node) in Unreal.
The store’s purchase is finished only after Flock delivered, so a crash or a lost connection in between never loses what the player paid for: the store hands the purchase back at the next launch and Flock delivers it then. One store purchase is delivered once, however many times it is sent.
Real-money purchases need the Flock SDK for Unity 1.98.0 or later, or the Flock SDK for Unreal 1.45.0 or later (its Blueprint nodes from 1.47.0). Wallet purchases need neither: see Shops and Inventory.
  • Unity needs Unity IAP 5 (com.unity.purchasing 5.x) in the project. On Android, set Minimum API Level to 23 or higher (Player Settings → Other Settings): Unity IAP 5’s Google Play Billing library needs it, and a Unity 2021.3 project starts at 22, so its build stops with a manifest merger error.
  • Unreal needs nothing installed: Flock reaches the store through the engine’s online subsystem, which it turns on. Google Play needs UE 5.8 or later, the first engine with a Billing Library Google Play still takes; on UE 5.4 to 5.7 connecting the store is refused.

What you set up

  1. Connect each store to Flock in the dashboard, with your game’s own keys.
  2. Price the items in real money and give each the id of its product in the store.
  3. Create the products in the store with those ids.
  4. Connect the store in your game once at start.
  5. Check the setup from the game.
1

Connect the stores to Flock

Open Monetization → Payments in the Flock dashboard and connect each store you sell in. Flock uses these keys to ask the store about a purchase; they never reach the player’s device.
  1. In the menu at the top of the page, choose the game: each game connects its own stores.
  2. On the Providers tab, under Mobile stores, press Connect beside Google Play or App Store.
  3. Fill in every field, as the tables below say, and leave Active ticked.
  4. Press Save. Success: the store shows Connected and names the keys it holds.
The keys are encrypted before they are stored and are never shown again: to replace one, press Update keys and enter every field again. Only studio admins and managers connect stores. The Sales tab lists every sale, and refunds one when you press Refund.
To make the service account:
  1. In the Google Cloud console, in any project, turn on the Google Play Android Developer API.
  2. Create a service account there, and add a JSON key to it. The key downloads as a file.
  3. In the Google Play Console, under Users and permissions, invite the service account’s email address, give it your app, and allow View financial data and Manage orders and subscriptions.
  4. Paste the JSON file’s whole text into Service account JSON.
Google can take a while to accept a new service account. Until it does, the setup check below says the store refused your keys. In our test it took effect a minute after re-saving one of the app’s products in the Play Console.
Each store’s form also shows a Notification URL. Give it to the store (App Store Connect’s App Store Server Notifications, Google Play’s real-time developer notifications) so Flock hears about refunds.
2

Price the items in real money

An item costs real money when its currency is one of the Real Currencies in the currency config of its Game Version (Monetization → Currencies, the Real Currencies tab; see Currencies and Wallets). In the item’s form (Monetization → Shops, the shop’s Items tab; see Shops and Inventory), type the Price as the player sees it, such as 3.99; the server keeps it in the currency’s smallest unit, so the SDK reads 399 in SAR for SAR 3.99. Success: the item’s tile shows Real money.On each such item, under Store product IDs, enter its product id for each store, exactly as the store has it. The item’s type decides what kind of product it is in the store:
3

Create the products in the store

Create each product with the same id: in the Google Play Console under Monetize → Products → One-time products, in App Store Connect under your app’s In-App Purchases. Activate it. The price the player sees is the one the store sets for their country.
4

Connect the store in your game

Connect once, after the SDK starts, and keep the connection for the whole session. On a phone the store is found by itself; on Windows, macOS, Linux and WebGL the same call connects a web checkout instead (Web Payments).
The Unity editor cannot show a store purchase succeed. It connects a web checkout unless the build target is Android or iOS, and then Unity IAP’s fake store answers, whose purchases Flock refuses. To see a store purchase go through, build to a device that has the store (see Test before you ship).First install Unity IAP 5: open Window → Package Manager, click +, choose Add package by name… (Install package by name… in Unity 6), enter com.unity.purchasing and a 5.x version.
Unity's Package Manager with In-App Purchasing selected

Window → Package Manager with In-App Purchasing (com.unity.purchasing) selected, version 5.

For Android, also set Minimum API Level to 23 or higher in Edit → Project Settings → Player → Android → Other Settings.Then add this component to an object in your first scene. RefreshTheShop stands for your own code that reads the wallet and inventory again and redraws the shop.
From now on Shop.PurchaseAsync buys real-money items through this connection. Without one, it refuses a real-money item before anything is sent, and says to connect the store. Connecting a store is refused when Unity IAP 5 is not installed. The examples below use this store.
5

Check the setup

The setup check asks the store and Flock’s server whether everything is in place, without buying anything. It needs a signed-in player, so run it from a developer button after signing in, while you set up.
CheckSetupAsync throws FlockAuthException without a signed-in player, so sign the player in first (Authenticate a player). The code runs inside an async method.

Show the store’s price

Show the price the store gives, which is in the player’s currency with their taxes, rather than the item’s Flock price.
item is a real-money ShopItem read from its shop.
GetPrice is null when the store did not find the product. The prices in the comment are examples: the text is the store’s own. On a web checkout GetPrice gives the item’s own price and is never null.

Buy

The code runs inside an async method; item is a real-money ShopItem read from its shop (see Shops and Inventory), and ShowReward and ShowWaitingForPayment stand for your own screens.
Every case, in short:If you cancel the call’s own CancellationToken, the store’s purchase carries on, and PurchaseCompleted reports it once paid. If the player signs out while the store’s dialog is open, the call ends as cancelled too, and the store’s purchase, once paid, is delivered to the player who bought it at a later sign-in, or through Restore purchases.

Restore purchases

A player on a new phone, or after a reinstall, gets their one-time items back with Restore purchases. Start it from a button once the player is signed in to Flock: without a signed-in player it fails. On the App Store it also asks the player to sign in to the store.
RestoreAsync throws FlockAuthException without a signed-in player. The code runs inside an async method.
A purchase delivered before grants nothing again. One-time items belong to the Flock player who bought them, so the player must sign in to that same Flock account (a device sign-in is tied to the device; link the account to keep purchases across devices). See Linking Accounts.

Purchases finished later

Some purchases end after the call: a payment that clears later, or a purchase interrupted by a crash or a lost connection. The store hands each back when the game connects to it; once a player is signed in, Flock delivers it and PurchaseCompleted reports it (Unreal: OnPurchaseCompleted, or On Store Purchase Completed in Blueprint). One Flock could not be reached for is sent again at the next launch, or at once when the player taps Restore purchases. Subscribe to it before anything else needs it, and use it to refresh the shop and the wallet.

Stop selling an item

Set the item, or its shop, to Inactive in the dashboard. Players’ shop reads leave it out at once, and the purchase call checks with Flock just before the store’s dialog, so a game still showing the item refuses with ShopItemNotForSale and the store never charges. A purchase the player already paid for is still delivered: the game keeps the products it sold, so an unfinished purchase of an inactive item is delivered at the next launch, and restoring still gives back one-time items.

Test before you ship

  • In the Unity editor, the build target decides: with Android or iOS selected, Unity IAP’s fake store answers. On another build target, name the store to test with: FlockStore.ConnectAsync(new FlockStoreOptions { PaymentProvider = PaymentProviders.GooglePlay }). The setup check works there and tests your keys, but Flock refuses the fake store’s purchases, so a purchase in the editor ends as not delivered.
  • In Unreal, the store is reached on an Android or iOS device only: in the editor and on Windows, macOS and Linux, Connect makes a web checkout. Test store purchases on a device, installed as below.
  • Google Play: upload a build to the internal testing track, add your testers under License testing in the Play Console, and install the game from the testing link in the Play Store. A tester’s purchase is not charged.
  • App Store: use a Sandbox tester from App Store Connect on a device.

Revenue

Flock records revenue on the server, once per store purchase, at the item’s Flock price and currency. The SDK sends no revenue of its own for a store purchase, and a wallet purchase is never counted as revenue.

When something fails

Every failure says what went wrong and how to fix it: in Unity its Message, with the fix on a Fix: line; in Unreal Error.ToDisplayText(), with the fix in Error.Hint. In Unreal each code below is EFlockErrorCode:: followed by its name. The store purchase’s own codes:

Unity IAP 4

A game on Unity IAP 4.x keeps its own purchase code and hands each purchase to Flock with Shop.RedeemStoreReceiptAsync, finishing it in the store only once that returns. FlockUnityIap4Store.cs in the SDK’s GitHub repository is a ready-made version to copy into your project (the .unitypackage does not include it).

Your own store code in Unreal

A game with billing code of its own (on Android with UE 5.4 to 5.7, for one) hands each purchase to Flock with the shop provider’s RedeemStoreReceipt (Flock Redeem Store Receipt, with Make Google Play Receipt or Make App Store Receipt), finishing it in the store only once that succeeds. A redemption is safe to send again: one store purchase makes one Flock purchase. Use one way to buy. The engine’s own in-app purchase Blueprint nodes finish a purchase as it is made, before Flock has delivered it, so a purchase Flock then refuses is lost. The editor’s Flock setup panel warns when a Blueprint uses them in a game whose shops sell real-money items; keep them only for products no Flock shop item sells.