This project is a part of The SOOMLA Project which is a series of open source initiatives with a joint goal to help mobile game developers get better stores and more in-app purchases.

Haven't you ever wanted an in-app purchase one liner that looks like this ?!

    cocos2dx_StoreController::buyMarketItem("[itemId]");

The new Virtual Economy model V3 is merged into master. The new model has many new features and it works better than the old one. Old applications may break if they use in this new model so already published games with android-store from before May 1st, 2013 needs to clone the project with tag 'v2.2' and not 'v3.0'.

The cocos2dx-store shows you how to use The SOOMLA Project's android-store and ios-store in your cocos2d-x project. In cocos2dx-store there are 3 relevant scenes: MainScene, StoreAScene and StoreBScene: MainScene - the welcome scene from where you open the store. StoreAScene - the store's first window that contains a list of VirtualGoods. StoreBScene - the store's second window that contains a list of VirtualCurrencyPacks.

We suggest that you go over the information on ios-store and android-store:

• ios-store project wiki
• android-store project wiki

If you also want to create a storefront you can do that using SOOMLA's Store Designer.

In order to run the iOS and Android projects you'll need to recursively clone cocos2dx-store:

git clone --recursive git@github.com:soomla/cocos2dx-store.git

The Android project is an IntelliJ project. Just open the folder cocos2dx-store/cocos2dx-store/proj.android from IntelliJ to use it.

The first thing you should do is go to StoreConfig.java (Android) and StoreConfig.m (iOS) and change the value for the variable SOOM_SEC. Do this now! This value is set once and cannot be changed after you publish you game.

StoreController is initialized through cocos2dx_StoreController class. initialize is called with another secret. This secret is also unchangeable and its purpose is to provide more security to your game's data. This value is set once and cannot be changed after you publish you game.

You'll need to initialize StoreController ONLY once from AppDelegate::applicationDidFinishLaunching (example).

If you're building your cocos2dx application for the iOS platform, open our xCode project and see how to integrate it with ios-store. The example ios project needs to be enough, but if you want more info then this is what's relevant to you:

1. You'll have to create your implementation of IStoreAssets that will represent the assets in your specific game. We created an IStoreAssets implementation for an imaginary game called Muffin Rush and we called it MuffinRushAssets.
2. We've created our cocos2dx UI in cocos2dx-store/Classes. You don't need these files. Just look into AppDelegate.cpp and see where we initialize cocos2dx_StoreController and do the same in your game.
3. You'll need ONLY the HEADER files from cocos2dx-store/Classes/StoreBridge to be included in your game's iOS project. (EXCEPT for JniHelpers.h !)
4. From cocos2dx-store/ios, copy the following files into your iOS project: cocos2dx_StoreController.mm, cocos2dx_StoreInfo.mm, cocos2dx_StoreInventory.mm, iOSHelper.mm, iOSHelper.h.
5. In the above Getting Started, we mentioned you need to recursively clone cocos2dx-store. By doing that you also cloned ios-store into the 'submodules' folder. Make sure you add the folder 'SoomlaiOSStore' from ios-store into your project.
6. Make sure you go over ios-store Getting Started for more instructions. For example: make sure you add '-fno-objc-arc' to the source JSONKit.m in Build Phases.

If you're building your cocos2dx application for the Android platform, open our IntelliJ project from cocos2dx-store/proj.android and see how to integrate it with android-store. The example Android project needs to be enough, but if you want more info then this is what's relevant to you:

1. You'll have to create your implementation of IStoreAssets that will represent the assets in your specific game. We created an IStoreAssets implementation for an imaginary game called Muffin Rush and we called it MuffinRushAssets.
2. We've created our cocos2dx UI in cocos2dx-store/Classes. You don't need these files. Just look into AppDelegate.cpp and see where we initialize cocos2dx_StoreController and do the same in your game.
3. You'll need an Android.mk similar to the one under the proj.android/jni folder.
4. Look into Application.mk and see how we added '-fexceptions' to 'APP_CPPFLAGS'.
5. From cocos2dx-store/android.proj, copy the folder 'com' into your project's 'src' folder. (you can remove the subfolder 'example')
6. In the above Getting Started, we mentioned you need to recursively clone cocos2dx-store. By doing that you also cloned android-store into the 'submodules' folder. Make sure you add the folder 'SoomlaAndroidStore/src' from android-store into your classpath as a source folder.
7. Make sure you go over ios-store Getting Started for more instructions.

