The Android flavor of The Open Code Project for In App Purchasing.
Pull request Compare This branch is 245 commits ahead, 982 commits behind soomla:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Welcome to The SOOMLA Project

The SOOMLA Project is a series of open-source projects that aims to help game developers get better in-app purchasing stores for their games. The open-source platform-specific projects include everything a game developer needs, from storage of virtual items to purchasing mechanisms with the various devices' native app-stores. As an optional (and currently EXPERIMENTAL) part of our open-source projects you can also get the store's layout which you can customize with your own game's assets. To use our storefront, refer to Get your own Storefront.


The android-store is a Java project that works seamlessly with Google Play's in-app purchasing API.

Check out our Wiki for more information about the project and how to use it better.

Getting Started

  1. Clone android-store. Copy all files from android-store's subfolders to their equivallent folders in your Android project:

    git clone

  2. Make the folowing changes to your AndroidManifest.xml:

    Add the following permission:

      <uses-permission android:name="" />

    Add the following code to your 'application' element:

      <service android:name="com.soomla.billing.BillingService" />
      <receiver android:name="com.soomla.billing.BillingReceiver">
              <action android:name="" />
              <action android:name="" />
              <action android:name="" />
      <activity android:name="" />
  3. Create your own implementation of IStoreAssets in order to describe your specific game's assets. Initialize StoreController with the class you just created:

                                           new YourStoreAssetsImplementation(),
                                           "YOUR PUBLIC KEY FROM GOOGLE PLAY",

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

Storage & Meta-Data

When you initialize StoreController, it automatically initializes two other classed: StorageManager and StoreInfo. StorageManager is the father of all stoaage related instances in your game. Use it to access tha balances of virtual currencies and virtual goods (ususally, using their itemIds). StoreInfo is the mother of all meta data information about your specific game. 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'll 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":

    VirtualCurrency coin = StoreInfo.getInstance().getVirtualCurrencyByItemId("currency_coin");
    StorageManager.getInstance().getVirtualCurrencyStorage().add(coin, 10);
  • Remove 10 virtual goods with itemId "green_hat":

    VirtualGood greenHat = StoreInfo.getInstance().getVirtualGoodByItemId("green_hat");
    StorageManager.getInstance().getVirtualGoodsStorage().remove(greenHat, 10);
  • Get the current balance of green hats (virtual goods with itemId "green_hat"):

    VirtualGood greenHat = StoreInfo.getInstance().getVirtualGoodByItemId("green_hat");
    int greenHatsBalance = StorageManager.getInstance().getVirtualGoodsStorage().getBalance(greenHat);


If you want to protect your application from 'bad people' (and who doesn't?!), you might want to follow some guidelines:

  • SOOMLA keeps the game's data in an encrypted database. In order to encrypt your data, SOOMLA generates a private key out of several parts of information. StoreInfo.customSecret is one of them. SOOMLA recommends that you change this value before you release your game. BE CAREFUL: You can always change this value once! If you try to change it again, old data from the database will become unavailable.
  • Following Google's recommendation, SOOMLA also recommends that you split your public key and construct it on runtime or even use bit manipulation on it in order to hide it. The key itself is not secret information but if someone replaces it, your application might get fake messages that might harm it.

Event Handling

SOOMLA lets you create your own event handler and add it to StoreEventHandlers. That way you'll be able to get notifications on various events and implement your own application specific behaviour to those events.

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

In order to create your event handler:

  1. create a class that implements IStoreEventHandler.
  2. Add the created class to StoreEventHandlers: StoreEventHandlers.getInstance().addEventHandler(new YourEventHandler());


We want you!

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

SOOMLA, Elsewhere ...


MIT License. Copyright (c) 2012 SOOMLA.