Store

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

Import Statement: import VPlayPlugins 1.0
Inherits:

PluginItem

Inherited By:

LevelStore.

Properties

Signals

Methods

Detailed Description

This item provides in-app purchases using the Soomla framework. Users can buy virtual goods using either virtual or real currencies. See Soomla Store Plugin documentation for more infos.

To synchronize your users' in-app purchases over multiple devices, use the SyncedStore item.

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

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
Sign up for Free and start developing right away!
I want to make Games
I want to make Apps
Game Development
Cross-Platform, Any Resolution

Use one IDE to deploy to all supported platforms, including iOS and Android, from a single code base.

Support all screen resolutions, aspect ratios and sizes with auto-adapting UI elements, smart scene scaling and memory efficient asset selection.

Learn More

V-Play ranked #1 at research2guidance cross-platform tool benchmarking 2014 by 2188 developers comparing 40 leading tools.

Multiplayer

V-Play Multiplayer supports both real-time and turn-based gameplay, so you can use it to make many different types of cross-platform multiplayer games. It's perfect for making player-vs-player games like 'Words with Friends' or games for a large amount of players, such as 'Clash of Clans'.

Learn More Video

Highscores & Achievements

The V-Play Game Network is a cross-platform gaming service that allows players around the world to compare game highscores and achievements. Players can also challenge each other across multiple platforms and share their progress on Facebook.

Learn More

QML & JavaScript

Qt Meta Language is a highly intuitive reactive language, which is super easy to learn, yet it's extremely powerful and flexible. Mix it with JavaScript to create awesome stuff, with just a few lines of code.

import QtQuick 2.0
import VPlay 2.0

GameWindow {
  Scene {
    
    SimpleButton {
      anchors.centerIn: parent
      text: "Press Me"
      onClicked: {
        console.debug("Wow you pressed me!")
      }
    }
  }
}

Learn More

Monetize & Analyze

With V-Play, you can use many 3rd party services for ads, in-app purchases, analytics and more, with just a few lines of code. All of these plugins work cross-platform, which allows you to maintain a single code base.

Learn More

Level Editor

The LevelEditor can be used during development to create and modify levels for your game, which you can then bundle in your final publishing build. Additionally, you can also integrate the in-game level editor to your published game and let your gamers create new levels.

Learn More Video

Card Game like UNO, Hearthstone or Poker

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/OneCard/OneCard.pro

Match-3 like Candy Crush Saga

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/JuicySquash/JuicySquash.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/JuicySquashAdvanced/JuicySquashAdvanced.pro

Puzzle like 2048 or Threes!

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/2048/2048.pro

Casino like Big Win Slots

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/FlaskOfRum/FlaskOfRum.pro

Side Scroller like Jetpack Joyride or Flappy Bird

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/FlappyBird/FlappyBird.pro

Tower Defense like Castle Defense or Bloons TD

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/Squaby/Squaby.pro

Falldown & Jump like Doodle Jump or Mega Jump

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/ChickenOutbreak/ChickenOutbreak.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/ChickenOutbreak2/ChickenOutbreak2.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/DoodleJump/DoodleJump.pro

Platformer like Super Mario or Lep's World

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/Platformer/Platformer.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/PlatformerWithLevelEditor/PlatformerWithLevelEditor.pro

Action like Angry Birds, Fruit Ninja, Cut the Rope

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/StackTheBoxWithCommunityEditor/StackTheBoxWithCommunityEditor.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/BalloonPop/BalloonPop.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/CarChallenge/CarChallenge.pro

Arcade like Arkanoid or Space Invaders

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/ZombieBreak/ZombieBreak.pro

Community like Super Mario Maker or Minecraft

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/examples/Squaby/Squaby.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/StackTheBoxWithCommunityEditor/StackTheBoxWithCommunityEditor.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/PlatformerWithLevelEditor/PlatformerWithLevelEditor.pro

Any other Idea? let us know how we can help you

You are looking for another demo?

The V-Play SDK includes many open-source demos for different game genres. You can use their source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

If you do not find your game genre in this list and wonder if V-Play is the right choice, just contact us, we are happy to help!

Contact Us

App Development
Better Apps, Less Effort

Develop feature-rich, cross-platform mobile apps from a single code base.

V-Play apps look, feel and perform exactly like native iOS, Android and Desktop apps. With less code & much faster development time.

Learn More Highlights Video

V-Play ranked #1 at research2guidance cross-platform tool benchmarking 2014 by 2188 developers comparing 40 leading tools.

Save Time, Code & Money

Save up to 90% source code with V-Play, compared to frameworks like Xamarin, Titanium, React Native and others.

Learn More

QML & JavaScript

Qt Meta Language is a highly intuitive reactive language, which is super easy to learn, yet it's extremely powerful and flexible. Mix it with JavaScript to create awesome stuff, with just a few lines of code. QML also allows you to easily create smooth and complex animations.

import QtQuick 2.0
import VPlayApps 2.0

App {
  Page {
    
    AppButton {
      anchors.centerIn: parent
      text: "Press Me"
      onClicked: {
        console.debug("Wow you pressed me!")
      }
    }
  }
}

Learn More

Monetize & Analyze

With V-Play, you can use many 3rd party services for ads, in-app purchases, analytics and more, with just a few lines of code. All of these plugins work cross-platform, which allows you to maintain a single code base.

Learn More

Native Sensors & More

V-Play Apps harness the power of Qt, the leading cross-platform development framework used by over 1,000,000 developers.

This gives your access to native device features like sensors, camera, file system as well as multimedia, networking, localization and much more.

Learn More

Responsive Design

V-Play has built in responsive design capabilities, you can target phones and tablets with the same source code.

Learn More

Highly Extensible

You have existing JavaScript, C++ or native code? You want to add any 3rd party SDK that we do not offer already?

No worries, you can add any JS, C++, Java or Objective-C code to your project.

Learn More

Component Showcase App shows the most important V-Play features and components

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/showcase/Showcase.pro

Qt World Summit Conference App a full-featured conference management app made by V-Play

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/qtws2016/QtWS2016.pro

Twitter App how to build layouts like in the official Twitter app for iOS and Android

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/twitter/Twitter.pro

Maps App displays free bikes or boxes at bike stations for Vienna's bike sharing service Citybike Wien

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/maps/Maps.pro

Messaging App demonstrates how to create the UI of a Facebook Messenger like app

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/messaging/Messaging.pro

Weather App how to include powerful animations into your user interface

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/waether/Weather.pro

Any other Idea? let us know how we can help you

You are looking for another app demo?

The V-Play SDK includes many open-source demos for different app types. You can use their source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play..

If you do not find your app type in this list and wonder if V-Play is the right choice, just contact us, we are happy to help!

Contact Us