Difference between revisions of "StoreKit"
(Created page with "__NOTOC__ '''Supported platforms:''' <br/> '''Available since:''' Gideros 2012.2.2<br/> === Description === <br /> The `StoreKit` class provides the functionality that allow a...") |
|||
Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
− | '''Supported platforms:''' <br/> | + | '''Supported platforms:''' ios<br/> |
'''Available since:''' Gideros 2012.2.2<br/> | '''Available since:''' Gideros 2012.2.2<br/> | ||
=== Description === | === Description === | ||
Line 131: | Line 131: | ||
If all transactions are delivered successfully, `event.errorCode` and `event.errorDescription` will be `nil`.<br /> | If all transactions are delivered successfully, `event.errorCode` and `event.errorDescription` will be `nil`.<br /> | ||
<br /> | <br /> | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
{|- | {|- | ||
| style="width: 50%;"| | | style="width: 50%;"| | ||
=== Methods === | === Methods === | ||
+ | [[StoreKit:canMakePayments]] - StoreKit - returns whether the user is allowed to make payments<br/> | ||
+ | [[StoreKit:finishTransaction]] - StoreKit - completes a pending transaction<br/> | ||
+ | [[StoreKit:purchase]] - StoreKit - process a payment request<br/> | ||
+ | [[StoreKit:requestProducts]] - StoreKit - retrieve localized information about a list of products<br/> | ||
+ | [[StoreKit:restoreCompletedTransactions]] - StoreKit - restore previously completed purchases<br/> | ||
| style="width: 50%;"| | | style="width: 50%;"| | ||
=== Events === | === Events === | ||
+ | [[Event.REQUEST_PRODUCTS_COMPLETE]] | ||
+ | [[Event.RESTORE_TRANSACTIONS_COMPLETE]] | ||
+ | [[Event.TRANSACTION]] | ||
=== Constants === | === Constants === | ||
+ | [[StoreKit.FAILED]] | ||
+ | [[StoreKit.PURCHASED]] | ||
+ | [[StoreKit.RESTORED]] | ||
|} | |} |
Revision as of 08:57, 23 August 2018
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`.
MethodsStoreKit:canMakePayments - StoreKit - returns whether the user is allowed to make payments |
EventsEvent.REQUEST_PRODUCTS_COMPLETE Event.RESTORE_TRANSACTIONS_COMPLETE Event.TRANSACTION Constants |