Swarm Documentation API Reference

Adding a Swarm Store to your App

Estimated Integration Time: 30 minutes

The Swarm Store provides an easy way to monetize your app through selling virtual goods to your users. Virtual goods can be anything you want, from removing an advertisement banner in a free app to the sale of a new sword that can be used to fight off enemies.

Purchasing items can be done through Swarm's Store screens or directly in your app via a popup dialog. All purchases that a user makes are managed in the user's inventory. Items sold can be consumable (something that is destroyed on use, like a Health Potion) or non-consumable (like ad-banner removal).

When a users purchase items from your Swarm Store, you (as the developer) can earn real money based on how many Swarm Coins they spend. For more details, please read the Terms of Service (TOS) regarding Swarm Coins.

Prerequisites:


Terminology

StoreItem
An Item is something that the user can own. Items are sold to a user by using StoreItemListings (described below), and added to their inventory. An Item could be a sword, ad-removal, fish, or just about anything you can imagine.

An Item can be consumable or non-consumable. A consumable item is removed from the user's Inventory when it is used, but a non-consumable item remains in the user's Inventory when it is used. Examples of consumable items may be things like potions and food whereas examples of non-consumable items may be things like swords, hats, and ad-banner removal.

An Item can contain a Payload. A Payload is a developer-defined String of data to be delivered to the app when a user purchases an Item. Example: an array of parameters for a Sword: "damage=10, speed=5".


StoreCategory
A Category is a logical block of StoreItemListings (described below). A StoreCategory is a grouping of things to be sold together. For example, a StoreCategory could be "Weapons", "Armor", or "Hats".


StoreItemListing
A StoreItemListing is a way for you to list StoreItems in StoreCategories. For example, a StoreItemListing may contain the Item "Sword" in category "Weapons" for a price of 10 Swarm Coins.

StoreItemListings have a quantity to allow you to sell multiple of an Item in a single purchase. For example, you could choose to sell 1 Health Potion for 10 Swarm Coins or 5 Health Potions for 40 Swarm Coins.


UserInventory
Every User has a UserInventory, which keeps track of what Items they have purchased and how many of them they currently own.
If a user consumes an Item they own (such as a Health Potion), they will have 1 Health Potion removed from their inventory.


Configuring your Store

Create Items
What you sell in your store is completely up to you. For this example, we will be selling "Health Potions", which will allow a user to heal themselves in our game.

First, we must define an Item in the Swarm Admin.


Note: We have defined the Payload as the amount of health that the user should gain when the health potion is consumed.
Write down the ItemId for your Health Potion, as we will need it again soon.


Create Categories
For this example, we will just create one category called "Potions". However, you can have multiple categories in your store.



Create Listings
Next we will create two different listings. (1) Health Potion for 10 Swarm Coins.


As well as another listing for: (5) Health Potions for 40 coins (a bulk discount!)



Take note of the Id values (shown in red boxes above) for each Listing, as we will need them again soon.


Selling your Listings

Now that you have finished configuring our Store, you can start selling items to your users via the StoreItemListings. This can be done one of two ways, both of which are described below.

Sell through the Swarm Interface
You can send the user into the Swarm Store Interface, where the user can purchase things with no further setup.
Swarm.showStore(); 
Sell directly from your App
You can sell from directly inside your app as well, which provides a more seamless user experience with minimal setup. Try putting the one of the following lines inside of a Button's OnClickListener. Remember to pass in your context as the first argument and replace the IDs with the StoreItemListing IDs created earlier (in the Swarm Admin Panel)
// Prompts the user to purchase 1 potion
SwarmStoreListing.purchase(context, SINGLE_POTION_LISTING_ID);

// Prompts the user to purchase 5 potions
SwarmStoreListing.purchase(context, FIVE_POTION_LISTING_ID);
[+] Click here to see more control and customization options.


Using purchased Items

Now that your users have purchased a few items, it is time to let them use them!

Simply make a call to consumeItem. Consuming an item will reduce the quantity of the item by 1 in the user's inventory (if the user has this item in his/her inventory).
if (Swarm.isLoggedIn()) {
    Swarm.user.consumeItem(HEALTH_POTION_ITEM_ID);
    Player.life = Player.life + healAmount;
} 
(Optional) You can also easily check if the user has a specified item in his/her inventory by getting the quantity. First setup the GotItemQuantityCB callback. For more information on Swarm Callbacks, please read: callbacks.
GotItemQuantityCB healthPotionCheckCallback = new GotItemQuantityCB() {
    public void containsItem(int quantity) {
        if (quantity > 0) {
            // user has the item in his/her inventory at the specified quantity
         
        }
    }
}
Then, call getItemQuantity and pass in the callback as shown below. That's all there is to it!
if (Swarm.isLoggedIn()) {
    Swarm.user.getItemQuantity(HEALTH_POTION_ITEM_ID, healthPotionCheckCallback);
}
[+] Click here to see more control and customization options.


Congratulations!

At this point your game should have a working Store. Your users can start purchasing virtual goods from the Store, and you can start monetizing your app in a whole new way!