Soomla Plugin

Integrate with Soomla to offer in-app purchases and a virtual economy model within your app.

Cross-Platform In-app Purchases

The Soomla Plugin fully supports in-app purchases for iOS App Store and Android in-app products on Google Play Store & Amazon AppStore.

Simply define your in-app purchases within your existing QML code and use the same API to trigger cross-platform purchases within your games & apps.

Virtual Economy Model

The Soomla Plugin is built around a freemium virtual economy model and in-game currencies ("soft currencies").

Your users can earn virtual currency by playing certain stages within your game or by using in-app purchases to exchange it against real money.

Overview

The Soomla plugin offers in-app purchases and a virtual economy model for iOS & Android. The plugin supports Apple iOS In-App Purchase on iOS and Google Play In-app Billing or Amazon In-App Purchasing on Android.

The Soomla libraries are open-sourced and distributed under Apache 2.0 license.

Use Cases

In-app purchases are probably the most utilized monetization strategy in today's app economy. In-app purchases implemented as a Freemium model provide a great opportunity for you to get your app into people's hands for free, and then capture some revenue from their enjoyment of playing or using your game.

Some ways to use in-app purchasing for revenue streams include:

  • Removal of advertisement, removal of restrictions within the game or upgrading to a premium version of the game
  • Virtual goods (and virtual currencies) within your game
  • Extended game play or time (like new levels)
  • Tokens and badges
  • Additional and featured content

Note: The following examples of a virtual store are built around a tower defense game called Squaby. Squaby uses a virtual currency "Gold" which can be used to buy new or upgrade existing towers. Gold can be earned by stopping Squabies or by buying currency packs within the game.

Key Benefits

Using in-app purchases with our Soomla plugin has some key benefits you shouldn't miss:

  • Virtual Economy Model

    Most of today's successful mobile games use a virtual economy model, which can be seen as a special type of a freemium model. The fundamental core of every virtual economy is the existence of an in-game currency ("soft currency") that a user of your game can either earn by playing (and mostly completing) certain stages within your game or by using in-app purchases to change real money to your in-game currency with an exchange rate defined within your game. Your players can then use this virtual currency to purchase other goods within your game, i.e. to purchase additional ammo, levels or characters.

    Creating a virtual economy is not only for monetizing your game, more important it's to engage your players and giving them ways to advance in your game play, to measure their progress and to add an extra way of having fun in your game, independently from the game's actual genre.

    The V-Play Store plugin already comes with a built-in virtual economic model especially designed for games, including items for virtual currencies, currency packs, single use goods, single use pack goods and lifetime goods.

  • QML Declarative Language Features

    Thanks to the use of QML's declarative language features (especially property bindings) you can boost the integration process of in-app purchases while making logical links more transparent and comprehensible, e.g. displaying or hiding an app banner within your game depending on the purchase state of a no-ad upgrade is as simple as:

     AdBanner {
       visible: !noadsGood.purchased
     }
  • Save Time and Write Better Code

    Beside the declarative language features you can save a lot additional time while adding in-app purchases to your game thanks to a comprehensive documentation with code samples, integration into our open-sourced demo games and an export functionality that rescues you from the hassle of adding in-app purchases to different platform app stores multiple times by hand.

  • True Cross Platform

    The Store plugin is built around the same API, independent from the underlying platform, meaning that you can use the same source code for Android and iOS. This will even be true for platforms supported by V-Play Plugins added in the future.

Example Usage

To try the Soomla plugin and see an integration example have a look at the V-Play Plugin Demo app.

The Soomla plugin can be used after adding the following import statement to your QML source code:

 import VPlayPlugins 1.0

The main item for using the Soomla plugin is the Store item. Therefore every app & game utilizing in-app purchases should have at most one Store item, best added to near the root item of your QML files.

The structure of your virtual economy and purchasable types is defined with the Store::currencies, Store::currencyPacks and Store::goods properties.

