Premium Content Methods

The Premium Content service provides the tools needed for a game developer to sell products and verify purchases within their games. Armor Games currently supports two product types: Unlockables and Consumables.

  • Unlockable products - player buys item once, can access forever.
  • Consumable products - player buys finite quantity which are consumed during game play.

The Armor Games team does the initial product setup for developers. This includes creating new products, associating marketing assets, and setting prices. Once setup, developers can use the following methods to interact with the Premium Content service.

To get started selling products within your game, please contact tasselfoot@armorgames.com.

showStorefront(sku)

Displays the HTML Storefront modal window atop the game. This window displays product information and purchase options to the user. The user can choose to purchase a product or simply close the Storefront window.

The developer has basic control over what is displayed in the HTML Storefront modal window depending on the params object provided. For example, if a product SKU is provided then the Storefront will only list the product for the given SKU. If the SKU is omitted, then all active products for the game will be displayed.

ag.showStorefront('2wa-product');
ag.showStorefront();

setPurchaseHandler(callback)

Method will be invoked when storefront is closed.

ag.setPurchaseHandler(function(event, eventName, payload) { ... });

The incoming parameters for the above callback:

  • event - The jQuery/DOM event object. Note that your game may have limited access to this object's parameters due to cross-origin security enforced by the browser.
  • eventName - A string mapping to the type of event - generally one of the following:
    • cancelPurchase
    • completePurchase
  • payload - An object with the resulting purchase information (which may vary depending on if it's an unlockable or consumable product):
    • is_consumable (bool)
    • purchase_quantity (string, but contains an int)
    • sku (string)
    • sku_base (string)

Warning

A common issue we see is game developers performing a JSON.stringify() call on the event parameter for debugging and logging purposes. This will cause the browser to throw a security error due to limited access to some of the object's parameters (as noted earlier).

retrievePurchases()

Retrieve all purchases made by the user. The return is an array of all products available to the game, and each element of the array has two objects, "product" and "purchase". "Product" contains details about the product itself, and "purchase" has details about the user's purchase or lack of purchase.

For instance, you can check: response.purchase.success (boolean) to see if the user has purchased the product. If it's a consumable, you can check response.purchase.data (int) to see how many they currently have of that consumable.

ag.retrievePurchases().then(function(response) {
  for (var index in response) {
    if (response[index].purchase.success) {
      console.log('You have purchased ' + response[index].product.name + '!');
    }
  }
});

retrievePurchase(sku)

Retrieve a single purchase made by the user.

ag.retrievePurchase('2wa-cookies').then(function(response) {
  // var remaining = response.purchase.data;
});

consume(sku, quantity)

The consume method will decrease a user’s item quantity by the given amount for the provided product SKU. 

ag.consume('2wa-cookies:20', 1).then(function(response) {
  // Product "2wa-cookies:20" should be decremented by 1
  // var remaining = response.purchase.data;
});