Difference between revisions of "StoreKit"
Line 130: | Line 130: | ||
<br /> | <br /> | ||
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 === | ||
Line 154: | Line 140: | ||
| style="width: 50%;"| | | style="width: 50%;"| | ||
=== Events === | === Events === | ||
− | [[Event.REQUEST_PRODUCTS_COMPLETE]] | + | [[Event.REQUEST_PRODUCTS_COMPLETE]]<br/> |
− | [[Event.RESTORE_TRANSACTIONS_COMPLETE]] | + | [[Event.RESTORE_TRANSACTIONS_COMPLETE]]<br/> |
− | [[Event.TRANSACTION]] | + | [[Event.TRANSACTION]]<br/> |
=== Constants === | === Constants === | ||
− | [[StoreKit.FAILED]] | + | [[StoreKit.FAILED]]<br/> |
− | [[StoreKit.PURCHASED]] | + | [[StoreKit.PURCHASED]]<br/> |
− | [[StoreKit.RESTORED]] | + | [[StoreKit.RESTORED]]<br/> |
|} | |} |
Revision as of 09:12, 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`.
{|-
| 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