by Jon (Updated on 2015-10-26)
In-App Purchases (IAP) let you sell goods and services from within a game. This gives developers more opportunities to monetize the free app by providing downloadable, supplementary content (new levels or game modes), an unlock for the full game and much more.
Most of the work involves setting up the purchases on iTunes Connect. Once you get past that part, it's just a matter of setting up a few blocks inside of Stencyl.
This guide will show you how to set up In-App Purchases in iTunes Connect and get you up to the critical point – getting iOS to display its standard prompt for purchasing an item.
Note: You do not need a Studio license with us to test this feature. You only need it to publish your game.
Disclaimer: Apple continually changes the process, making it difficult for us to maintain this portion. The general ideas should remain the same, but the specifics and names can and will change over time.
Note: What if you want to operate on an existing game? You can, but only under certain conditions that Apple dictates. Consult Apple's documentation for details.
When you are ready to proceed, mark the game as Ready to Upload, but do NOT submit the binary yet.
Sign out of your “Store” account on your device (it’s under the Settings App as “Store” towards the bottom). Do NOT sign back in using the test account yet! You will sign in to the test account while you are testing your game.
If you’re testing your game, it helps to delete the existing copy of the game from the device that never had IAPs to begin with.
Making purchases in Stencyl requires two steps. One is setup related.
Use the request info for product block to declare a purchase. You can find it under Game > Mobile towards the bottom. The ID you use is the Product ID you entered into iTunes Connect.
Do this for each purchase in your game. You only have to do this ONCE, not every time you wish to make a purchase.
(In order to "know" when your request succeeded, use the when a product info request succeeds event under Add Event > Mobile > Purchases)
Now, all you have to do is create a behavior that buys the product. You can find the buy product block under Game > Mobile towards the bottom. The ID you use is the Product ID you entered into iTunes Connect.
You should always check if a purchase succeeded (or failed) using the purchase events we provide (under Add Event > Mobile > Purchases). Only if a purchase succeeds should you proceed to unlock or provide the promised functionality.
Now, run your game on your iOS device. If everything was properly set up, your app should prompt you to purchase your product. Congratulations!
If you are less fortunate and nothing happens after 30 seconds or so, read the Troubleshooting section.
In prior versions of Stencyl, it was challenging to determine exactly when a purchase succeeded or failed. This is no longer the case. You now can use Events (all under Add Event > Mobile > Purchases) to react to various Purchase-related happenings.
Consumable purchases are products that can be used. More specifically, these are products that can be repurchased over and over again. This contrasts with regular (non-consumable) purchases that stay with the user forever.
A common example of a consumable purchase is virtual currency. Some games (particularly those that make you wait to progress), will sell a special currency that can be used in game to speed the game up or let you purchase special items that accomplish the same.
Consumables are "used" using the use product block (same block as buy product, click the dropdown). Make sure to check that the user has at least 1 of that product before using, as shown below.
If consumption was successful, you will receive a purchase-succeeded event. If it failed, you will receive a purchased-failed event. Be sure to handle these events - do not let the user consume the products immediately.
If a user installs your app in a different device, or if the user has wiped their device, they'll want to get their purchases back for your app. Restoring Purchases is the feature that enables this. The way it works is that when a restore happens, the game acts as if the player made all those purchases again.
Use the restore purchases block under Game > Mobile to initiate this process (connect it to a button press, for example).
When this happens, you will receive a bunch of purchase is restored events (which you can receive via Add Event > Mobile > Purchases), each corresponding to a purchase. It's your task to react to these events in an appropriate manner.
So... something didn't quite go right. First, check your logs.
If you see something along the lines of "Cannot connect to the iTunes Store", then you know for certain that something didn’t quite go right along the way.
Here’s a list of everything we know that could go wrong.
If none of these solutions work, ask for help on the forums.
In-App Purchases are challenging to add because of the obtuse system of setting them up on iTunes Connect. Unfortunately, there's little we can do to make this process easier besides providing help and documenting solutions to common problems as they come along.