Story Tellers iOS Starter Kit Documentation
To test out In-App Purchasing in iOS9 (or any iOS version), you need to create a new app listing in iTunes Connect as a registered Apple Developer.
One of the steps in creating a new app, is setting your Bundle ID. Typically, developers use a reverse of their domain name, then the app name. For example, com.cartoonsmart.buildavehicle . Be sure this ID is entered in your general settings in Xcode.
Now its time to create an In-App Purchase (or a few) in iTunes Connect.
The Story Tellers Kit supports both Non-Consumable and Consumable. Non-Consumable products are bought for life. Buyers can restore past Non-Consumable purchases for free. If you want readers to be able to unlock certain pages in your book app, or provide extra functionality whenever they want it, this is the type of In-App Purchase you want to choose.
Alternatively, your In-App Purchase can be set as Consumable, meaning buyers will use up what they bought over time. For example, they might buy 10,000 Coins, and doing something in the app (playing a game on a page, or pressing a button), subtracts a certain amount of Coins. Consumable purchases are not restorable. For example, pressing a Restore button would not give the buyer back the 10,000 coins they originally purchases. But the user could buy more Coins, for example, if they had 5,000, they could buy 10,000 more. And Coins is just an example, you can invent your own currency titles in the property list
Most likely for a book app, you’ll choose Non-Consumable, but you have both options in the kit.
After you’ve gone through the steps to create an In-App Purchase you’ll see a screen like this…
Jot down your Product ID’s and Type. You’ll add them to the Property List like so…
Notice there are two dictionaries above, one named Nonconsumables and one named Consumables. Inside are dictionaries with the Product ID’s set as Keys. Each dictionary can / should contain an Events dictionary of events to do when the purchase has been made. Optionally these same events can be run if the In-App Purchase is restored (you have two ways to restore purchases, one does not run these events).
How to check when an In-App Purchase has been made…
For both Non-Consumable or Consumable purchases, the kit will save an NSUserDefault with the Product ID as the key, and a value of “Purchased”. So for example, if you want to set up an Event Listener to check whether a product has been purchased, you would do this…
In the example above we are checking if MOREVEHICLES equals Purchased, and if so the Events dictionary will run, sending the user to the Cover page. Keep in mind, you can run an unlimited number of Events here, you don’t necessarily have to send the user to another page.
How to check when an In-App Purchase has NOT been made…
Alternatively, you can check if the purchase has not been made. Notice instead of ListenFor, we are using ListenFor!= which checks to see if MOREVEHICLES does NOT equal Purchased.
Again you can run an unlimited number of events based on this non-equality. In this example, we are showing the PurchaseButton (using the Show property). This previously-hidden button could be shown only if the In-App purchase wasn’t already bought.
Properties for Buying and Restoring
- BuyProduct – the value should be the Product ID to purchase.
- Restore – no value is needed. This will restore all Non-Consumable purchase, and run the Events associated with each. An alert will also appearing telling users their purchases have been restored.
- RestoreSilently – no value is needed. This will restore all Non-Consumable purchases without running the Events associated with them. This will not show an alert either. The example below shows RestoreSilently being run as a TouchUpEvent, but this could also be run in the Events dictionary of the Cover page, to essentially make sure the app is fully restored anytime it is launched.
If your app will sell consumable purchases, you will most likely want to set the AddToValues properties. For example…
Later on, you will probably want to subtract from a saved value using SubtractFromValues. This could be done anytime you let the reader / user do something special that was an incentive for buying coins earlier.
And keep in mind, you can always check to see if a particular value is over a certain amount using an EventListener. So for example, you might listen to see if Coins is less than 10, and if so, show a PurchaseButton.
If you stumbled onto this article, it is part of our documentation for the Story Tellers iOS Starter Kit 2. The kit enables you to make children’s book apps and games without writing any code! But it is Swift 2 based and compatible with iOS9 (or higher) and Xcode 7 (or higher), so kit buyers can even extend the functionality to fit their needs further. Some of what we cover in the kit documentation may apply to Xcode in general, so this article could be worth a read even if you aren’t a user. You can purchase Lifetime Updates the kit here, or subscribe Yearly to CartoonSmart and get the latest version, plus access to all of our other kits / tutorials.
We’ve also created an iBook to document the very latest properties in the kit, so be sure to download that as well.