This tutorial is designed to help you properly add In-App Purchases to your iOS games.  In this tutorial, we'll walk through the GameSalad Creator aspects of this process; successive tutorials will cover the Apple / iTunes Connect aspects.  As a reminder, IAPs are only available to users with a Pro Membership.

Disclaimer: This process covers incorporating table data, and is fairly complex.  However, it's very important to understand all aspects of this process.  We recommend moving as much of your game, inventory, and purchases data as possible into tables.

Getting Started - IAP for Consumable Items

First, create the attributes that your In-App Purchase behaviors will modify.  In this example, we've created an Integer attribute named "Coins" and a Boolean Attribute named "Unlocked Game".  Coins will be our example of a consumable good - that is, one that users can purchase over and over, and will use up over time.  Unlocked Game will be our example of a non-consumable good - that is, one that users will only purchase and use once.

Unlocked Game will be set to False by default, and changed to True when that purchase is made.

Second, create a new table to reference information about your purchased items.  As you can see in the table below, we've set the first column to "text" and the second to "integer".  It is very important that the IDs in the text column match exactly with the ones you made in iTunes Connect, as we'll discuss in a later tutorial.  

Not all tables have to be formatted this way, but this particular example utilizes the second "Integer" column to record the number of items in consumable purchases.  If all your purchases are non-consumables, the second column may be unnecessary.  Here, indicate the number of consumable items the player will receive upon purchase.

Next, we're going to create a new actor.  This actor will hold our In-App Purchase behaviors.  Drag in the "In App Purchase Item" behavior.

In the Product ID attribute field, click the Expression Editor icon (e) to bring up the Expression Editor.  Select the function "tablecellvalue(table, row, col)".  

Tip: You can manually enter the product ID or use game attributes for item referencing, but you will find that tables will make the process much easier and more efficient when editing your values in the future.

Replace "table" with the game attribute associated with your item table.  In this case, it would be "game.ItemTable".  If you named your table something else, then it will show up as "game.(your table name) ".

Now, specify the row and column of the desired product ID.  In this example, we will reference the item "Coin Bag 100" at row 1, column 1.  Click the green check button to accept the expression and return to the behavior.

Tip: Everything inside of the TableCellValue bracket can be linked to attributes or expressions utilizing functions.  Mix and match methods to see what works best for you.

We want this purchase to add 100 coins to the total game coin count.  In the "Change Attribute" field, navigate to the game attributes and select "game.Coins", which we created at the beginning of this tutorial.

Because this is a consumable item, you must click the "Consumable" checkbox.  By default, this will be unchecked.  With the checkbox, you'll be given a new field in which to enter how to change the affected attribute - in other words, how much to increase the Coins attribute by.  

We've already set this up in the table, so we need another expression using the tableCellValue function to determine the amount to add to game.Coins.  In this case, we'll use the first row and the second column, named "quantity".  We could also use "2" instead of "quantity"; table row and column references can be identified by either their number value or by your user-generated name.  As long as the user-generated name is put in quotes (and spelled correctly!), it will work.  For this reason, we highly recommend you don't name any columns with the same name.

To recap - this process should add 100 coins to the game.Coins attribute whenever a user purchases the bag of 100 coins.

You'll need to repeat this process for all of your consumable IAP items - and be sure to link up the proper rows and columns!

IAP Behavior for Non-Consumable Items

Non-Consumable items are going to be handled almost identically to consumable ones, except they will only work with Boolean attributes in the Change Attribute dialogue.  The idea is that a non-consumable item is a one time purchase that will flag the specified Boolean attribute from False to True automatically when the purchase is successful. 

1. First, create an actor.  
2. Drag in the In App Purchase Item behavior.
3. 
4. Use the Expression Editor to select the function "tableCellValue"; select the table we created before, but this time use row 3, column 1.  If you recall from earlier, row 3 corresponds to the "Full Game Unlock" item in our table.
5. Since this is not a consumable item, leave "Consumable" unchecked.
6. 
7. In the Change Attribute field, select the Boolean game attribute we created earlier called "game.UnlockGame".  This is the attribute we will have associated with content that will be available to the player once the purchase is complete.  When switched to True, players will have access to new levels, music, characters, items, or anything else you wish to offer them for purchase.

Setting up Success, Cancel, & Error Scenes

The In App Purchase Item behavior also allows you to customize your player's experience for the various purchasing events: Success, Cancel, and Error.  

By default, the game will return to the state it was in before the transaction occurred.  However, you have the option to specify another scene.  Upon the completion of the purchase event, your game will pause and load your special scene.

Use the drop-down menus in the In App Purchase behavior to specify which scene your players will be taken to in the event of success, cancellation, or error.

In App Purchase Restore Item Action

It is not currently a requirement, but it is highly recommended that you include a button or option in your game to restore any non-consumable purchases the player made previously.  This is helpful when a player has moved to a new device, or reinstalls your game after deleting it from their device.

Note: Restore behaviors will only restore non-consumable items associated with boolean attributes.  Consumables like coin packs cannot be restored.

1. Use the "In App Purchase Restore Item Action" behavior.  Similarly to previous steps, specify the desired Product ID and associated attribute to change, preferably through the use of a table.  In this example, the third row of the items table is being referenced for the "Full Game Unlock" item.
2. Use the (+) and (-) buttons to add or remove additional items that can all be restored at the same time.

This behavior will automatically prompt the user to log into their iTunes account, if they haven't already, and will confirm that the purchase has already been made.  All you need to do is give them a button linked to this behavior, along with possibly a bit of text explaining what it is for.

Saving and Loading your IAP Attributes

When an item has been purchased the associated attributes will automatically save and use the Product ID as the save key.  Somewhere in your initial scenes, you will want to create a Load Attribute behavior associated with your purchased item(s).  This will prevent the player from having to go through the purchase process each time they play your game in order to unlock their items.

Note: Loading an attribute associated with a purchase is NOT the same as using the Restore Item Action behavior, which should only be used to recover previous purchases when playing the game on a new device or if the user has reinstalled the game.

Example 1

In this example, we are loading the saved value for the item "Full Game Unlock".  In the Key field the associated Product ID cell is being referenced using the "TableCellValue" function.  The Attribute field should be associated with the boolean game attribute "game.UnlockGame".

Example 2

While consumable items will be saved automatically, the actual quantity of that item will change constantly through gameplay. It is incredibly important to remember to create a custom Save Attribute behavior with a unique Key. It is NOT recommended that you use the Product ID as the key, as it is likely to not return the desired value.  In this example, we will create a Save Attribute behavior associated with "game.Coins" with the unique Key "TotalCoins".  A behavior like this should be triggered ANY TIME the player earns or spends coins in the game.

Also, somewhere at the beginning of the game be sure to trigger a Load Attribute behavior that uses your custom Key to load the "game.Coins" attribute.