In-App Purchasing (IAP)

Product Identifiers

Products are individually identified by a unique string known as a product identifier. Each store may use a different term, but in all cases it's a string value which must be unique for your app. It's recommended that you follow the reverse-domain naming convention across all stores, for example:

com.acmegames.SuperRunner.UnlockFullGame

Module Inclusion

Because each IAP provider utilizes a different module/plugin on the Solar2D side, you must load the proper one.

If you are only supporting one store, you can simply require() the proper module as follows:

local store = require( "store" )  -- iOS

local store = require( "plugin.google.iap.billing" )  -- Android

local store = require( "plugin.amazon.iap" )  -- Amazon

Alternatively, if you want to support multiple platforms, a conditional routine can be implemented. In the following example, the system.getInfo() call is used to detect which store the built app will target, and that property is used to load the proper module.

local store

local targetAppStore = system.getInfo( "targetAppStore" )

if ( "apple" == targetAppStore ) then  -- iOS
    store = require( "store" )
elseif ( "google" == targetAppStore ) then  -- Android
    store = require( "plugin.google.iap.billing" )
elseif ( "amazon" == targetAppStore ) then  -- Amazon
    store = require( "plugin.amazon.iap" )
else
    print( "In-app purchases are not available for this platform." )
end

Initialization

Once the proper module is loaded, you must initialize it using the store.init() call:

store.init( transactionListener )

The only required argument, transactionListener, is the function you intend to use to handle store transaction requests, including purchases and potential refunds. For example:

local function transactionListener( event )

    local transaction = event.transaction

    if ( transaction.isError ) then
        print( transaction.errorType )
        print( transaction.errorString )
    else
        -- No errors; proceed
    end
end

-- Initialize store
store.init( transactionListener )

Product Properties

When products are loaded, the product listener function (productListener argument for store.loadProducts()) will receive an event table as its sole argument. The properties/keys associated with this table will differ slightly because of core variances in store functionality, but at the very minimum, these two properties will be available:

• event.products — A table in which each element is another table containing detailed product information. This is primarily the table you'll need to inspect to get detailed information about the loaded products.

• event.invalidProducts — A table in which each element is a string representing a product identifier. This table will only be populated by products that don't exist or aren't available.

Typically, you should iterate (loop) through event.products to determine which products are available. For example:

local productIdentifiers = {
    "com.domainname.testProduct1",
    "com.domainname.testProduct2",
    "com.domainname.testProduct3",
}

local function productListener( event )

    for i = 1,#event.products do
        print( event.products[i].productIdentifier )
    end
end

-- Load store products; store must be properly initialized by this point!
store.loadProducts( productIdentifiers, productListener )

For each instance within event.products, various properties will be available and these properties can be used to create an interface (store scene) or display available products in some other manner. Because of core variances in store functionality, these properties will differ for each store, but the following common properties will be available for products in all stores:

• productIdentifier — A string representing the product identifier.
• title — A string representing the product title.
• description — A string representing the product description.
• localizedPrice — The product price as a localized currency string, for example $0.99.

Transaction Properties

When a transaction occurs, various properties will be available within the event.transaction table which is dispatched to the transaction listener function. Because of core variances in store functionality, these properties will differ for each store, but the following common properties will be available for transactions in all stores:

• state — A string indicating the state of the transaction, for example "purchased", "cancelled", or "failed".
• identifier — The unique string identifier for the transaction.
• productIdentifier — A string representing the product identifier associated with the transaction.
• receipt — A JSON-formatted string representation of the transaction receipt.
• date — A string representing the date when the transaction occurred.
• isError — Boolean value indicating whether an error occurred. If this is true, errorType and errorString will be strings stating the reason.
• errorType — A string representing the type of error that occurred if isError is true.
• errorString — A more descriptive error message (string) if isError is true.

After you receive a transaction event, you should take the appropriate action. For example, if the user successfully purchased an item, you might save this information to a file or local database and unlock the ability to use the item. This file can then be referenced in future sessions so you know that the item has been purchased.

The following is an example framework for the transaction listener function:

local function transactionListener( event )

    local transaction = event.transaction

    if ( transaction.isError ) then
        print( transaction.errorType )
        print( transaction.errorString )
    else
        -- No errors; proceed
        if ( transaction.state == "purchased" or transaction.state == "restored" ) then
            -- Handle a normal purchase or restored purchase here
            print( transaction.state )
            print( transaction.productIdentifier )
            print( transaction.date )

        elseif ( transaction.state == "cancelled" ) then
            -- Handle a cancelled transaction here

        elseif ( transaction.state == "failed" ) then
            -- Handle a failed transaction here
        end

        -- Tell the store that the transaction is complete
        -- If you're providing downloadable content, do not call this until the download has completed
        store.finishTransaction( transaction )
    end
end

-- Initialize store
store.init( transactionListener )

        end

        -- Tell the store that the transaction is complete
        -- If you're providing downloadable content, do not call this until the download has completed
        store.finishTransaction( transaction )
    end
end

Purchasing Disabled (Apple)

iOS devices have a setting which can disable in-app purchasing entirely. This is commonly used to prevent children from accidentally purchasing items without permission. For Apple IAP, Solar2D provides the store.canMakePurchases property to check whether purchasing is enabled or disabled. You should use this to check in advance if purchasing is allowed and notify the user if it's forbidden.

Consuming Items (Google)

Google IAP requires that you consume purchases to make item(s) available for purchase again. Essentially, once a product is purchased, it is considered "owned" and it cannot be purchased again. However, since you'll almost certainly want to encourage players to buy certain items again — gem/coin packs, extra lives, etc. — you must send a consumption request to revert "owned" products to "unowned" products so that they become available for purchase again. Consuming products also discards their previous purchase data.

To consume items, call store.consumePurchase() with the associated product identifier:

store.consumePurchase( productIdentifier )

When invoked, and upon receipt of a successful consumption event, the value of event.transaction.state within the transaction listener function will be "consumed". At this point, you may re-enable the product for purchase within your user interface or store scene.

Handling Refunds (Google)

Google IAP allows for transactions to be refunded (instructions). Upon receipt of a successful refund event, the value of event.transaction.state within the transaction listener function will be "refunded" and, in this case, you can disable the content that was refunded and/or delete it from the app locally if it was downloaded.

Sandbox Mode (Amazon)

Amazon lets you test in-app purchasing via a "sandbox" mode in which no real purchases are made. If you want to implement some form of debugging in your Solar2D app, you can use the store.isSandboxMode() API to check if the app is currently in testing mode.