A very basic Store implementation with one lifetime good item looks like the following example:

 import QtQuick 2.2
 import QtQuick.Window 2.1

 import VPlayPlugins 1.0

 Window {
   visible: true
   width: 360
   height: 360

   Store {
     id: store

     version: 1
     // Replace with your own custom secret
     secret: "vplaysecret"
     // From Google Play Developer Console, when using Google Play billing service
     androidPublicKey: ""

     goods: [
       LifetimeGood {
         id: noadsGood
         itemId: "noads_id"

         purchaseType: StorePurchase { id: noAdPurchase; productId: noadsGood.itemId; }
       }
     ]
   }
 }

Please also have a look at our plugin example project on GitHub: https://github.com/V-Play/PluginDemo

In-App Purchase Types

Following purchase type items are available:

Component Description
StorePurchase The StorePurchase item is used to offer purchases through the platform's app store.
VirtualPurchase The VirtualPurchase item allows purchases with other items like an in-game Currency.

The Store plugin comes with a built-in virtual economic model especially designed for games. Depending on the type, an item can either be purchased as a StorePurchase or as a VirtualPurchase. Purchases with StorePurchase type are mainly used for non-consumable, app-wide items and virtual currency packs. StorePurchases typically open the platform's app store and ask the user to confirm the purchase with a specific price.

Purchases with VirtualPurchase type on the other hand allow a lot more flexibility on the game's design in comparison to purchases with StorePurchase type: Instead of providing each in-game good as dedicated in-app purchase through the platform app stores you can introduce a virtual currency, which can then be used by your gamers to buy your in-game goods. This approach has a variety of advantages:

  • You can change prices for virtual goods dynamically without the need to update app store entries
  • You can reward your users with single virtual goods or an additional currency amount without opening the platform app stores

Virtual Goods and Currencies

Virtual goods are the core of every virtual economy. Virtual goods are game objects within your game you want to sell to your players. The Store plugins comes with different types of virtual goods, including virtual currencies and different purchase types for different needs within a game. The different types are described in more detail below.

Following good and currency items are available:

Component Description
Currency The Currency item describes a single virtual currency you want to offer within your game.
CurrencyPack The CurrencyPack item describes a purchasable collection of a specific virtual Currency within your game, buyable with StorePurchase.
SingleUseGood The SingleUseGood item is a consumable good item with a specific balance.
SingleUsePackGood The SingleUsePackGood item describes a purchasable collection with a specific amount of a specific SingleUseGood.
LifetimeGood The LifetimeGood item can be used to offer items which are available as long as a player plays the game as a one-time purchase, purchasable either with virtual Currency or as a StorePurchase.

Currencies and Currency Packs

Virtual currencies are used to provide a currency like coins or credits within your game play. Currencies can be purchased in volume (bundled within a CurrencyPack) by your players with a purchase type of StorePurchase.

Your game needs at least one Currency and one CurrencyPack defined in order to offer a virtual economy.

A simple example for a currency (named "Gold") and a purchaseable currency pack (named "10 Pieces of Gold") looks like the following:

 Store {
   currencies: [
     Currency { id: goldCurrency; itemId: "currency_gold_id"; name: "Gold"; }
   ]

   currencyPacks: [
     CurrencyPack {
       id: gold10Pack
       itemId: "gold_pack_10_id"
       name: "10 Pieces of Gold"
       currencyId: goldCurrency.itemId // The currency you want to use for this pack
       currencyAmount: 10
       purchaseType:  StorePurchase { id: gold10Purchase; productId: gold10Pack.itemId; }
     }
   ]
 }

Note: The virtual economic model allows to define multiple currencies within the same game. However, in most cases a single virtual currency should be sufficient.

Single Use Good Items

A SingleUseGood item is the most basic kind of a virtual good. It is a virtual item that a player can only use once before he has to purchase more of the same kind again. SingleUseGood items can be purchased an unlimited number of times. These goods can normally be summed up and accumulated so that the user has a balance of them (e.g. 20 green balls). The balance of every virtual item is saved within an internal database and can be retrieved with SingleUseGood::balance property. Single use goods are commonly purchased with a virtual currency with the VirtualPurchase type.

A simple example for an additional one time usage weapon for a tower defense game looks like the following:

 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; }
     }
   ]
 }

Single Use Pack Good Items

