StoreKit

Supported platforms:
Available since: Gideros 2012.2.2

Description

THIS PLUGIN IS DEPRECATED!

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")

Loading the Storekit module also creates a global variable storekit of type StoreKit for direct use.

State of a Transaction

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

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

StoreKit Events

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

Event.REQUEST_PRODUCTS_COMPLETE

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

require("storekit")
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

<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 returns whether the user is allowed to make payments StoreKit:finishTransaction completes a pending transaction StoreKit:purchase process a payment request StoreKit:requestProducts retrieve localized information about a list of products StoreKit:restoreCompletedTransactions restore previously completed purchases

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