In-App Purchases

In-App Purchases are an exciting new way for mobile Stencyl games to monetize and bring success to their creators.

It’s well known that given a free app and a paid app, the free app will be downloaded on average, 10x as much as the paid app. This gives the creator more opportunities to monetize the free app by providing downloadable, supplementary content (new levels or game modes), an unlock for the full game, consumables and much more.

Starting with Stencyl 1.4, iOS developers can add In-App Purchases to their games. Like all things Apple, the devil is entirely in setting up In-App Purchases in iTunes Connect. The amount of Stencyl-specific work is minute in comparison.

What this Primer Covers

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.

Prerequisites

• Stencyl 1.4 or later
• Apple Developer License
• All your certificates and provisioning profiles should be properly set up
  • For the App ID you will use, In-App Purchases must be enabled. Go to the Provisioning Portal to check.
• An active iOS Paid Applications Contract (check the Contracts, Tax & Banking section of iTunes Connect!)
• An iOS device – In-App Purchases cannot be tested in the iOS Simulator

Step 1: Go to iTunes Connect

https://itunesconnect.apple.com

Step 2: Set up a Sandbox Account

1. Click on “Manage Users”
2. Click on “Test User”
3. Define a user. This is what you will test In-App Purchases with.

Step 3: Set up a new game with IAPs

1. Create a new game entry in iTunes Connect.
2. Click “Manage In-App Purchases”
3. Click “Create New”
   1. Pick Non-Consumable
   2. Fill out the form.
   3. “Cleared for Sale” must be yes, and you must provide a screenshot. It’s OK for now to provide a blank screenshot.
4. Repeat Step 3 for as many items as you need.

What if you want to operate on an existing game? You can, but only under certain conditions that Apple dictates. For the sake of keeping this guide simple, I’m not going to cover that case today but will in the full guide.

Step 4: Mark Game as Ready to Upload

When you are ready to proceed, mark the game as Ready to Upload, but do NOT actually submit the binary!

Step 5: Set up Purchases in Stencyl

In a gist, setting up purchases in Stencyl is a simple process.

1. Tell the game what products you want to sell.
2. Tell the game when to sell the products, using the buy product block.
3. To determine what products have been bought, use the “user purchased product” block, which returns true or false.

Here are the exact steps. In this instance, we just want to prompt the player to buy a product.

1. Open up your game.
2. Go to “Mobile Game Settings” and click on Monetization.
3. Fill in the In-App Purchases field with the Product IDs you defined in Step 3.3. One product per line.
4. Now, create a scene behavior and stick in the “buy product” block. You can find it under Game > iOS APIs towards the bottom. (Figure 5)
5. Attach the behavior to any scene.

(Figure 5)

Don’t test your game quite yet – there’s still one more step to go.

Step 6: Prepare your Device

1. 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!
2. If you’re testing your game, it helps to delete the existing copy from the device that never had IAPs to begin with.

Step 7: Test it on the device!

Now, run your game on the 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 10-15 seconds, read on.

Troubleshooting

Since you are testing on the device, likely through Xcode, you will see the game’s output in the lower pane. If you see something along the lines of “Error [NUM]: 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.

Out of your control

• Wait up to 24 hours for iTunes Connect to sync its data.

In your control

• Is your iOS Paid Applications contract active? (Check Contracts, Tax and Banking in iTunes Connect)
• Have you enabled In App Purchases for the App ID you are using?
• Have you marked your app as ready to upload?
• Did you remember to check “cleared for sale” for each product?
• Did you member to submit a screenshot for each product?
• Did you provide the correct product IDs, exactly as you entered them into iTunes Connect?
• Did you remember to enter in the product IDs into StencylWorks?
• Did you sign out of your live/real account?
• Did you create a test account in iTunes Connect?
• Did you sign in to the test account, only in the app-itself, NOT under Settings?
• The “dumb” solutions that sometimes work
  • Are you testing your game on your device, not in the simulator?
  • Is your device jailbroken?
  • Can the device connect to the internet?
  • Have you tried deleting and than reinstalling the app? (Not just installing it!)
  • Have you tried rebooting your device?

If none of these solutions work, ask on the forums. In-App Purchases are challenging to add, not because they’re particularly difficult, but because of the obtuse system of setting them up. Unfortunately, we have little sway in making this process easier, besides documenting every last possibility of failure.

MikeyPB
Good Article. The only thing I tripped up on was the option to host content with Apple. I checked Yes, which was wrong (I'm certainly not hosting anything!).
Thankfully, the Apple site alerted me to this when I went back to iTunes Connect (head in hands) to see what I had done wrong.

You have to create a new game entry in iTunes connect (through the 'manage your apps' option). This means inputting a lot of info about your game, as it seems to be the first step to publishing. I was unprepared for this so was unsure if I was doing the right thing, just to let others know.
0 4 days, 19 hours ago

paullawton
Make sure you're not stupid like me who spent ages getting it to work because I was using the Apple ID (generated by Apple - something like 6875642) instead of the correct Product ID (entered by you - something like my.unique.product_id).

There's a reason it's underlined and in bold :)
0 2 months, 1 day ago

looniegames
http://www.stencyl.com/help/view/pu blish-to-app-store/
0 3 months, 4 weeks ago

looniegames
Hope this helps.
http://developer.apple.com/library/ ios/#documentation/LanguagesUtiliti es/Conceptual/iTunesConnect_Guide/8 _AddingNewApps/AddingNewApps.html
0 3 months, 4 weeks ago

ambidexterousgames
How do you create a new game entry in iTunes Connect ?
2 9 months, 6 days ago

Commenting Guidelines

Sign In to Comment