Monetising your Game with In-App Purchases

Welcome to the Facebook Instant Games SDK Tutorials. This series of tutorials covers many aspects of using the Facebook Instant Games SDK.

In this tutorial we will take a look at earning money from your game with in-app purchases using the Facebook Instant Games SDK.

Introduction

Facebook Instant Games allows you to sell virtual products to your users on the Android and Web platforms (iOS is not currently supported).
In order to earn money from in-app purchases you must have created a verified business on Facebook. See https://www.facebook.com/business/help/1710077379203657 for details.

You can add products to the In App Purchases section of the Instant Games product in the developer dashboard. Here you can specify product ID’s, names, descriptions, price and icons associated with your virtual products.

Note that you will also have to submit your in-app purchases for review in the review section of instant games. Do not launch your game until IAP’s have also been approved as they may not work.
Also note that users that have been added to the Testers section in the In App Purchases section of Instant games will not be charged for purchases, which is useful for testing.

Checking for Support

Before attempting to make any purchases in-game its best to check that in-app purchasing is available. You can do this by querying support by calling FBInstant.getSupportedAPIs():
[sourcecode language=”js”]
var supportedAPIs = FBInstant.getSupportedAPIs();
if (supportedAPIs.includes("payments.purchaseAsync"))
purchasingSupported = true;
[sourcecode language="js"]
Once you know that you have support you can begin working with in-app purchases.

You also need to ensure that payments are ready before using the API. You do this by subscribing to the payments.onReady event:
[sourcecode language="js"]
FBInstant.payments.onReady(function() {
// Payments are ready
});
[/sourcecode]

Getting Products

You can retrieve a list of your products and their details by calling FBInstant.payments.getCatalogAsync():
[sourcecode language=”js”]
FBInstant.payments.getCatalogAsync().then(function(catalog)
{
// catalog contains an array of products
}).catch(function(err) {
// There was an error
});
[/sourcecode]

Each product has the following properties:

  • title string Product title
  • productID string Product ID
  • description string? Product description
  • imageURI string? A link to the products icon
  • price string Product price
  • priceCurrencyCode string Currency code for the product

Buying Products

You can allow the user to make a purchase of a specific item by calling FBInstant.payments.purchaseAsync():
[sourcecode language=”js”]
FBInstant.payments.purchaseAsync(
{
productID: product_id,
developerPayload: payload,
}).then(function(purchase)
{
// Purchase success (purchaseToken is available in purchase)
}).catch(function(err) {
// Purchase failed
});
[/sourcecode]

When you make the call to purchaseAsync() the user is displayed a native dialog which shows the product summary. The user can at this point choose to accept or cancel the purchase. If the user cancels the purchase then purchaseAsync() will return with an error.

Consuming Purchases

Once a purchase has been made it is classed as unconsumed. To consume a product you can call FBInstant.payments.consumePurchaseAsync():
[sourcecode language=”js”]
FBInstant.payments.consumePurchaseAsync(purchase_token)
.then(function()
{
// Product consumed
}).catch(function(e) {
// Error occurred
});
[/sourcecode]
purchase_token is returned by FBInstant.payments.purchaseAsync() as part of the purchase.

Getting Consumed Products

Products are by default unconsumed which means that the player still owns the products until they have been used. This is good for none consumable items such as extra game levels. Other products however such as currency are consumable and used as the player plays. The best way that I have found to deal with consumable products such as currency is to consume them straight after purchase. You can get a list of consumable products by calling FBInstant.payments.getPurchasesAsync():
[sourcecode language=”js”]
FBInstant.payments.getPurchasesAsync().then(function(purchases)
{
// purchases contains the list of unconsumed purchases
}).catch(function(error) {
// Error occurred
});
[/sourcecode]

Each purchase has the following properties:

  • developerPayload string? A developer-specified string, provided during the purchase of the product
  • paymentID string Purchase transaction ID
  • productID string Product ID
  • purchaseTime string Unix timestamp of purchase time
  • purchaseToken string A purchase token representing the purchase, can be used to consume the purchase
  • signedRequest SignedPurchaseRequest Server signed encoding of the purchase request

Leave a Reply