How to do In-App Purchases
In this exercise we'll cover a few different scenarios around purchasing. We'll look at:
- Setting up a Virtual Good to be purchased using a Virtual Currency.
- Checking the purchase of the Virtual Good as an authenticated player in the Test Harness.
- How you set up your Virtual Goods so you can also do purchases through third-party stores (Google Play, iOS App Store, Windows Store).
Creating and Configuring Game Currencies
Before you set up your Virtual Goods for purchasing with virtual currencies, you can create and configure currencies for your game.
Default Game Currencies? You can also use the default game currencies you have enabled for your game in Game Overview>Edit for pricing your Virtual Goods. However, in this tutorial we'll work with the custom Currencies you've created for your game.
1. Go to Configurator>Currencies and click to Add a new custom currency:
2. For this tutorial, we'll configure a sign-up bonus for CURRENCY_1 of 1000:
- Now, whenever you register a player, they'll be granted 1000 units of CURRENCY_1.
3. Click to Save and Close your editing changes to the currency.
Creating Currencies? For more details of how to create and configure game currencies, see Currencies.
Setting Up a Virtual Good for Purchasing with a Virtual Currency
1. Log in to the GameSparks Developer Portal and go to Configurator > Virtual Goods.
2. Click to Add a new Virtual Good. The Add Virtual Good page appears.
3. Enter the Virtual Good details:
- Give it a Name and a Short Code - we'll use the Short Code to refer to the item later on.
- Leave the Type as Virtual Good.
- Note that the other option here is Currency Pack which, instead of adding a good to your player, grants them some configurable quantity of currencies. You would typically select Currency Pack as the Virtual Goods Type when you want to allow your players to exchange real money for in-game currencies. When players purchase a Currency Pack Virtual Good using any of the 3rd-party store BuyGoodsRequests, such as IOSBuyGoodsRequest, they will be credited with the game currency amounts you've configured for that Currency Pack Virtual Good. See the Virtual Goods page for details.
- Currency Costs - Because we're going to start with a Virtual Currency purchase, we need to specify a price for the Virtual Good here, so let's set the CURRENCY_1 value at 100. This means a player will be charged 100 units of CURRENCY_1 when they buy this Virtual Good.
- Recall that we've configured CURRENCY_1 to award every new player a sign-up bonus of 1000 of that currency.
Default Game Currencies? If you've enabled any of the six default game currencies in Game Overview>Edit, you can also configure a Virtual Good for costings in any of these default currencies.
4. Click to Save and Close the new Virtual Good.
The next steps all take place within the Test Harness.
Checking Purchases in the Test Harness
If you've been following along with the configuration set up above, you should be able to run these steps in the Test Harness.
1. Firstly, we register a new player by submitting an Authentication > RegistrationRequest for "PLAYER ONE":
{
"@class": ".RegistrationResponse",
"authToken": "25e60b70-12c7-4e7f-b363-24ca0355bd92",
"displayName": "PLAYER ONE",
"newPlayer": true,
"userId": "592822bbde3a881f9d8d6d35"
}
- The RegsitrationResponse confirms that the new player has been registered.
2. Now that the PLAYER ONE is registered, we can look at their account details. By submitting a Player > AccountDetailsRequest we can see our CURRENCY_1 signup bonus has been awarded:
{
"@class": ".AccountDetailsResponse",
"currencies": {
"CURRENCY_1": 1000,
"CURRENCY_4": 0,
"CURRENCY_5": 0,
"CURRENCY_2": 400,
"CURRENCY_3": 0
},
"displayName": "PLAYER ONE",
"externalIds": {},
"location": {
"country": "GB",
"latitide": 53.966705322265625,
"city": "York",
"longditute": -1.0832977294921875
},
"userId": "592822bbde3a881f9d8d6d35",
"virtualGoods": {}
}
- Note that not all of the AccountDetailsResponse is shown here!
3. To buy a Heart we submit a Store > BuyVirtualGoodsRequest:
{
"@class": ".BuyVirtualGoodsRequest",
"currencyShortCode": "CURRENCY_1",
"quantity": 1,
"shortCode": "HEART"
}
{
"@class": ".BuyVirtualGoodResponse",
"boughtItems": [
{
"quantity": 1,
"shortCode": "HEART"
}
],
"currencyConsumed": 100,
"currencyShortCode": "CURRENCY_1"
}
4. And we submit a subsequent Player > AccountDetailsRequest, which will show that the player now has a Heart available and 100 less of CURRENCY_1:
{
"@class": ".AccountDetailsResponse",
"currencies": {
"CURRENCY_1": 900,
"CURRENCY_4": 0,
"CURRENCY_5": 0,
"CURRENCY_2": 400,
"CURRENCY_3": 0
},
"displayName": "PLAYER ONE",
"externalIds": {},
"location": {
"country": "GB",
"latitide": 53.966705322265625,
"city": "York",
"longditute": -1.0832977294921875
},
"userId": "592822bbde3a881f9d8d6d35",
"virtualGoods": {
"HEART": 1
}
}
- Note that not all of the AccountDetailsResponse is shown here!
5. Lastly, the player can now consume a Heart using Store > ConsumeVirtualGoodRequest, which will remove the Virtual Good from their profile:
{
"@class": ".ConsumeVirtualGoodRequest",
"quantity": 1,
"shortCode": "HEART"
}
{
"@class": ".ConsumeVirtualGoodResponse"
}
Integrating with Third-Party Stores
Using a Virtual Currency is one option when buying Virtual Goods. What if you want to hook up to a third-party store to handle real money transactions? GameSparks supports integration with Google Play and the iOS App Store to allow you to do just that!
This section explains how to integrate each store type with the GameSparks platform. In all cases the underlying flow is the same:
- The player requests a purchase to be made within the Game Client.
- The Game Client calls the Store API on the device to process the transaction.
- The Store API responds with a receipt.
- The Game Client sends the receipt through to the GameSparks platform.
- The GameSparks platform validates the receipt and adds the purchased Virtual Goods to the player's profile.
Google Play
1. To make purchases using Google Play, you first need to set up your Virtual Good as a product in the Google Play Developer Console. See Creating a Product List.
2. Now we need to tie the Virtual Good in your game to the product in Google Play. We do this in the GameSparks Developer Portal:
- Go to Configurator > Virtual Goods and edit your Virtual Good.
- Insert the Product ID you gave your product within the Google Play Developer Console into the Google Product ID field.
Enable Google Integration! If you don't see the Google Product ID field for configuring your Virtual Good, go to the Game Overview page and click to Edit the page. Ensure that Google integration is checked on the Features & Integrations tab. See Selecting Features and Integrations on this page.
3. Finally, to verify the purchase on the server you need to set up your Google Play public key within your game:
- In the GameSparks Developer Portal go to Configurator > Integrations and select Google.
- Click Edit and in the Google Play Public Key field, enter the key obtained by following the steps in the section "Getting an app's license key" here.
4. After making the purchase in the client, Google Play will invoke your response Intent as described in Purchasing an Item. At this point you can get the purchase data and the signature:
String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA"); String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE");
5. You then send the data to the GameSparks platform using a GooglePlayBuyGoodsRequest:
{ "@class": ".GooglePlayBuyGoodsRequest",
"signature": "dataSignature",
"signedData": "purchaseData"
}
The GameSparks platform will validate the purchase against the signature and, if it is valid, return with:
{ "@class": ".BuyVirtualGoodResponse",
"boughtItems": [ { "shortCode": "HEART", "quantity": 1 } ],
}
At which point the player's profile will have been updated with the newly purchased Virtual Goods.
iOS App Store
1. To make purchases using the iOS App Store, first you need to set up your Virtual Good in iTunes Connect, as described in Configuring a Product.
2. Now we need to tie the Virtual Good in your game to the product in iTunes Connect. We do this in the GameSparks Developer Portal:
- Go to Configurator > Virtual Goods and edit your Virtual Good.
- Insert the Product ID you gave your product within iTunes Connect into the iOS Product ID field.
3. After a purchase is made, get hold of the receipt as described in Read the Receipt Data.
NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL]; NSData *receipt = [NSData dataWithContentsOfURL:receiptURL]; if (!receipt) { /* No local receipt -- handle the error. */ }
4. You then send the receipt to the GameSparks platform using a IOSBuyGoodsRequest:
{
"@class": ".IOSBuyGoodsRequest",
"receipt": "receipt"
}
The GameSparks platform will validate the purchase with the App Store and, if successful, return with:
{
"@class": ".BuyVirtualGoodResponse",
"boughtItems": [
{
"shortCode": "HEART",
"quantity": 1
}
],
}
At which point the player’s profile will have been updated with the newly purchased Virtual Goods.