In certain cases it's desirable to sell packs of single use goods, which can be achieved with SingleUsePackGood items. Therefore SingleUsePackGood items are just bundles of SingleUseGood items. Beside selling bundles of goods you can also use these items to give a discount on items purchased in volume, i.e. purchasing a truck of green bananas might in sum be cheaper than purchasing each single banana on its own.

SingleUsePackGood items can be purchased an unlimited number of times. This kind of item does not have an own balance, instead the balance of the associated SingleUseGood is updated according to the amount defined in the pack.

A simple example for an additional one time usage weapon for a tower defense game looks like the following:

 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; }
     },
     SingleUsePackGood {
       id: vacPackGood
       itemId: "vacpack_item_id"
       name: "5 Vacuum Cleaners"
       goodItemId: vacGood.itemId
       amount: 5
       purchaseType: VirtualPurchase { itemId: goldCurrency.itemId; amount: 200; }
     }
   ]
 }

Lifetime Good Items

In comparison to single use good items lifetime good items are virtual goods that are available for the playerer as long as he plays the game. So a LifetimeGood allows you to offer virtual goods that are bought only once and then kept forever. Furthermore your users can't buy more than one instance of the very same lifetime good item.

If your lifetime good is of type StorePurchase it can be restored with Store::restoreAllTransactions.

Race tracks, Game Upgrades and Buildings are good examples of Lifetime use Goods.

A simple example for a life time good looks like the following:

 Store {
 goods: [
     LifetimeGood {
       id: slowmotionGood
       itemId: "slowmotion_item_id"
       name: "Slow Motion"
       description: "Squabies move with less speed"
       purchaseType:  VirtualPurchase { itemId: goldCurrency.itemId; amount: 300; }
     }
   ]
 }

Further examples are no-ad upgrades or the removal of game restrictions of a free version of your game when using the StorePurchase purchase type. Here is an example for an in-app purchase for removing a possible app banner:

 Store {
   goods: [
     LifetimeGood {
       id: noadsGood
       itemId: "noads_id"

       purchaseType: StorePurchase { id: noAdPurchase; productId: noadsGood.itemId; }
     }
   ]
 }

Available QML Items

Currency

Item describes a single virtual currency you want to offer within your game

CurrencyPack

Item describes a purchasable collection of a specific virtual Currency within your game, buyable with StorePurchase

LifetimeGood

Item can be used to offer items which are available as long as a player plays the game

SingleUseGood

Item is a consumable good item with a specific balance

SingleUsePackGood

Item describes a purchasable collection with a specific amount of a specific single use good

Store

Item provides in-app purchases for iOS and Android

StorePurchase

Item is used to offer purchases through the platform's app store

VirtualPurchase

Item allows purchases with other items like an in-game Currency

Integration

iOS Integration Steps

  1. Download our PluginDemo from https://github.com/v-play/PluginDemo/archive/master.zip and unzip it.
  2. Copy libSoomlaiOSCore.a and libSoomlaiOSStore.a from the ios subfolder to a sub-folder called ios within your project directory.
  3. Add the following lines of code to your .pro file:
     ios {
       VPLAY_PLUGINS += soomla
     }

Android Integration Steps

  1. Open your build.gradle file and add the following lines to the dependencies block:
     dependencies {
       compile 'net.vplay.plugins:plugin-soomla:2.+'
     }

    Note: If you did not create your project from any of our latest wizards, make sure that your project uses the Gradle Build System like described here.

  2. You can choose between two in-app purchasing billing services on Android, either Google Play or Amazon.

    Open the AndroidManifest.xml file and add the following lines as children of the <application> element to use Google Play:

     <meta-data android:name="billing.service" android:value="google.GooglePlayIabService" />

    Open the AndroidManifest.xml file and add the following lines as children of the <application> element to use Amazon:

     <meta-data android:name="billing.service" android:value="amazon.AmazonIabService" />

    Note: You can only choose one billing service.

Used Soomla SDK Versions

iOS 3.6.9
Android 3.6.11

Set-up & Test In-App Purchases

Testing your in-app purchases requires you app to be signed with a distribution certificate and that all purchases are successfully set up in the corresponding app store.

