应用内购买 (IAP)

产品标识符

产品由称为**产品标识符**的唯一字符串标识。每个商店可能使用不同的术语，但在所有情况下它都是一个字符串值，对于您的应用必须是唯一的。建议您在所有商店中遵循反向域名命名约定，例如

com.acmegames.SuperRunner.UnlockFullGame

模块包含

由于每个 IAP 提供商在 Solar2D 端使用不同的模块/插件，因此您必须加载正确的模块/插件。

如果您只支持一个商店，您可以简单地使用 `require()` 加载相应的模块，如下所示

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

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

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

或者，如果您要支持多个平台，则可以实现条件例程。在以下示例中，使用 system.getInfo() 调用来检测构建的应用将面向哪个商店，并使用该属性来加载相应的模块。

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

初始化

加载正确的模块后，您必须使用 `store.init()` 调用对其进行初始化

store.init( transactionListener )

唯一必需的参数 `transactionListener` 是您打算用于处理商店**交易**请求的函数，包括购买和潜在退款。例如

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 )

产品属性

加载产品后，产品侦听器函数（`store.loadProducts()` 的 `productListener` 参数）将接收一个 `event` 表作为其唯一参数。由于商店功能的核心差异，与此表关联的属性/键会略有不同，但至少会有以下两个属性可用

• `event.products` — 一个表，其中每个元素是另一个包含详细产品信息的表。这主要是您需要检查以获取有关已加载产品的详细信息的表。

• `event.invalidProducts` — 一个表，其中每个元素都是一个表示产品标识符的字符串。此表将仅由不存在或不可用的产品填充。

通常，您应该遍历（循环）`event.products` 以确定哪些产品可用。例如

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 )

对于 `event.products` 中的每个实例，都会提供各种属性，这些属性可用于创建界面（商店场景）或以其他方式显示可用的产品。由于商店功能的核心差异，这些属性会因商店而异，但以下通用属性适用于所有商店的产品：

• productIdentifier — 表示产品标识符的字符串。
• title — 表示产品标题的字符串。
• description — 表示产品描述的字符串。
• localizedPrice — 产品价格，以本地化货币字符串表示，例如 `$0.99`。

交易属性

发生交易时，分派给交易侦听器函数的 `event.transaction` 表中将提供各种属性。由于商店功能的核心差异，这些属性会因商店而异，但以下通用属性适用于所有商店的交易：

• state — 指示交易状态的字符串，例如 `"purchased"`、`"cancelled"` 或 `"failed"`。
• identifier — 交易的唯一字符串标识符。
• productIdentifier — 表示与交易关联的产品标识符的字符串。
• receipt — 交易收据的 JSON 格式字符串表示形式。
• date — 表示交易发生日期的字符串。
• isError — 布尔值，指示是否发生错误。如果为 `true`，则 `errorType` 和 `errorString` 将是说明原因的字符串。
• errorType — 如果 `isError` 为 `true`，则表示发生的错误类型的字符串。
• errorString — 如果 `isError` 为 `true`，则为更详细的错误消息（字符串）。

收到交易事件后，您应该采取适当的行动。例如，如果用户成功购买了一件商品，您可以将此信息保存到文件或本地数据库中，并解锁使用该商品的功能。然后，可以在以后的会话中引用此文件，以便您知道该商品已被购买。

以下是交易侦听器函数的示例框架：

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

禁用购买 (Apple)

iOS 设备有一个可以禁用应用内所有购买的设置。这通常用于防止儿童在未经许可的情况下意外购买商品。对于 Apple IAP，Solar2D 提供了 store.canMakePurchases 属性来检查购买是否已启用或禁用。您应该使用此属性提前检查是否允许购买，并在禁止购买时通知用户。

消耗商品 (Google)

Google IAP 要求您消耗购买的商品，才能再次购买该商品。本质上，一旦产品被购买，它就被视为“已拥有”，并且不能再次购买。但是，由于您几乎肯定希望鼓励玩家再次购买某些商品（例如宝石/硬币包、额外的生命等），因此您必须发送消耗请求将“已拥有”的产品恢复为“未拥有”产品，以便它们可以再次购买。消耗产品还会丢弃其以前的购买数据。

要消耗商品，请使用关联的产品标识符调用 store.consumePurchase()

store.consumePurchase( productIdentifier )

调用后，并在收到成功的消耗事件后，交易侦听器函数中 `event.transaction.state` 的值将为 `"consumed"`。此时，您可以重新启用用户界面或商店场景中的产品购买。

处理退款 (Google)

Google IAP 允许退款交易（说明）。收到成功的退款事件后，交易侦听器函数中 `event.transaction.state` 的值将为 `"refunded"`，在这种情况下，您可以禁用已退款的内容和/或将其从本地应用中删除（如果已下载）。

沙盒模式 (Amazon)

Amazon 允许您测试应用内通过“沙盒”模式进行购买，在这种模式下不会进行实际购买。如果您想在 Solar2D 应用中实现某种形式的调试，可以使用 store.isSandboxMode() API 检查应用当前是否处于测试模式。