Bazaar In-App Billing

Bazaar In-app Billing for Unity3d

In order to provide In-app billing for Unity3d, Bazaar used SOOMLA which helps game developers to easily create their in-game economy. You can check SOOMLA's github and knowledge base for more information. Also please join Bazaar group in order to be notified upon any modification or news about Bazaar's Unity In-app billing. 

Economy Model

SOOMLA's unity3d-store provides a complete data model implementation for virtual economies. Every game economy has currencies, packs of currencies that can be sold, and items that can be sold either for money or in exchange for other items. And these are just the very basics, of course.

We recommend that you also read SOOMLA Economy Model and Economy Model & Operations where you will find more detailed explanations for each of the different entities.

Soomla's Economy Model

Virtual Items

Almost every entity in your virtual economy will be a Virtual Item. There are many types of Virtual Items and you can select the ones that fit your needs. Each one of the various types extends the class VirtualItem and adds its own behavior.

Almost all VirtualItems are PurchasableVirtualItems. Among other features, all Virtual items have 2 functions to help you easily interact with them: give and take. Preferably, you should use the two methods provided in StoreInventory for these purposes, called giveVirtualItem and takeVirtualItem. Use these functions to give or take from your users a specific amount of a specific Virtual Item.

Use giveVirtualItem when you want to give your user something and get nothing in return. (If you want to give something and get something in return, you need to use buy). Use takeVirtualItem when you want to take something from your user.

Every virtual item has an itemId, a unique string that we use to identify the different items.

Purchase Types

As stated above, almost all Virtual Items are purchasable, or as we call them, PurchasableVirtualItems. The only one that isn’t purchasable is VirtualCurrency, and we’ll get to why that is later on in this document. Every PurchasableVirtualItem has the function buy that performs a purchase of a virtual item according to a given purchase type. There are 2 different purchase types: PurchaseWithVirtualItem and PurchaseWithMarket.

PurchaseWithVirtualItem

Any item with purchase type PurchaseWithVirtualItem can be purchased with any VirtualItem, like a sort of trade. When creating an instance of PurchaseWithVirtualItem, you need to provide the ID of the virtual item that you want to be paid with and the amount of that virtual item.

PurchaseWithMarket

This kind of PurchaseType should be attached to items that you want to make available for purchase in ‌Bazaar for real money. When you create an instance of PurchaseWithMarket, you need to define the associated VirtualItem in the Market, and insert the product ID of the item into the SOOMLA code (in your version of ).

VirtualCurrency

Every game that has an economy has at least one VirtualCurrency. Use this class to define your game's virtual currency.

VirtualCurrency is NOT a PurchasableVirtualItem. This is because in game stores, you never buy just a single "Gold Coin" or a "Muffin", but rather you buy a pack of them. Your users will be able to buy packs of your game’s VirtualCurrency by using VirtualCurrencyPack which is explained below.

If for some reason you want to sell a single “Gold Coin” or a single “Gem” you can do so by providing a VirtualCurrencyPack with one Coin or one Gem.

VirtualCurrencyPack

As we mentioned above, in game stores you never buy just a "Gold Coin" or a "Muffin", you always buy a pack of the game's VirtualCurrency. This class represents exactly that: a pack of VirtualCurrency. Use this class to define various currency packs in your game.

VirtualGoods

Every virtual good is a PurchasableVirtualItem. You can buy it with other VirtualItems, or in the market with money. Virtual goods are the heart of every virtual economy. These are the game objects you’re going to want to sell in your game's store.

Every virtual good belongs to one of the following groups:

  1. Single Use
  2. Single Use Pack
  3. Lifetime
  4. Equippables
  5. Upgradables

For a detailed descriptions of each category please refer to here and here.

Other Objects

VirtualCategory

VirtualCategory is used to categorize VirtualGoods. For Example: Your game can have categories of virtual goods like: "Power Ups", "Fruits", "Swords", "Hats" ...

MarketItem

MarketItem is a representation of an item in Bazaar. MarketItem is only used for PurchaseWithMarket purchase type.

You have to define MarketItems in Bazaar. Don't forget that.

A word about StoreInfo

On runtime, StoreInfo keeps all the virtual items. You can query it for the different virtual items using their itemIds.

Debugging

If you want to see full debug messages from android-store and ios-store you just need to check the box that says "Debug Messages" in the SOOMLA Settings. Unity debug messages will only be printed out if you build the project with Development Build checked.

