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`.

{|- | style="width: 50%;"|

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
| style="width: 50%;"|

Events

Event.REQUEST_PRODUCTS_COMPLETE
Event.RESTORE_TRANSACTIONS_COMPLETE
Event.TRANSACTION

Constants

StoreKit.FAILED
StoreKit.PURCHASED
StoreKit.RESTORED
|}