Store

The Store item provides in-app purchases for iOS and Android. More...

Import Statement: import VPlayPlugins.soomla 1.2
Inherits:

Item

Inherited By:

LevelStore

Properties

Signals

Methods

Detailed Description

Property Documentation

androidPublicKey : string

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 Services & APIs, 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.


currencies : list<Currency>

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.


currencyPacks : list<CurrencyPack>

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.


goods : list<Good>

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.


secret : string

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.


supported : bool

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.


version : int

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.


Signal Documentation

currencyBalanceChanged(string itemId, int balance, int amountAdded)

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: In most cases the usage of the Currency::balance property is preferable over the usage of this signal in order to retrieve the current balance of a given Currency, as you can then benefit from the advantages of QML property bindings.


goodBalanceChanged(string itemId, int balance, int amountAdded)

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: In most cases the usage of the good's balance property is preferable over the usage of this signal in order to retrieve the current balance of a given Currency, as you can then benefit from the advantages of QML property bindings.


insufficientFundsError()

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: {
     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.


itemNotFoundError(string itemId)

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


itemPurchased(string itemId)

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.

See also storePurchased.


restoreAllTransactionsFinished(bool success)

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.

See also restoreAllTransactions and restoreAllTransactionsStarted.


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.

See also restoreAllTransactions and restoreAllTransactionsFinished.


storePurchaseCanceled(string itemId)

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.

See also storePurchased and storePurchaseStarted.


storePurchaseStarted(string itemId)

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.

See also storePurchased and storePurchaseCanceled.


storePurchased(string itemId)

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.

See also itemPurchased.


unexpectedError()

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.


Method Documentation

void buyItem(string itemId)

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.


int getItemBalance(string itemId)

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.


bool giveItem(string itemId, int amount)

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.

See also getItemBalance and takeItem.


void printStoreProductLists()

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.

Note: You are not required to use the output of this function, it's only meant to make publishing your game a lot easier.

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 Mac OS X 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.

void restoreAllTransactions()

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.


bool takeItem(string itemId, int amount)

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.


Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support