Store

The androidPublicKey property is mandatory if you want to use in-app purchases on Google Play Store.

Every app on Google Play Store has a unique public key for communication between the app and Play Store. To find the public key, open your application's details in your Developer Console after uploading a draft apk, then click on Monetization Setup, and look at the field titled Your License Key for This Application. For more information have a look at Getting an app's license key.

This property holds all currencies you want to provide within your game's assets. You need at least one currency defined to be able to offer virtual purchases.

You define your virtual currencies like the following example. For more information have a look at Currency item.

 Store {
   currencies: [
     Currency { id: creditsCurrency; itemId: "currency_credits_id"; name: "Credits"; }
   ]
 }

See also Currency.

Currency packs are collections you can offer your users to buy a certain amount of your in-game currencies. You need at least one currency and one currency pack defined to be able to offer virtual purchases.

You define your virtual currencies packs like the following example. For more information have a look at CurrencyPack item.

 Store {
   currencies: [
     Currency { id: creditsCurrency; itemId: "currency_credits_id"; name: "Credits"; }
   ]

   currencyPacks: [
     CurrencyPack {
       id: credits10Pack
       itemId: "credits_pack_10_id"
       name: "10 Credits"
       currencyId: creditsCurrency.itemId // The currency you want to offer with this pack
       currencyAmount: 10
       purchaseType:  StorePurchase { id: credits10Purchase; productId: credits10Pack.itemId; }
     }
   ]
 }

See also CurrencyPack and Currency.

The goods property holds all virtual goods you want to offer within your game. Depending on your store design goods can either be purchased with virtual currency (VirtualPurchase) or from the platform's stores directly (StorePurchase).

The Store plugin offers different types of goods to simplify the handling of virtual items, including LifetimeGood, SingleUseGood and SingleUsePackGood.

You define virtual goods like the following example:

 Store {
   goods: [
     SingleUseGood {
       id: vacGood
       itemId: "vac_item_id"
       name: "Vacuum Cleaner"
       description: "All Squabies are sucked in by your mom's vacuum cleaner"
       purchaseType: VirtualPurchase { itemId: goldCurrency.itemId; amount: 50; }
     }
   ]
 }

See also LifetimeGood, SingleUseGood, and SingleUsePackGood.

The secret property is used to encrypt the purchase and inventory data stored locally on the device. Be sure to set the secret only once per app and don't change it while running your game and after publishing your app (and updates), otherwise all purchased items from your user get lost.

Be sure to keep your game's secret in private. The property is mandatory.

A boolean read-only flag holding the state if billing (in-app purchases in general) is supported on the currently used device.

Possible reasons for unsupported devices are for example an unsupported platform (e.g. the current device is MeeGo powered), activated parental control (iOS) or an outdated Google Play app on Android. If supported is false calls involving StorePurchase items won't succeed, you then could inform the user that his device is currently not able to perform in-app purchases.

An integer holding the current version of your game's store assets described by currencies, currencyPacks and goods.

Bump the version every time you make changes to your game's assets to overwrite the old settings. Like changes to secret, version changes will delete all user items stored locally, so don't change it while running your game and after publishing your app unless you have to do so.

If you omit this property a default value of 1 is used.

This handler is called when the balance of a currency given with the itemId parameter changes. The amountAdded parameter describes the positive (when added) or negative (when subtracted) change of the balance.

Note: The corresponding handler is onCurrencyBalanceChanged.

This handler is called when the balance of a good item given with the itemId parameter changes. The amountAdded parameter describes the positive (when added) or negative (when subtracted) change of the balance.

Note: The corresponding handler is onGoodBalanceChanged.

This handler is called whenever a purchase of an item with VirtualPurchase type failed because the user's payment item balance is not sufficient. For example, you can then give the hint that new credits can be purchased:

 Store {
   onInsufficientFundsError: itemId => {
     NativeUtils.displayMessageBox("Out of Gold", "You can purchase new gold in Squaby's in-game store.")
   }
 }

This handler is also called if you try to decrease a Currency's balance with takeItem where the amount taken off is higher than the remaining balance.

The itemId parameter is set to the item that was tried to purchase (or give) for which the signal gets emitted.

Note: The corresponding handler is onInsufficientFundsError.

This handler is called whenever an item with the given itemId can't be found in the last store request.

Note: The corresponding handler is onItemNotFoundError.

