Adding In-App Purchases to your Windows 8 Game

Introduction

In-app purchases can be a great way to monetise your Construct 2 games on Windows 8. For our game Mortar Melon we’ve given our first world away for free, but then charged for a new desert world.

Here you can see the pop-up screen with a description of the IAP, the price, and the option to buy:

You could also use an IAP to hide advertisements, buy new weapons or clothes for your characters, purchase power-ups, add ingame currency or even buy more time playing the game. The possibilities are endless!

Adding IAP to an example .capx

You can download the sample mini-game that we’ll be using for our tutorial here: Sample .capx.

This is a simple flinging game where you have to reach your friend and give them a kiss ❤. From the main menu you can change your character’s hat and this will be the basis for our in-app purchases - buying hats!

After opening up the .capx, the first thing we’ll need to do is export the game to run on Windows 8. If you’re not familiar with this ensure you familiarise yourself with this tutorial: How to make a Windows 8 app. Follow this tutorial and you should be able to launch the game on our target platform!

After launching the game you’ll notice that you can freely change the character’s hat, switching between a purple cap or no headgear at all. This won’t do... we can’t give hats away for free! The next few steps will talk through how we can make the hat an in-app purchase.

First, open up the .capx and in the objects panel, right click and insert new object. Find the Windows 8 Object and select Insert. Now we can start adding Windows 8 specific functionality to the game.

Navigate to the the event sheet called Menu, found under the Event Sheets folder in the Project Panel. Expand the Hats group and you can see the logic that changes the hat in the main menu of the game.

Add in the following logic to add in-app purchases on Windows 8. This simply sets the purple hat button to be active when purchased and prompts to purchase when inactive and pressed.

Notice the product ID “PurpleCap”. This is very important and needs to be consistent at every step of the process.

You can download the .capx with these additions here: Sample .capx with IAP.

Testing purchases

Now if you export again and run the game, you’ll see the following message.

This means that you can test purchases without having to submit your app. When it comes to your final app submission, make sure Test mode is turned off, otherwise you’ll fail certification.

When running the game and you select the purple hat on the menu screen, you’ll be presented with the following prompt:

This allows you to simulate various situations that could happen when a user tries to make a purchase. These error codes correspond to the following:

S_OK - Operation successful

E_INVALIDARG - One or more arguments are not valid

E_FAIL - Unspecified failure

E_OUTOFMEMORY - Failed to allocate necessary memory

S_OK will trigger the Construct 2 condition On Successful Purchase and all the others will trigger On Failed Purchase. Ensure that you accommodate for when a purchase fails as well as when it is completed. Players will get confused if the game just fails to purchase silently without notifying them of an issue!

So now if you select S_OK and click Continue, you’ll see the hat is selected and you can continue playing the game with your newly acquired gear.

To simulate a user that has already completed the IAP prior to launching, we need to make some changes to the WindowsStoreProxy.xml file in the Solution Explorer of the exported project.

Change this text:

    	<!-- Include to test product purchases -->
    	<!--
    	<Product ProductId="my_product_id">
    		<IsActive>false</IsActive>
    	</Product>
    	-->

To the following:

    	<Product ProductId="PurpleCap">
    		<IsActive>true</IsActive>
    	</Product>

Here we’ve added a product with a Product ID "PurpleCap” which matches what was entered in Construct 2 previously. We’ve also set the property IsActive to true, simulating a scenario where the user has already purchased the product.

Now when you run the build, you’ll notice you are no longer prompted when selecting the purple hat. This is how you’d expect it to behave when after having purchased a product.

Retrieving IAP Information

In order to retrieve information about your IAP including name and price, you need to change the following:

    	  <!-- Include to test product listings -->
    	  <!--
    	  <Product ProductId="my_product_id">
            <MarketData xml:lang="en-us">
              <Name>My Product</Name>
              <Price>1.99</Price>
              <CurrencySymbol>$</CurrencySymbol>
            </MarketData>
          </Product>
    	  -->

To this:

    	  <Product ProductId="PurpleCap">
            <MarketData xml:lang="en-us">
              <Name>Purple Cap</Name>
              <Price>1.99</Price>
              <CurrencySymbol>$</CurrencySymbol>
            </MarketData>
          </Product>

Here the Product ID matches what we’ve previously entered in Construct 2. We’ve also added a language code, a name, a price and a currency symbol. This information will be used by Construct 2 to output the formatted price and name of the product.

When your app is submitted, the language and currency is determined by the user’s device. The information that you enter in WindowsStoreProxy.xml is just dummy content for testing that will be replaced automatically once in the store.

If you go back to the Construct 2 project and add the following logic, we’ll log the name and price of the IAP to the Visual Studio console.

In your own project you can use the Windows 8 Object expressions ProductName and ProductFormattedPrice to display the name and price of an IAP from within your game using the text object.

Warning: when using a custom font, ensure that it contains the currency symbols for the markets you’re targeting, otherwise no currency symbol will display at all! You can test by changing the CurrencySymbol property in WindowsStoreProxy.xml.

Export and deploy the project, and when switching back to Visual Studio you should see the name and price of the IAP has been logged to the console.

Warning: Exporting to the same folder will overwrite any changes that you’ve made to the project, including WindowsStoreProxy.xml. Ensure that when you re-export you do so to a separate directory and copy only the files you need (usually c2runtime.js and any new images/media) to your working directory.

Adding IAP to your submission

So now we’ve added the ability to purchase a purple hat, and learnt how we can extend this to show the name and price of an IAP product. Next we’ll look at the IAP details you need to complete in the Windows Dev Center when submitting your app.

For more information on submitting your app, please read this article: Submitting your app

Highlighted below is where you’ll define the essential IAP details.

In the following section, add the Product ID that matches what you’ve put in the Construct 2 project and in WindowsStoreProxy.xml. It is very important that this matches exactly. Also enter the Price tier for how much you want to charge for the IAP and change the Product lifetime if you’d like the purchase to expire.

Click Save and go back to the previous section. In the following highlighted section you’ll add the description of the IAP which will tell the end-user what the product is.

Add your description in the field below. This will be presented to the user when prompted to complete the IAP.

Here you can see an example of where the description is shown for our game Mortar Melon after the user clicks the buy button.

Conclusion

So we’ve talked through how to add in-app purchases to your Construct 2 game, exporting to Windows 8 for testing and what details you need to complete in Windows Dev Center for certification.

Hopefully this introduction will give you the information to go forth and successfully monetise your games!