Note: Make sure that you already added your own Store item implementation to your project before proceeding with the following steps for testing in-app purchases.

In-App Purchases in iOS App Store

Preparing iOS In-App Purchases

  1. Log in to iTunes Connect and create a new iOS app or open the overview page of an existing one.

    Note: Make sure to use an app with an explicit App ID (with in-app purchases enabled), otherwise purchases can't be used for your app.

  2. Click the "Manage In-App Purchases" button and create your in-app purchases according to the purchasable items with type StorePurchase defined in your Store item in your QML code.

    Items of type CurrencyPack (and probably SingleUseGood, SingleUsePackGood and LifetimeGood if defined with VirtualPurchase type) are typically defined as consumable items, items of type LifetimeGood with StorePurchase purchase type are typically defined as non-consumable items.

    Note: You can also make use of Store::printStoreProductLists which makes creating the in-app purchases a lot easier.

    For more information on how to create and configure your app's products in iTunes Connect please have a look at the official In-App Purchase Configuration Guide for iTunes Connect.

Testing iOS In-App Purchases

Testing in-app purchases on iOS requires you to sign the app with a valid development certificate and an explicit development provisioning profile which is enabled for in-app purchases for your given app identifier. You can create one at the Apple Developer Portal here.

As soon as you have a valid provisioning profile you can proceed with the following steps:

  1. Before running your app you need a valid test account which can be retrieved from iTunes Connect. Open iTunes Connect, select the "Manage Users" option and click "Test User". Enter the required information and save the settings.
  2. You also need to clean any production account information stored on your test device by opening "Settings" and tap "Sign Out" on the "iTunes & App Store" settings screen. This prevents an actual production user account from automatically being used when testing.

    Note: Make sure to log out from a test user account after testing your app again, if you try to use a test account for the production App Store the test user account automatically gets invalid.

  3. As soon as your test user(s) and Qt 5 project is ready for testing in-app purchases open your iOS shadow build directory and open the generated Xcode project.
  4. Open the project settings by clicking on your project in the upper left corner, select your target (named after your project) and open the tab "Build Settings" tab. Search for the entry "Provisioning Profile" and select your app's development provisioning profile.

    Note: Please also make sure that "iOS Device" (or the name of your device if you already connected it) target is selected in the upper left corner of Xcode like illustrated above.

  5. Run your app from Xcode and test your in-app purchases. When asked for your credentials enter the newly created test user from iTunes Connect.

    Note: All pop-ups should display a "sandbox" hint while you are in testing mode.

For more information on testing in-app purchases on iOS please have a look at the official Testing In-App Purchase Products guide.

Further Reading

For more information on in-app purchases on iOS please have a look at the official In-App Purchase Programming Guide.

In-App Purchases in Google Play Store

Preparing Google Play In-App Purchases

  1. Log in to Google Play Developer Console and create a new app or open the overview page of an existing one.
  2. Upload a new draft app signed with your distribution certificate which includes the "BILLING" permission in its AndroidManifest.xml file.
  3. Switch to the section "In-app Products" and create your in-app purchases according to the purchasable items with type StorePurchase defined in your Store item in your QML code.

    Choose "managed" product as the type for your goods. "Managed" products can only be bought once, and only be bought again if they are consumed. For goods like CurrencyPack or SingleUseGood, we typically want to be able to buy them multiple times. For this, the Soomla plugin immediately consumes the good and remembers total amount locally.

    Note: You can also make use of Store::printStoreProductLists which makes creating the in-app purchases a lot easier.

  4. Open the "Services & APIs tab of your newly uploaded application and copy the license key. Paste it as Store::androidPublicKey property within your Store item.

    For more information on how to create and configure your app's products in Google Play Developer Console please have a look at the official Administering In-app Billing guide.

Testing Google Play In-App Purchases

Testing in-app purchases on Google Play requires you to sign the app with the distribution certificate and upload it to Google Play as alpha or beta release. You also need to add your app's license key as Store::androidPublicKey property like described above.

For more information on testing in-app purchases on Google Play please have a look at the official Testing In-app Billing guide.

Further Reading

For more information on in-app purchases on Google Play please have a look at the official In-app Billing Overview guide.

Videos

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