InAppPurchase¶

C++ type: InAppPurchase (static) · Header: InAppPurchase.h

Description¶

One-time products, consumable or not, and subscriptions, through Google Play Billing on Android and StoreKit 2 on iOS. Exports include it only when Google Play Billing is enabled in the project's Android settings, or App Store Purchases in its iOS settings. On every other platform the calls report BILLING_UNAVAILABLE through their events.

Results arrive as events at the start of a frame. A purchase must be acknowledged or consumed: Google Play refunds one left unsettled for three days, and the App Store delivers it again at every launch. See Monetization → In-app purchases for the setup, a complete store script, and the App Store differences.

REGISTER_EVENT(InAppPurchase::onPurchaseUpdated, onPurchaseUpdated);
InAppPurchase::purchase("remove_ads");

void Store::onPurchaseUpdated(PurchaseDetails purchase) {
    if (purchase.state == PurchaseState::PURCHASED && !purchase.acknowledged) {
        InAppPurchase::acknowledgePurchase(purchase.purchaseToken);
    }
}

RegisterEvent(self, InAppPurchase.onPurchaseUpdated, "onPurchaseUpdated")
InAppPurchase.purchase("remove_ads")

function Store:onPurchaseUpdated(purchase)
    if purchase.state == PurchaseState.PURCHASED and not purchase.acknowledged then
        InAppPurchase.acknowledgePurchase(purchase.purchaseToken)
    end
end

Methods¶

Callback events¶

Method details¶

initialize / isReady¶

• static void initialize()
• static bool isReady()

Connects to the store. onInitialized(response, message) reports OK once it is ready, and every call before that fails with SERVICE_DISCONNECTED. Calling initialize() again while connected reports OK again.

On Android, isReady() is true while connected to Google Play. When the connection drops, onDisconnected fires and the next call connects again by itself. On iOS, initialize() reports OK at once and starts listening for App Store transactions, which delivers the ones left unsettled in earlier launches through onPurchaseUpdated.

queryProducts¶

• static void queryProducts(const std::vector\<std::string>& productIds, ProductType type)

Fetches the details of these products, which must all be of type: their localized names, descriptions, prices and, for subscriptions, plans and offers. onProductsQueried(response, message) reports when they are stored, and products the store does not know are left out. On iOS so are products of the other type, and the message names both kinds. An empty list reports DEVELOPER_ERROR. In Lua, pass a table of strings.

InAppPurchase::queryProducts({"coins_100", "remove_ads"}, ProductType::INAPP);
InAppPurchase::queryProducts({"premium"}, ProductType::SUBS);

InAppPurchase.queryProducts({ "coins_100", "remove_ads" }, ProductType.INAPP)
InAppPurchase.queryProducts({ "premium" }, ProductType.SUBS)

hasProduct / getProduct / getProducts¶

• static bool hasProduct(const std::string& productId)
• static ProductDetails getProduct(const std::string& productId)
• static std::vector\<ProductDetails> getProducts()

The products queried so far. getProduct() returns an empty ProductDetails for a product that was not queried, so check hasProduct() first.

for _, product in ipairs(InAppPurchase.getProducts()) do
    Log.print(product.name .. " " .. product.price)
end

purchase¶

• static void purchase(const std::string& productId, const std::string& offerToken = "")

Opens the store's purchase screen for a queried product. The result is onPurchaseUpdated for a completed or pending purchase, or onPurchaseFailed(productId, response, message), for example with USER_CANCELED, ITEM_ALREADY_OWNED, or ITEM_UNAVAILABLE for a product that was not queried.

On Google Play, offerToken picks a subscription plan from the product's offers. Left empty, a subscription buys its first base plan (or its first offer when it has no base plan), and a one-time product its default purchase option. The App Store ignores it: a product has one plan, and its introductory offer applies by itself.

On iOS, a device not allowed to make payments reports BILLING_UNAVAILABLE, and a purchase waiting for a parent's approval (Ask to Buy) is reported as PENDING with no purchaseToken; once approved, it arrives as a new purchase.

The purchases include the ids set with setObfuscatedAccountId and setObfuscatedProfileId.

changeSubscription¶

• static void changeSubscription(const std::string& productId, const std::string& offerToken, const std::string& oldPurchaseToken, SubscriptionReplacementMode mode = WITH_TIME_PRORATION)

Replaces an owned subscription with another plan or product, an upgrade or a downgrade. oldPurchaseToken must belong to a purchase in getPurchases(), so query SUBS purchases first; otherwise onPurchaseFailed reports DEVELOPER_ERROR. mode decides how the time left on the old plan is billed. KEEP_EXISTING keeps the old plan's payment schedule and ignores offerToken.

On iOS it buys productId like purchase(), and the App Store replaces the subscription of the same group; offerToken and mode are ignored.

acknowledgePurchase / consumePurchase¶

• static void acknowledgePurchase(const std::string& purchaseToken)
• static void consumePurchase(const std::string& purchaseToken)