This handler is called whenever an item with StorePurchase or VirtualPurchase type was purchased successfully. If the purchase is of type StorePurchase the signal storePurchased also gets emitted, so make sure to prevent certain actions from performing twice after a purchase.

Note: The corresponding handler is onItemPurchased.

See also storePurchased.

This handler is called right after restoreAllTransactions finished. You can use it to hide a status indicator as long as the user's transactions are loaded.

The success parameter indicates if the restoreAllTransactions was successful or not. If the restore operation was successful this would be the right place to re-download content of a LifetimeGood or update the game's UI.

Note: The corresponding handler is onRestoreAllTransactionsFinished.

See also restoreAllTransactions and restoreAllTransactionsStarted.

This handler is called right after restoreAllTransactions gets called. As the method works asynchronous your game should display a status indicator as long until restoreAllTransactionsFinished gets emitted.

Note: The corresponding handler is onRestoreAllTransactionsStarted.

See also restoreAllTransactions and restoreAllTransactionsFinished.

This handler is called whenever a user cancels the purchase of an item with type StorePurchase. This may happen if the user selects the cancel button of the platform's store overlay or no valid payment options are given.

Note: The corresponding handler is onStorePurchaseCanceled.

See also storePurchased and storePurchaseStarted.

This handler is called whenever a user starts a purchase of an item with type StorePurchase. This implies usually that the platform's store overlay is shown and asks the user for a valid store account.

Note: The corresponding handler is onStorePurchaseStarted.

See also storePurchased and storePurchaseCanceled.

This handler is called whenever an item with StorePurchase type was purchased successfully. Whenever this signal is emitted the signal itemPurchased also gets emitted, so make sure to prevent certain actions from performing twice after a purchase.

On iOS, the additional parameter transactionData contains information about the payment transaction. The information is forwarded from SKPaymentTransaction. It is a JSON map with the following entries:

• receiptBase64: Payment receipt data encoded in Base64.
• transactionIdentifier: A string that uniquely identifies a successful payment transaction.
• transactionDate: The date the transaction was added to the App Store’s payment queue as a string formatted MM/dd/YYYY.
• originalTransactionIdentifier: A string that uniquely identifies a payment transaction that was restored by the App Store.
• originalTransactionDate: The date the restored transaction was added to the App Store’s payment queue as a string formatted MM/dd/YYYY.

On other platforms, transactionData contains an undefined value.

Note: The corresponding handler is onStorePurchased.

See also itemPurchased.

This handler is called whenever an unexpected error occurred during the last store request. You can use this handler to ask the player for sending a support request so you can resolve this issue.

Note: The corresponding handler is onUnexpectedError.

Call this method to purchase the given item from a platform store or with virtual currency, depending on the purchase type. Purchasable items are CurrencyPack, LifetimeGood, SingleUseGood, and SingleUsePackGood.

See also getItemBalance.

Returns the balance of the an item with the given itemId. Keep in mind that only items of type Currency, LifetimeGood and SingleUseGood have a meaningful balance. You can also use the item's balance property to retrieve the balance of the specific item

See also giveItem and takeItem.

Call this method to give a user a specific amount of the item with the given itemId, without charging for it.

Keep in mind that only items of type Currency, LifetimeGood and SingleUseGood can be given. The amount is optional, if amount is omitted a value of 1 is used as default value.

Returns result

See also getItemBalance and takeItem.

Use this method to export CSV data sets for importing to the specific platform stores.

In order to be able to use in-app purchases on Google Play and iOS App Store you have to define the in-app products beforehand in the platform developer consoles. This is a tedious process as you generally have to define at least a name, description and item id for each platform separately.

To improve this step you can use printStoreProductLists() to print a corresponding CSV list which you then can save into a text file and import to the specific platform stores.

Calling this method makes only sense if you've defined the itemId, name, description and price properties in your virtual items which are encapsulated by a StorePurchase item. Here is an example:

 CurrencyPack {
   id: gold10Pack
   itemId: "gold_pack_10_id"
   name: "10 Pieces of Gold"
   description: "Buy this item to get additional 10 pieces of Gold"
   currencyId: goldCurrency.itemId
   currencyAmount: 10
   purchaseType: StorePurchase { id: gold10Purchase; productId: gold10Pack.itemId; price: 0.89; }
 }

Here is how to use the method:

1. Define your virtual economy model and your in-app purchases like described in this document.
2. Add a block like the following to your Store item:

    Component.onCompleted: store.printStoreProductLists()

   Note: Be sure to remove the code snippet again before shipping your game!

