StoreKit

Supported platforms: ios
Available since: Gideros 2012.2.2

Description

The StoreKit class provides the functionality that allow an application to request payment from a user.
This class is only available to iOS platforms.

The StoreKit class is defined in module "storekit". Therefore, you need to call
require("storekit") before using it. Loading the "storekit" module
also creates a global variable storekit` of type `StoreKit for direct use.

<h3>State of a Transaction</h3>

The state of a transaction is defined by 3 string constants:

<ul>
<li>**StoreKit.PURCHASED = "purchased"**: The App Store successfully processed payment. Your application should provide the content the user purchased.</li>
<li>**StoreKit.FAILED = "failed"**: The transaction failed. Check the event.errorCode` and `event.errorDescription fields to determine what happened.</li>
<li>**StoreKit.RESTORED = "restored"**: This transaction restores content previously purchased by the user. Read the event.originalTransaction field to obtain information about the original purchase.</li>
</ul>

<h3>StoreKit Events</h3>

The StoreKit` class dispatches the events `Event.REQUEST_PRODUCTS_COMPLETE`, `Event.TRANSACTION` and `Event.RESTORE_TRANSACTIONS_COMPLETE.

<h3># Event.REQUEST_PRODUCTS_COMPLETE</h3>
The function StoreKit:requestProducts is used to retrieve localized information about a list of products from the Apple App Store.
When the request completes, Event.REQUEST_PRODUCTS_COMPLETE event is dispatched. The resulting event table contains
these additional fields about the products:

<ul>
<li>**event.error:** (number) error code if the request failed to execute</li>
<li>**event.errorDescription:** (string) error description if the request failed to execute</li>
<li>**event.products:** (table) array of products where each element is a table which contains the product information</li>
<li>**event.invalidProductIdentifiers:** (table) array of product identifier strings that were not recognized by the Apple App Store</li>
</ul>

Each table in event.products array contains these fields:

<ul>
<li>**title:** (number) localized name of the product</li>
<li>**description:** (string) localized description of the product</li>
<li>**price:** (number) cost of the product in the local currency</li>
<li>**productIdentifier:** (string) string that identifies the product to the Apple App Store</li>
</ul>

For example, this code can be used to print the retrieved product information:
<pre><code>

local function onRequestProductsComplete(event)
if event.errorCode ~= nil then
print("error", event.errorCode, event.errorDescription)
return
end

print("products:")
for i=1,#event.products do
print("title", event.products[i].title)
print("description", event.products[i].description)
print("price", event.products[i].price)
print("productIdentifier", event.products[i].productIdentifier)
end

print("invalidProductIdentifiers:")
for i=1,#event.invalidProductIdentifiers do
print(event.invalidProductIdentifiers[i])
end
end

</code></pre>
<h3># Event.TRANSACTION</h3>

This event is dispatched when a transaction is updated. The event listener should process all successful transactions,
unlock the functionality purchased by the user, and then finish the transaction by calling StoreKit:finishTransaction method. The resulting event table can
contain these additional fields about the products:

<ul>
<li>**event.errorCode:** (number) error code if event.transaction.state` is set to `StoreKit.FAILED</li>
<li>**event.errorDescription:** (string) error description if event.transaction.state` is set to `StoreKit.FAILED</li>
<li>**event.payment.productIdentifier:** (string) product identifier of the transaction</li>
<li>**event.payment.quantity:** (number) number of items the user wants to purchase</li>
<li>**event.transaction.state:** (string) current state of the transaction</li>
<li>**event.transaction.identifier:** (string) string that uniquely identifies a successful payment transaction</li>
<li>**event.transaction.receipt:** (string) signed receipt that records all information about a successful payment transaction</li>
<li>**event.transaction.date:** (string) date the transaction was added to the App Store's payment queue</li>
<li>**event.originalTransaction.identifier:** (string) identifier of original transaction</li>
<li>**event.originalTransaction.date:** (string) date of the original transaction</li>
</ul>

This code can be used to print the transaction information and unlock the functionality purchased by the user:

<pre><code>
local function onTransaction(event)
print("payment.productIdentifier", event.payment.productIdentifier)
print("payment.quantity", event.payment.quantity)

print("transaction.state", event.transaction.state)

if event.transaction.state == StoreKit.FAILED then
print("error", event.errorCode, event.errorDescription)
else
print("transaction.identifier", event.transaction.identifier)
print("transaction.date", event.transaction.date)

if event.transaction.state == StoreKit.PURCHASED then
print("transaction.receipt", event.transaction.receipt)
end

if event.transaction.state == StoreKit.RESTORED then
print("originalTransaction.identifier", event.originalTransaction.identifier)
print("originalTransaction.date", event.originalTransaction.date)
end

-- unlock the functionality purchased by the user
end

storekit:finishTransaction(event.transaction)
end

</code></pre>
<h3># Event.RESTORE_TRANSACTIONS_COMPLETE</h3>

This event is dispatched after the transactions are delivered. The resulting event table can contain these additional fields:

<ul>
<li>**event.errorCode:** (number) error code if an error occurred while restoring transactions</li>
<li>**event.errorDescription:** (string) description of the error if an error occurred while restoring transactions</li>
</ul>

If all transactions are delivered successfully, event.errorCode` and `event.errorDescription` will be `nil.

Methods StoreKit:canMakePayments - StoreKit - returns whether the user is allowed to make payments StoreKit:finishTransaction - StoreKit - completes a pending transaction StoreKit:purchase - StoreKit - process a payment request StoreKit:requestProducts - StoreKit - retrieve localized information about a list of products StoreKit:restoreCompletedTransactions - StoreKit - restore previously completed purchases

Events Event.REQUEST_PRODUCTS_COMPLETE Event.RESTORE_TRANSACTIONS_COMPLETE Event.TRANSACTION Constants StoreKit.FAILED StoreKit.PURCHASED StoreKit.RESTORED