android-store and ios-store provides you with VirtualCurrencyPacks. VirtualCurrencyPack is a representation of a "bag" of currency units that you want to let your users purchase in Google Play or App-Store. You define VirtualCurrencyPacks in your game specific assets file which is your implementation of IStoreAssets (examples: android ios). After you do that you can use cocos2dx-store to call cocos2dx_StoreController to make actual purchases and android-store or ios-store will take care of the rest.

Example:

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

VirtualCurrencyPack TEN_COINS_PACK = new VirtualCurrencyPack(
        "10 Coins",                // name
        "A pack of 10 coins",      // description
        "10_coins",                // item id
        TEN_COINS_PACK_PRODUCT_ID, // product id in Google Market
        1.99,                      // actual price in $$
        10,                        // number of currency units in the pack
        COIN_CURRENCY);            // the associated currency

VirtualCurrencyPack* TEN_COINS_PACK = [[VirtualCurrencyPack alloc] initWithName:@"10 Coins"
                                              andDescription:@"A pack of 10 coins"
                                                   andItemId:@"10_coins"
                                                    andPrice:0.99
                                                andProductId:TEN_COINS_PACK_PRODUCT_ID
                                           andCurrencyAmount:10
                                                 andCurrency:COIN_CURRENCY];

Now you can use cocos2dx_StoreController to call the in-app purchasing mechanism:

This is a full example that shows you how to do everything from the click event handler to the actual purchase and event handling. You can find the full example here.

void StoreScene::menuChooseCallback(CCObject* pSender)
{
    if (pSender)
    {
		GameMenuItem* item = (GameMenuItem*)pSender;

		int tag = item->getTag();
		char productId[512];
		snprintf(productId, sizeof(productId), productIdFromTag(tag).c_str());
		try{
			if (tag == 0) {

			} else {
				cocos2dx_StoreController::buyMarketItem(productId);
			}
		}
		catch (cocos2dx_VirtualItemNotFoundException& e) {
#if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
			__android_log_write(ANDROID_LOG_ERROR, "SOOMLA JNI", "Caught cocos2dx_VirtualItemNotFoundException from NATIVE!");
#elif (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)
            iOSHelper::LogMessage("Caught cocos2dx_VirtualItemNotFoundException!");
#endif
		}
	}
}

And that's it! android-store and ios-store knows how to contact Google Play and the App Store for you and redirect the user to the purchasing mechanism. IMPORTANT: Don't forget to handle in cocos2dx_EventHandler.cpp in order to get the events of successful or failed purchases.

When you initialize cocos2dx_StoreController, ios-store and android-store automatically initializes two other classes: StorageManager and StoreInfo which makes 2 cocos2dx classes relevant:

• cocos2dx_StoreInventory is used to access all storage related instances in your game. Use it to access tha balances of virtual currencies and virtual goods (usually, using their itemIds).
• cocos2dx_StoreInfo is the mother of all meta data information about your specific game. ios-store and android-store initializes StoreInfo with your implementation of IStoreAssets so you can use cocos2dx_StoreInfo 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. Stay tuned... this is just one of the goodies we prepare for you.

Example Usages

Add 10 coins to the virtual currency with itemId "currency_coin":

string itemId("currency_coin");
cocos2dx_StoreInventory::addCurrencyAmount(itemId, 10);

Remove 10 virtual goods with itemId "green_hat":

string itemId("green_hat");
cocos2dx_StoreInventory::removeGoodAmount(itemId, 10);

Get the current balance of green hats (virtual goods with itemId "green_hat"):

string itemId("green_hat");
int balance = cocos2dx_StoreInventory::getCurrencyBalance(itemId);

Make sure you handle the appropriate exceptions when using any cocos2dx_* class. Look in the header files in ../Classes/StoreBridge to see what exceptions are thrown.

We want you!

Fork -> Clone -> Implement -> Test -> Pull-Request. We have great RESPECT for contributors.

• Website
• On Facebook.
• On AngelList

MIT License. Copyright (c) 2012 SOOMLA. http://project.soom.la

• http://www.opensource.org/licenses/MIT