This feature allows you to support In-App Purchases. Currently, only the Apple iTunes Store is supported. In the future, other store fronts may be added.

Using In-App Purchases with the Apple iTunes Store

In-App Purchases allow users to purchase additional content. However, the Apple iTunes Store manages transaction information only! Developers cannot use the Apple App Store to deliver content. So, either you bundle content with your app when you ship it waiting to be unlocked upon purchase, or you have to work out your own system to download the data if you wish to deliver content after the fact. To support downloadable content, you may use our new Network/AsynchHTTP APIs.

For your app to work with Apple's iTunes Store, you must follow Apple's instructions for setting up provisioning on Apple's Provisioning Portal and for setting up purchasing on iTunesConnect. This is a complex process. There are many helpful tutorials available elsewhere on the web; some suggestions are listed at the end of this article. Briefly, the key steps are as follows:

• make sure you submit you tax and banking information to Apple. In-app purchases will not work without this being cleared and you won't get any error messages telling you this is the problem.
• on the Provisioning Portal, create a new AppID that is unique and fully qualified (e.g. com.anscamobile.NewExampleInAppPurchase) (don't use wildcards)
• create a provisioning profile for your AppID
• on iTunes Connect, create a new App using the same bundle identifier
• add your purchasable items with their product identifiers and their classifications (Consumable, Non-Consumable, or Subscription)
• add and configure a test user account to exercise your in-app purchasing code

A sample project is available here: InAppDemo.zip

Using Corona's store module

You'll also need to create code in your Corona app to handle transactions with the App Store.

Initialization / Getting Started

First, you should require the store module into your program
store = require("store")

Next, you need to call the store.init function specifying a listener to handle transaction callbacks (more on that below).

store.init( listener )

You should call store.init() soon after your program finishes launching. The reason is that the Apple App Store likes to aggressively make sure any incomplete transactions can be completed as soon as possible. If a transaction was interrupted the last time your program was run (say due to a phone call or network outage), the user should be able to continue the transaction. By calling store.init(), your app notifies the store that it is ready to handle transaction callbacks.

Getting information about available products for sale

Corona provides store.loadProducts() to retrieve information about items available for sale. This includes the price of each item, a localized name, and a localized description. However, the Apple App Store does not provide a way to query for a list of all available products. Therefore, your code must include (or generate) product identifiers for all items.

store.loadProducts( arrayOfProductIdentifiers, listener )

• arrayOfProductIdentifiers -- A Lua array with each element containing a string which is the product identifier of the in-app item you want to know about.
• listener -- A callback function that is invoked when the store finishes retrieving the product information.

Product IDs are what you entered in iTunes Connect. The typical convention is to use your bundle id with the item name appended on, e.g. (com.anscamobile.NewExampleInAppPurchase.MyNonConsumableItem).

The resulting event from the loadProductsCallback listener has the following properties:

• event.products -- A Lua array with each element containing a Lua table which contains various product information like title, description, price, and the product identifier.
• event.invalidProducts -- A Lua array with each element containing a string which is the product identifier you requested. You will only get entries here if you requested a product that isn't actually available or exists.

Each entry in the event.products array supports the following fields

• title -- The localized name of the item.
• description -- The localized description of the item.
• price -- The price of an item (as a number)
• productIdentifier -- The product identifier.

Here is a simple code example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

function loadProductsCallback( event )
        print("showing products", #event.products)
        for i=1, #event.products do
                local currentItem = event.products[i]
                print(currentItem.title)
                print(currentItem.description)
                print(currentItem.price)
                print(currentItem.productIdentifier)
        end
        print("showing invalidProducts", #event.invalidProducts)
        for i=1, #event.invalidProducts do
                print(event.invalidProducts[i])
        end
end
 
arrayOfProductIdentifiers = 
{
        "com.anscamobile.NewExampleInAppPurchase.MyConsumableItem",
        "com.anscamobile.NewExampleInAppPurchase.MyNonConsumableItem",
        "com.anscamobile.NewExampleInAppPurchase.MySubscriptionItem",
}
store.loadProducts( arrayOfProductIdentifiers, loadProductsCallback )

If you need your product list to be dynamic, Apple recommends you run your own server to provide a list of up-to-date products your app can retrieve.

Typically, you would use the callback as an opportunity to create and display a UI so a user may browse and buy items.

Can Make Purchases?

iOS devices have a setting that disables purchasing. A common case for this is to prevent children from accidentally purchasing things without parents' permission. Corona provides an API to check whether purchasing is possible. Use this preemptively to avoid having your users navigate through many purchase steps only to find out at the last step that purchasing is forbidden.

store.canMakePurchases

Returns true if purchases are allowed, false otherwise.

Purchasing products

To initiate a purchase, Corona provides store.purchase().

store.purchase( arrayOfProducts )

• arrayOfProducts -- A Lua array specifying the products you want to buy. Each element may contain a string which is the product identifier or a Lua table with the same fields as the product elements passed back to you from the event.products array in the loadProductsCallback listener.

This function will send out purchase requests to the store. The listener you specified in store.init() will be invoked when the store finishes processing the transaction.

Note: Currently, there is no explicit API to specify quantities for consumable items. However, as a backdoor, you may place the product in the array multiple times and Corona will set the quantity behind the scenes.

Transaction Listener Callback Events

Calling store.init() enables your program to handle transaction callbacks from the App Store using the listener you provide. This listener should handle all of the following circumstances:

• An item was just purchased (via store.purchase())
• A purchase transaction was cancelled by the user (after store.purchase() was called)
• A purchase transaction failed for various reasons (via store.purchase())
• An item that was purchased in a previous run of the app was interrupted (perhaps due to a phone call) and the App Store is trying to resume/finish the transaction now that it sees that the app is running again.
• A restore already purchased items request was initiated (via store.restore(), explained below)

The resulting event from the transaction callback listener has the following property:

• event.transaction -- An object containing the transaction.

The transaction object supports the following read-only properties

• state -- A string containing the state of the transaction. Valid values are "purchased", "restored", "cancelled", and "failed".
• productIdentifier -- The product identifier associated with the transaction.
• receipt -- A unique receipt returned from the Store. It is returned as a hexadecimal string.
• identifier -- A unique transaction identifier returned from the Store. It is a string.
• date -- The date of when the transaction occurred.
• originalReceipt -- A unique receipt returned from the Store from the original purchase attempt. This is mostly relevant in a case of a restore. It is returned as a hexadecimal string.
• originalIdentifier -- A unique transaction identifier returned from the Store from the original purchase attempt. This is mostly relevant in a case of a restore. It is a string.
• originalDate -- The date of when the original transaction occurred. This is mostly relevant in a case of a restore.
• errorType -- The type of error that occurred when the state is "failed" (a string).
• errorString -- A (sometimes) more descriptive error message of what went wrong in the "failed" case.

After you receive a transaction event, it is up to you to decide what to do. For example, if the user successfully purchased an item, you might record this information in a preference file that unlocks the user's ability to use the item. This file should be referenced in the future so you know that the item has been purchased in future runs. Similarly, if the content must be downloaded, you would initiate the download here.

After you finish handling the transaction, you must call store.finishTransaction() on the transaction object. If you don't do this, the App Store will think your transaction was interrupted and will attempt to resume it on the next application launch.

store.finishTransaction( transaction )

Restoring Purchased Items

Users who wipe the information on a device or buy a new device, may wish to restore previously purchased items without paying for them again. The store.restore() API initiates this process. Transactions that can be restored will be invoked on your transactionCallback listener which you registered with store.init(). The transaction state will be "restored" in this case and your app may then make use of the originalReceipt, originalIdentifier, and originalDate fields of the transaction object.

Transaction Callback Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

function transactionCallback( event )
        local transaction = event.transaction
        if transaction.state == "purchased" then
                print("Transaction succuessful!")
 
        elseif  transaction.state == "restored" then
                print("Transaction restored (from previous session)")
                print("productIdentifier", transaction.productIdentifier)
                print("receipt", transaction.receipt)
                print("transactionIdentifier", transaction.identifier)
                print("date", transaction.date)
                print("originalReceipt", transaction.originalReceipt)
                print("originalTransactionIdentifier", transaction.originalIdentifier)
                print("originalDate", transaction.originalDate)
 
        elseif transaction.state == "cancelled" then
                print("User cancelled transaction")
 
        elseif transaction.state == "failed" then
                print("Transaction failed, type:", transaction.errorType, transaction.errorString)
 
        else
                print("unknown event")
        end
 
        -- Once we are done with a transaction, call this to tell the store
        -- we are done with the transaction.
        -- If you are providing downloadable content, wait to call this until
        -- after the download completes.
        store.finishTransaction( transaction )
end
 
store.init( transactionCallback )
 
-- Might try buying something here:
-- store.puchase{ "com.anscamobile.NewExampleInAppPurchase.MyNonConsumableItem" }
-- Or might try restoring here:
-- store.restore()

Additional Notes & Documentation

In App Purchases are not easy to set up. You may find that you spend more time setting things up in iTunes Connect and creating Provisioning Profiles than actually writing code. Here are some tips and links to help you along the way.

Apple Links

• In App Purchase Programming Guide
• Technical Note TN2259: Adding In App Purchase to your iOS Applications
• iTunes Connect Frequently Asked Questions > Manage Your In App Purchases

Other Links

• In App Purchases: A Full Walkthrough
• Things I learned implementing my first InAppPurchase