Getting Started

  1. Download the Bazaar unitypackage and double-click on it. It'll import all the necessary files into your project.
  2. Drag the "StoreEvents" and "CoreEvents" Prefabs from ../Assets/Soomla/Prefabs into your scene. You should see it listed in the "Hierarchy" panel. [This step MUST be done for unity3d-store to work properly]
  3. On the menu bar click "Window -> Soomla -> Edit Settings" and change the value for "Soomla Secret" (also setup Public Key if you're building for Bazaar or Google Play):
    • Soomla Secret - is an encryption secret you provide that will be used to secure your data. (If you used versions before v1.5.2 this secret MUST be the same as Custom Secret)

    Choose the secret wisely. You can't change them after you launch your game!

    • Public Key - is the public key given to you from Bazaar or Google. (iOS doesn't have a public key).
  4. Create your own implementation of IStoreAssets in order to describe your specific game's assets (example). Initialize SoomlaStore with the class you just created:

    SoomlaStore.Initialize(new YourStoreAssetsImplementation());
    Initialize SoomlaStore ONLY ONCE when your application loads.
    Initialize SoomlaStore in the "Start()" function of a 'MonoBehaviour' and NOT in the "Awake()" function. SOOMLA has its own 'MonoBehaviour' and it needs to be "Awakened" before you initialize.
  5. You'll need an event handler in order to be notified about in-app purchasing related events. refer to the Event Handling section for more information.

And that's it! You have storage and in-app purchasing capabilities... ALL-IN-ONE.

What's next? In App Purchasing.

Soomla figured out many ways you can let your users purchase stuff in your game and they designed the new modelV3 to support 2 of them: PurchaseWithMarket and PurchaseWithVirtualItem.

PurchaseWithMarket is a PurchaseType that allows users to purchase a VirtualItem with Bazaar or Google Play or the App Store.
PurchaseWithVirtualItem is a PurchaseType that lets your users purchase a VirtualItem with a different VirtualItem. For Example: Buying 1 Sword with 100 Gems.

In order to define the way your various virtual items (Goods, Coins ...) are purchased, you'll need to create your implementation of IStoreAsset (the same one from step 4 in the "Getting Started" above).

Here is an example:

Lets say you have a VirtualCurrencyPack you call TEN_COINS_PACK and a VirtualCurrency you call COIN_CURRENCY:

VirtualCurrencyPack TEN_COINS_PACK = new VirtualCurrencyPack(
"10 Coins", // name
"A pack of 10 coins", // description
"10_coins", // item id
10, // number of currencies in the pack
COIN_CURRENCY_ITEM_ID, // the currency associated with this pack
new PurchaseWithMarket("com.soomla.ten_coin_pack", 1.99)
);

Now you can use StoreInventory to buy your new VirtualCurrencyPack:

StoreInventory.buyItem(TEN_COINS_PACK.ItemId);

And that's it! unity3d-store knows how to contact Bazaar or Google Play or the App Store for you and will redirect your users to their purchasing system to complete the transaction. Don't forget to subscribe to store events in order to get the notified of successful or failed purchases (see Event Handling).

Storage & Meta-Data

When you initialize SoomlaStore, it automatically initializes two other classes: StoreInventory and StoreInfo:  

  • StoreInventory is a convenience class to let you perform operations on VirtualCurrencies and VirtualGoods. Use it to fetch/change the balances of VirtualItems in your game (using their ItemIds!)
  • StoreInfo is where all meta data information about your specific game can be retrieved. It is initialized with your implementation of IStoreAssets and you can use it to retrieve information about your specific game.

The on-device storage is encrypted and kept in a SQLite database. SOOMLA is preparing a cloud-based storage service that will allow this SQLite to be synced to a cloud-based repository that you'll define.

Example Usages

  • Get VirtualCurrency with itemId "currency_coin":

    VirtualCurrency coin = (VirtualCurrency) StoreInfo.GetItemByItemId("currency_coin");
    
  • Give the user 10 pieces of a virtual currency with itemId "currency_coin":

    StoreInventory.GiveItem("currency_coin", 10);
    
  • Take 10 virtual goods with itemId "green_hat":

    StoreInventory.TakeItem("green_hat", 10);
    
  • Get the current balance of green hats (virtual goods with itemId "green_hat"):

    int greenHatsBalance = StoreInventory.GetItemBalance("green_hat");
    

Event Handling

SOOMLA lets you subscribe to store events, get notified and implement your own application specific behavior to those events.

Your behavior is an addition to the default behavior implemented by SOOMLA. You don't replace SOOMLA's behavior.

The 'Events' class is where all event go through. To handle various events, just add your specific behavior to the delegates in the Events class.

For example, if you want to 'listen' to a MarketPurchase event:

StoreEvents.OnMarketPurchase += onMarketPurchase;

public void onMarketPurchase(PurchasableVirtualItem pvi, string payload, Dictionary<string, string> extra) {
// pvi is the PurchasableVirtualItem that was just purchased
// payload is a text that you can give when you initiate the purchase operation and you want to receive back upon completion
// extra will contain platform specific information about the market purchase.
// Android: The "extra" dictionary will contain "orderId" and "purchaseToken".
// iOS: The "extra" dictionary will contain "receipt" and "token".

// ... your game specific implementation here ...
}

NOTE: One thing you need to notice is that if you want to listen to OnSoomlaStoreInitialized event you have to set up the listener before you initialize SoomlaStore. So you'll need to do:

StoreEvents.OnSoomlaStoreInitialized += onSoomlaStoreInitialized;

before

Soomla.SoomlaStore.Initialize(new Soomla.Example.MuffinRushAssets());

 For a complete example of event handling see this file.