Settle a PURCHASED purchase. Google Play refunds one left unsettled for three days, and the App Store delivers it again at every launch. On iOS, settling finishes the purchase's transactions.

• Acknowledge products bought once and subscriptions. onPurchaseAcknowledged(purchaseToken, response, message) reports it, and the stored purchase's acknowledged turns true.
• Consume consumables, like coins. Consuming also acknowledges, removes the purchase from getPurchases(), and lets the player buy the product again. onPurchaseConsumed(purchaseToken, response, message) reports it.

Grant and save a consumable before consuming it, once per purchaseToken: the same purchase can be reported twice, and a consumed one is never reported again. On iOS, consuming a product that is not a consumable in App Store Connect reports DEVELOPER_ERROR, and consuming one twice reports ITEM_NOT_OWNED. Never settle a PENDING purchase.

queryPurchases¶

• static void queryPurchases(ProductType type)

Asks the store for the player's purchases of type: active subscriptions, products bought once, and consumables not consumed yet. Each one is reported through onPurchaseUpdated with restored set, then onPurchasesQueried(type, response, message) fires. With OK, the result replaces the stored purchases of that type, so refunded and expired ones go away.

Call it for each type at startup and on Engine::onResume: purchases also complete outside the app, through pending payments, promo codes or another device.

restorePurchases¶

• static void restorePurchases()

For a Restore Purchases button: queries the purchases of both types, as two queryPurchases calls do. On iOS it first syncs the player's App Store account, which may ask them to sign in; a failed sync reports its error through both onPurchasesQueried events. Apple's review guidelines ask apps to offer a way to restore purchases that can be restored.

getPurchases / isPurchased¶

• static std::vector\<PurchaseDetails> getPurchases()
• static bool isPurchased(const std::string& productId)

The purchases known in this session, from purchase screens and queryPurchases, less the consumed ones. isPurchased() is true when one of them includes the product, is PURCHASED, and is not suspended. It does not check acknowledgment.

setObfuscatedAccountId / setObfuscatedProfileId¶

• static void setObfuscatedAccountId(const std::string& accountId)
• static void setObfuscatedProfileId(const std::string& profileId)

A hashed id of the player's account in your game, and of a profile within it, attached to the next purchases. Google Play uses them against fraud, and they come back in PurchaseDetails for your server. Never pass plain personal data.

The App Store takes the account id only as a UUID, which it keeps as the transaction's appAccountToken; any other value is left out with a warning. It has no profile id.

openSubscriptionManagement¶

• static void openSubscriptionManagement(const std::string& productId = "")

Opens the store's subscription management, on one subscription or on all of them, where the player can cancel or fix a payment. On Android it opens Google Play's subscription center. On iOS it shows Apple's subscription sheet over the game, on the product's subscription group from iOS 17, and queries the subscriptions again when it closes.

showInAppMessages¶

• static void showInAppMessages()

Lets Google Play show its messages about subscription payment problems, such as a declined card. When the player fixes the payment, subscription purchases are queried again, and onPurchaseUpdated reports the subscription without suspended. It does nothing on iOS, which shows these messages by itself.

Events¶

Each event is a static FunctionSubscribe member; subscribe with REGISTER_EVENT in C++ or RegisterEvent in Lua (see Events). C++ handlers take the parameters by value, exactly as listed.

Types¶

These structs are also Lua classes with the same fields. Lists are Lua tables.

ProductDetails¶

A product as the store describes it, from queryProducts.

ProductOffer¶

A subscription's base plan or offer, or a one-time product's purchase option.

PricingPhase¶

PurchaseDetails¶

Enumerations¶

ProductType¶

• INAPP — A one-time product, consumable or not. Also an iOS non-renewing subscription, which the store never expires: work out its end from purchaseTime.
• SUBS — An auto-renewing subscription.

PurchaseState¶

• UNSPECIFIED — Unknown state. On iOS, also a refunded purchase or an ended subscription.
• PURCHASED — Paid. Grant it and settle it.
• PENDING — Waiting for a payment or an approval made outside the app, like Ask to Buy on iOS. Do not grant it yet.

BillingResponse¶

Google Play Billing's response codes, with the same values. iOS maps StoreKit's errors to them.

RecurrenceMode¶

• INFINITE_RECURRING — Repeats until the subscription is canceled.
• FINITE_RECURRING — Repeats billingCycleCount times.
• NON_RECURRING — Charged once.

SubscriptionReplacementMode¶

How changeSubscription bills the time left on the old plan.

• WITH_TIME_PRORATION — The change applies now, and the time left is credited toward the new plan.
• CHARGE_PRORATED_PRICE — The change applies now and the billing date stays; the price difference for the time left is charged. Upgrades only.
• WITHOUT_PRORATION — The change applies now, and the new price is charged from the next billing date.
• CHARGE_FULL_PRICE — The change applies now, the new plan is charged in full, and the time left is credited.
• DEFERRED — The change applies when the old plan renews.
• KEEP_EXISTING — The old plan's payment schedule carries over. offerToken is ignored.

See also¶

• Monetization — setup, testing, and a complete store script
• AdMob and WebPortal