3. Run your game and look for log output like the following one:

    ================================================================================
   
    Google Play CSV file:
   
    net.vplay.plugins.SoomlaSample.noads,published,managed_by_android,false,en_US;No Ads;Buy this item to remove the app banner,true,2990000
    net.vplay.plugins.SoomlaSample.gold_pack_10,published,managed_by_publisher,false,en_US;10 Gold Nuggets;Buy 10 Gold Nuggets,true,890000
    net.vplay.plugins.SoomlaSample.gold_pack_50,published,managed_by_publisher,false,en_US;50 Gold Nuggets;Buy 50 Gold Nuggets,true,3990000
   
    iTunes Connect CSV file:
   
    SKU       Product ID      Reference Name  Type    Cleared For Sale        Wholesale Price Tier    Displayed Name  Description     Effective Date
    [SKU]     net.vplay.plugins.SoomlaSample.noads    net.vplay.plugins.SoomlaSample.noads    Non-Consumable  yes     [PRICE TIER]    No Ads  Buy this item to remove the app banner  now
    [SKU]     net.vplay.plugins.SoomlaSample.gold_pack_10     net.vplay.plugins.SoomlaSample.gold_pack_10     Consumable      yes     [PRICE TIER]    10 Gold Nuggets Buy 10 Gold Nuggets     now
    [SKU]     net.vplay.plugins.SoomlaSample.gold_pack_50     net.vplay.plugins.SoomlaSample.gold_pack_50     Consumable      yes     [PRICE TIER]    50 Gold Nuggets Buy 50 Gold Nuggets     now
   
    ================================================================================

4. Apple iTunes

   On iOS the productId must be unique across all in-app purchases and uploaded apps. It's therefore best practice to prepend the productId with your game's package identifier (like net.vplay.plugins.SoomlaSample). Please also keep in mind that the productId may only contain alphanumeric characters, underscores, and periods.

   • Copy the text block below "iTunes Connect CSV file:" into a text file.

     Note: Make sure that your text editor does not transform the tab delimiters to whitespaces, otherwise Application Loader won't accept your file.

   • Replace the "[SKU]" string with the SKU value of your app, found under the App Summary page on iTunes Connect. The SKU must match an existing application SKU.
   • Replace the "[PRICE TIER]" string with your desired price tier for your products. You can change your prices later on online in iTunes Connect (or via Application Loader app).
   • Open Application Loader on your macOS development machine, select Create New Package New from file.

     

   • Add ascreenshot for review for each of your in-app products. These screenshots should show where and how you use the in-app purchases in you app, they are only for the Apple Review Team and therefore never publicly shown withtin the App Store.
   • Adapt the other settings to your need and then select the "Delivery2 tab and click the "Deliver" button.
5. Google Play
   • Copy the text block below "Google Play CSV file:" into a text file.
   • Open the Google Play Developer Console, select your app, open the "In-App Products" tab.
   • Click the "Import/Export" button and import the created text file. You can then further adapt the settings of your in-app products.

     Note: You need to upload a draft apk with "BILLING" permissions set before being able to define in-app products first.

6. You can then check your in-app purchases online and further adapt the settings to your needs.

   Note: This method only supports consumable and non-consumable purchases. It currently does not support exporting subscriptions (goods with StorePurchase::isSubscription of true). You can define subscriptions manually in the app store backends.

Call this method to reload your good's purchase details from the app store backends. This updates the properties of StorePurchase, like marketPriceAndCurrency.

Usually this call happens automatically at the app start. In some cases this automatic call can fail, for example if there is no internet connection. You can then use this method to retry loading the details.

See also StorePurchase.

Call this method to restore all items of type LifetimeGood associated with a user's platform app store account after re-installing your game on a specific device.

Please keep in mind that only items associated with a specific account can be restored and therefore cross-platform restores between Android and iOS are not possible.

This method should be triggered by the user and not called automatically on every app start. The signal restoreAllTransactionsFinished will get emitted as soon as all in-app purchases are restored.

See also restoreAllTransactionsStarted and restoreAllTransactionsFinished.

Call this method to take away a specific amount of the item with the given itemId from a user, without refunding for it.

Keep in mind that only items of type Currency, LifetimeGood and SingleUseGood can be given. The amount is optional, if amount is omitted a value of 1 is used as default value.

The method returns true if the operation was successful or false if the amount to be taken is higher than the remaining balance of the item or the amount is 0.

See also getItemBalance and giveItem.