IAP SDK 编程

实例化 Samsung 应用程序内购买

在您的应用程序发出 IAP 请求之前，它必须调用 getInstance() 以创建 IapHelper 的单一实例。

请求

public static IapHelper getInstance( Context _context )

参数

参数	类型	说明
_context	Context	（必需）Android 上下文

返回值

IapHelper

代码片段

Java

private IapHelper iapHelper = IapHelper.getInstance(context);

Kotlin

private val iapHelper: IapHelper = IapHelper.getInstance(context)

设置 IAP 操作模式

IAP 支持三种操作模式。一种用于对项目购买启用计费，另两种用于测试 IAP 功能而不针对项目购买向应用程序用户计费。

如果未调用 setOperationMode()，则默认情况下操作模式设置为 OPERATION_MODE_PRODUCTION（不支持测试，但支持 Beta 版发布和正常发布）。

Caution在提交应用程序以供进行 Beta 版测试或正常发布之前，请确保操作模式设置为 OPERATION_MODE_PRODUCTION。换言之，仅当卖家门户中的应用程序状态为正在注册或正在更新时，才必须设置 OPERATION_MODE_TEST 或 OPERATION_MODE_TEST_FAILURE。

模式	说明
`OPERATION_MODE_PRODUCTION`	startPayment() 请求将按指定的方式处理，执行财务交易以使请求成功，并返回实际结果（成功或失败）。注意：所有其他 IAP SDK 请求将按如下方式工作：只有在 `OPERATION_MODE_PRODUCTION` 模式下购买的项目才会视为已拥有的项目。
`OPERATION_MODE_TEST`	startPayment() 请求将按指定的方式处理，未发生财务交易除外（将不会针对项目购买向已许可的测试者计费），并且始终返回成功的结果。有关 `OPERATION_MODE_TEST` 模式下显示的付款窗口的详细信息，请参见下面所示。注意：所有其他 IAP SDK 请求将按如下方式工作：只有在 `OPERATION_MODE_TEST` 模式下购买的项目才会视为已拥有的项目。要购买应用程序内项目，测试者必须在卖家的卖家门户配置文件中注册为已许可测试者。在此模式下，已许可测试者始终可免费获取您的应用程序内项目。如果所有其他用户尝试购买应用程序内项目，将会显示错误消息。
`OPERATION_MODE_TEST_FAILURE`	所有 IAP SDK 请求将失败。这旨在用作负面测试，以确保您的应用程序可以处理诸如输入和用户操作不正确这样的错误。

模式

说明

OPERATION_MODE_PRODUCTION

startPayment() 请求将按指定的方式处理，执行财务交易以使请求成功，并返回实际结果（成功或失败）。

注意：所有其他 IAP SDK 请求将按如下方式工作：

只有在 OPERATION_MODE_PRODUCTION 模式下购买的项目才会视为已拥有的项目。

OPERATION_MODE_TEST

startPayment() 请求将按指定的方式处理，未发生财务交易除外（将不会针对项目购买向已许可的测试者计费），并且始终返回成功的结果。
有关 OPERATION_MODE_TEST 模式下显示的付款窗口的详细信息，请参见下面所示。

注意：所有其他 IAP SDK 请求将按如下方式工作：

只有在 OPERATION_MODE_TEST 模式下购买的项目才会视为已拥有的项目。
要购买应用程序内项目，测试者必须在卖家的卖家门户配置文件中注册为已许可测试者。在此模式下，已许可测试者始终可免费获取您的应用程序内项目。如果所有其他用户尝试购买应用程序内项目，将会显示错误消息。

OPERATION_MODE_TEST_FAILURE

所有 IAP SDK 请求将失败。
这旨在用作负面测试，以确保您的应用程序可以处理诸如输入和用户操作不正确这样的错误。

Note如果设置了 OPERATION_MODE_TEST，则会显示下面的弹出窗口，并且付款窗口的右上角将显示 Sandbox，指示将不会针对项目购买向应用程序用户计费。

请求

public void setOperationMode( OperationMode _mode )

参数

参数	类型	说明
_mode	OperationMode	（必需）IAP 操作模式，用于控制对 IAP SDK API 请求的处理： `OPERATION_MODE_PRODUCTION` `OPERATION_MODE_TEST` `OPERATION_MODE_TEST_FAILURE`

代码片段

Java

iapHelper.setOperationMode(HelperDefine.OperationMode.OPERATION_MODE_TEST);

Kotlin

iapHelper.setOperationMode(HelperDefine.OperationMode.OPERATION_MODE_TEST)

获取用户拥有的项目

Requirement请确保在启动应用程序以检查未消耗的项目或订阅可用性时，始终调用 getOwnedList()。

getOwnedList() 返回应用程序用户通过先前的购买当前获得的应用程序内项目列表。

尚未使用且尚未报告为已消耗的消耗性项目
非消耗性项目

当前处于免费试用期或有效订阅期的订阅项目

包括已取消的订阅项目，直到其有效订阅期结束
如果订阅价格发生变动，将包括新价格、续订日期和用户同意等信息

请求

public boolean getOwnedList
(   
    String                        _productType,
    OnGetOwnedListListener        _onGetOwnedListListener
)

参数

参数	类型	说明
_productType	String	（必需）要返回的应用程序内项目的类型： `item`:消耗性项目和非消耗性项目 `subscription`：自动定期订阅项目 `all`：消耗性项目、非消耗性项目和自动定期订阅项目
_onGetOwnedListListener		（必需）指定要返回的项目数据和处理结果的 `OnGetOwnedListListener` 接口的名称

返回值

true - 请求已成功发送到服务器，并且结果将发送到 OnGetOwnedListListener 接口侦听器。
false - 请求未发送到服务器并且未处理。

响应

void onGetOwnedProducts(ErrorVo errorVo, ArrayList<OwnedProductVo> ownedList)

参数

参数	类型	说明
errorVo	ErrorVo	已处理的请求结果
ownedList	ArrayList<OwnedProductVo>	包含应用程序用户拥有的应用程序内项目的对象

ErrorVo

Getter	返回类型	说明
getErrorCode()	int	响应代码有关详细信息，请参阅“响应代码”
getErrorString()	String	错误消息
getErrorDetailsString()	String	有关结果的其他信息
isShowDialog()	boolean	`true`:过程失败之后，将会显示错误消息对话框。 `false`：过程失败之后，不会显示错误消息对话框。

OwnedProductVo

Getter	返回类型	说明
getItemId()	String	应用程序内项目的唯一 ID
getItemName()	String	应用程序内项目的标题
getItemPrice()	Double	应用程序内项目以本地货币表示的当前本地价格（例如 7.99）
getItemPriceString()	String	本地货币符号和价格（本地货币格式）：货币符号 + 价格（例如 £7.99）价格 + 货币符号（例如 66815₫）
getCurrencyUnit()	String	本地货币的符号（例如 €、£ 或 $）
getCurrencyCode()	String	本地货币的货币代码（3 个字符）（例如 EUR、GBP、USD）
getItemDesc()	String	应用程序内项目的说明
getType()	String	应用程序内项目的类型： `"item"`:消耗性项目或非消耗性项目 `"subscription"`:自动定期订阅
getIsConsumable()	boolean	应用程序内项目是否为消耗性项目。 `true`:消耗性应用程序内项目 `false`:非消耗性应用程序内项目（非消耗性项目或自动定期订阅）注意：如果为 `true`，则消耗性项目尚未报告为已消耗。可以再次购买此类项目之前，必须通过调用 consumePurchasedItems() 报告这些项目
getPaymentId()	String	Samsung IAP 为应用程序内项目的已确认付款分配的唯一标识符
getPurchaseId()	String	Samsung IAP 为应用程序内项目的购买交易分配的唯一标识符
getPurchaseDate()	String	项目购买和付款交易的日期和时间 (YYYY-MM-DD HH:mm:ss)
getSubscriptionEndDate()	String	仅适用于订阅应用程序内项目，项目的当前订阅期限将过期的日期和时间 (YYYY-MM-DD HH:mm:ss)
getPassThroughParam()	String	您的应用程序为项目购买和付款交易分配的唯一标识符如果未分配直通参数，将返回空字符串 ("")。
getSubscriptionPriceChange()	SubscriptionPriceChangeVo	订阅价格变动信息
getJsonString()	String	完全 JSON 有效负载

SubscriptionPriceChangeVo

Getter	返回类型	说明
getAppName()	String	应用程序名称
getItemName()	String	应用程序内项目的标题
getSubscriptionDurationMultiplier()	String	时间基本单位的数值倍数，用于确定订阅期限倍数与 `getSubscriptionDurationUnit()` 返回的值结合使用。
getSubscriptionDurationUnit()	String	每个订阅期限的时间基本单位（“YEAR”、“MONTH”、“WEEK”）注：这些单位始终以大写字母的形式返回。
getStartDate()	String	新价格开始对订阅者生效的日期和时间 (YYYY‑MM‑DD HH:mm:ss)
getOriginalLocalPrice()	Double	应用程序内项目的原本地价格（例如 7.99）
getOriginalLocalPriceString()	String	本地货币符号和价格（本地货币格式）：货币符号 + 价格（例如 £7.99）价格 + 货币符号（例如 66815₫）
getNewLocalPrice()	Double	应用程序内项目的新本地价格（例如 9.99）
getNewLocalPriceString()	String	本地货币符号和价格（本地货币格式）：货币符号 + 价格（例如 £9.99）价格 + 货币符号（例如 70000₫）
isConsented()	boolean	指示用户是否已同意价格变动（参见下面的 getPriceChangeMode()） `true`: 用户已同意价格变动。 `false`: T用户未同意价格变动。如果需要用户作出同意，Samsung 建议您添加弹出窗口、通知或设置，以允许现有订阅者续订（参见价格上调通知中的通知示例）。消息中还应提供订阅详情页面的深度链接，用于引导用户访问同意页面（在 Samsung 移动设备上）： samsungapps://SubscriptionDetail?purchaseId={purchaseId}
getPriceChangeMode()	PriceChangeMode	`PRICE_INCREASE_USER_AGREEMENT_REQUIRED`: 价格上调要求现有订阅者作出同意。用户必须明确接受价格上调后才能续订。 `PRICE_INCREASE_NO_USER_AGREEMENT_REQUIRED`: 价格上调不要求现有订阅者执行任何操作。除非用户选择退出，否则在下一次常规订阅付款日，将按新的价格收费。 `PRICE_DECREASE`: 在下一次常规订阅付款日，对现有订阅者实施价格下调。

代码片段

Java

iapHelper.getOwnedList(HelperDefine.PRODUCT_TYPE_ALL, new OnGetOwnedListListener() {
    @Override
    public void onGetOwnedProducts(@NonNull ErrorVo errorVo, @NonNull ArrayList<OwnedProductVo> ownedList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (OwnedProductVo item : ownedList) {
                if (item.getIsConsumable()) {
                    // TODO: Consume the consumable item not yet consumed
                }
                
                // TODO: Check if the subscription price has changed and user consent is required
                SubscriptionPriceChangeVo subscriptionPriceChangeVo = item.getSubscriptionPriceChange();
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.getOwnedList(IapHelper.PRODUCT_TYPE_ALL)
{ errorVo: ErrorVo, ownedList: ArrayList<OwnedProductVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in ownedList) {
            if (item.isConsumable) {
                // TODO: Consume the consumable item not yet consumed
            }
            
            // TODO: Check if the subscription price has changed and user consent is required
            val subscriptionPriceChangeVo = item.subscriptionPriceChange
        }
    } else {
        // TODO: Handle the error
    }
}

获取应用程序内项目详细信息

getProductsDetails() 返回应用程序中注册的一个、多个或所有应用程序内项目的信息。
返回 OnGetProductsDetailsListener 接口指定的项目数据和处理结果。

请求

public void getProductsDetails
(   
    String                           _productIds,
    OnGetProductsDetailsListener     _onGetProductsDetailsListener
)

参数

参数	类型	说明
_productIds	String	（必需）由下面两项内容之一指定的一个或多个应用程序内项目 ID：空字符串 ("")，指定所有应用程序内项目或逗号分隔的一个或多个唯一的应用程序内项目 ID 值（例如“coins，blocks，lives”）您可以从卖家门户中获取这些 ID（应用程序页面 > 单击应用程序的状态 > 应用程序内购买选项卡 > 项目 ID）。
_onGetProductsDetailsListener	（必需）指定要返回的项目数据和处理结果的 `OnGetProductsDetailsListener` 接口的名称

类型

说明

_productIds

String

（必需）由下面两项内容之一指定的一个或多个应用程序内项目 ID：

空字符串 ("")，指定所有应用程序内项目或
逗号分隔的一个或多个唯一的应用程序内项目 ID 值（例如“coins，blocks，lives”）

您可以从卖家门户中获取这些 ID（应用程序页面 > 单击应用程序的状态 > 应用程序内购买选项卡 > 项目 ID）。

_onGetProductsDetailsListener

（必需）指定要返回的项目数据和处理结果的 OnGetProductsDetailsListener 接口的名称

响应

void onGetProducts(ErrorVo errorVo, ArrayList<ProductVo> productList)

参数

参数	类型	说明
errorVo	ErrorVo	已处理的请求结果
productList	ArrayList<ProductVo>	包含应用程序内项目详细信息的对象

ErrorVo

Getter	返回类型	说明
getErrorCode()	int	响应代码有关详细信息，请参阅“响应代码”
getErrorString()	String	错误消息
getErrorDetailsString()	String	有关结果的其他信息
isShowDialog()	boolean	`true`:过程失败之后，将会显示错误消息对话框。 `false`：过程失败之后，不会显示错误消息对话框。

ProductVo

Getter	返回类型	说明
getItemId()	String	应用程序内项目的唯一 ID
getItemName()	String	应用程序内项目的标题
getItemPrice()	Double	应用程序内项目以本地货币表示的当前本地价格（例如 7.99） Note: When displayed, this string always includes the two digits to the right of the decimal point (and does not display the currency symbol). For example, if the local price is 8 euros, the value "8.00" is displayed. If you don't want to display the decimal point and the two digits to the right of the decimal point when the price is a whole number, use getItemPriceString() instead.
getItemPriceString()	String	本地货币符号和价格（本地货币格式）：货币符号 + 价格（例如 £7.99）价格 + 货币符号（例如 66815₫） Note: When displayed, this string always includes the two digits to the right of the decimal point (and does not display the currency symbol). For example, if the local price is 8 euros, the value "8.00" is displayed. If you don't want to display the decimal point and the two digits to the right of the decimal point when the price is a whole number, use getItemPriceString() instead.
getCurrencyUnit()	String	本地货币的符号（例如 €、£ 或 $）
getCurrencyCode()	String	本地货币的货币代码（3 个字符）（例如 EUR、GBP、USD）
getItemDesc()	String	应用程序内项目的说明
getType()	String	应用程序内项目的类型： `"item"`:消耗性项目或非消耗性项目 `"subscription"`:自动定期订阅
getIsConsumable()	boolean	应用程序内项目是否为消耗性项目 `true`:消耗性应用程序内项目 `false`:非消耗性应用程序内项目（非消耗性项目或自动定期订阅）
getSubscriptionDurationUnit()	String	仅适用于订阅应用程序内项目，每个订阅期限的时间基本单位（`"YEAR"`、`"MONTH"`、`"WEEK"`）。注意：单位必须为大写。
getSubscriptionDurationMultiplier()	String	仅适用于订阅项目，时间基本单位的数值倍数（例如 1YEAR、2MONTH、4WEEK），用于确定项目的订阅期限倍数与 `getSubscriptionDurationUnit()` 返回的值结合使用。
getTieredSubscriptionYN()	String	仅适用于订阅项目，无论项目是否具有两层定价 `"Y"`：项目具有一个或多个低层价格订阅期限，到期后采用常规价格期限 `"N"`：项目仅具有常规价格订阅期限
getTieredPrice()	String	仅适用于两层订阅项目，以本地货币表示的低层价格（例如 7.99）
getTieredPriceString()	String	仅适用于两层订阅项目，本地货币符号和价格（本地货币格式）：货币符号 + 价格（例如 £7.99）价格 + 货币符号（例如 66815₫）
getTieredSubscriptionDurationUnit()	String	仅适用于两层订阅项目，每个订阅期限的时间基本单位（`"YEAR"`、`"MONTH"`、`"WEEK"`）。注意：单位必须为大写。
getTieredSubscriptionDurationMultiplier()	String	仅适用于两层订阅项目，时间基本单位的数值倍数（例如 1YEAR、2MONTH、4WEEK），用于确定项目的订阅期限倍数与 `getTieredSubscriptionDurationUnit()` 返回的值结合使用。
getTieredSubscriptionCount()	String	如果项目同时具有低层订阅价格和常规层订阅价格，则为低层订阅期限的数目。
getShowStartDate()	String	项目将可供购买的开始日期和时间 (YYYY-MM-DD HH:mm:ss)
getShowEndDate()	String	此后项目将不可供购买的结束日期和时间 (YYYY-MM-DD HH:mm:ss)
getItemImageUrl()	String	项目的图像和缩略图的 URL
getItemDownloadUrl()	String	用于下载项目的 URL
getFreeTrialPeriod()	String	项目的订阅前免费试用期的持续时间（天）：7 到 999 天
getJsonString()	String	完全 JSON 有效负载

代码片段

Java

iapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp", new OnGetProductsDetailsListener() {
    @Override
    public void onGetProducts(@NonNull ErrorVo errorVo, @NonNull ArrayList<ProductVo> productList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (ProductVo item : productList) {
                // TODO: Get details of the item
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp")
{ errorVo: ErrorVo, productList: ArrayList<ProductVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in productList) {
            // TODO: Get details of the item
        }
    } else {
        // TODO: Handle the error
    }
}

购买应用程序内项目

startPayment() 启动对所指定应用程序内项目的购买和付款交易，并可通知最终用户该购买已成功还是失败。返回 OnPaymentListener 接口中指定的项目数据、交易结果和数据。

您可以指定 passThroughParam 参数值以增强购买安全性。使用由集成了 IAP 的应用程序创建和传递的 passThroughParam 值进行购买时，将在响应中返回值。

Caution当 IAP 操作模式为 OPERATION_MODE_PRODUCTION 并且正在 Galaxy Store 中分发应用程序时，则为财务交易的成功处理结果（将针对项目购买向应用程序用户计费）。

请求

public boolean startPayment
(
    String                  _itemId,
    String                  _passThroughParam,
    OnPaymentListener       _onPaymentListener
)

参数

参数	类型	说明
_itemId	String	（必需）要购买的应用程序内项目的唯一标识符值。
_passThroughParam	String	可选唯一标识符（最大值：255 字节），由您的 Android 应用程序分配给购买和付款交易。指定后，该值将由 `OnPaymentListener` 接口返回。当从 Samsung IAP 服务器 API 调用 iap/v6/receipt 以验证购买时，该值将由 pathThroughParam 字段返回。
_onPaymentListener		（必需）`OnPaymentListener` 接口的名称，该接口指定要返回的购买和付款交易数据、项目数据和处理结果。

返回值

true:请求已成功发送到服务器，并且结果将发送到 OnPaymentListener 接口侦听器。
false:请求未发送到服务器并且未处理。

响应

void onPayment(ErrorVo errorVo, PurchaseVo purchaseVo)

参数

参数	类型	说明
errorVo	ErrorVo	已处理的请求结果
purchaseVo	PurchaseVo	包含购买结果的对象

ErrorVo

Getter	返回类型	说明
getErrorCode()	int	响应代码（例如 -1003）有关详细信息，请参阅“响应代码”
getErrorString()	String	错误消息（例如“已购买”。）
getErrorDetailsString()	String	有关结果的其他信息（例如 IS9224/6050/NwCbCAxypi）
isShowDialog()	boolean	`true`:过程失败之后，将会显示错误消息对话框。 `false`：过程失败之后，不会显示错误消息对话框。

PurchaseVo

Getter	返回类型	说明
getItemId()	String	应用程序内项目的唯一 ID
getItemName()	String	应用程序内项目的标题
getItemPrice()	Double	应用程序内项目以本地货币表示的当前本地价格（例如 7.99） Note: When displayed, this string always includes the two digits to the right of the decimal point (and does not display the currency symbol). For example, if the local price is 8 euros, the value "8.00" is displayed. If you don't want to display the decimal point and the two digits to the right of the decimal point when the price is a whole number, use getItemPriceString() instead.
getItemPriceString()	String	本地货币符号和价格（本地货币格式）：货币符号 + 价格（例如 £7.99）价格 + 货币符号（例如 66815₫） Note: When displayed, if the price is a whole number, the decimal point and the two digits to the right of the decimal point are not displayed. For example, if the local price is 8 euros, the value "€8" is displayed. If you want to display the two digits to the right of the decimal point (even if the price is a whole number), use getItemPrice() instead.
getCurrencyUnit()	String	本地货币的符号（例如 €、£ 或 $）
getCurrencyCode()	String	本地货币的货币代码（3 个字符）（例如 EUR、GBP、USD）
getItemDesc()	String	应用程序内项目的说明
getType()	String	应用程序内项目的类型： `"item"`:消耗性项目或非消耗性项目 `"subscription"`:自动定期订阅
getIsConsumable()	boolean	应用程序内项目是否为消耗性项目 `true`：消耗性应用程序内项目 `false`:非消耗性应用程序内项目（非消耗性项目或自动定期订阅）注意：我们建议在验证消耗性应用程序内项目的购买后，通过调用 consumePurchasedItems() 来将项目报告为已消耗。
getPaymentId()	String	Samsung IAP 为应用程序内项目的付款交易分配的唯一标识符
getPurchaseId()	String	Samsung IAP 为应用程序内项目的购买交易分配的唯一标识符
getPurchaseDate()	String	项目购买的日期和时间 (YYYY-MM-DD HH:mm:ss)
getVerifyUrl()	String	自 IAP 6.0 起已弃用请参阅“验证购买”以获取 IAP 服务器 URL，从而验证使用由 `getPurchaseId()` 返回的购买 ID 进行的购买。
getPassThroughParam()	String	您的应用程序为项目购买和付款交易分配的唯一标识符如果未分配直通参数，将返回空字符串 ("")。
getItemImageUrl()	String	项目的图像和缩略图的 URL
getItemDownloadUrl()	String	用于下载项目的 URL
getOrderId()	String	订单的唯一标识符
getJsonString()	String	完全 JSON 有效负载

代码片段

Java

iapHelper.startPayment("Nuclear", "pLKjLKjLJL87=76df56rf+4f5", new OnPaymentListener() {
    @Override
    public void onPayment(@NonNull ErrorVo errorVo, @Nullable PurchaseVo purchaseVo) {
		if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
                String passThroughParam = _purchaseVo.getPassThroughParam();
                // TODO: If you have set a PassThroughParameter in the request,  
                //       you can verify the PassThroughParameter here.

                if (purchaseVo.getIsConsumable()) {
                    String purchaseId = purchaseVo.getPurchaseId();
                    // TODO: Consume the consumable item by calling `consumePurchasedItems()`
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.startPayment("Nuclear", "pLKjLKjLJL87=76df56rf+4f5")
{ errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        if (purchaseVo != null) {
            val passThroughParam: String = purchaseVo.passThroughParam
            // TODO: If you have set a PassThroughParameter in the request,  
            //       you can verify the PassThroughParameter here.

            if (purchaseVo.isConsumable) {
                val purchaseId: String = purchaseVo.purchaseId
                // TODO: Consume the consumable item by calling `consumePurchasedItems()`
            }
        }
    } else {
        // TODO: Handle the error
    }
}

Note当您尝试在应用程序中购买项目时，将会显示与下面所示类似的弹出窗口。您必须登录您的 Samsung 帐户。

确认已购买的消耗性项目

consumePurchasedItems() 将一个或多个已购买的消耗性项目报告为已消耗，这样可以再次购买这些项目。应用程序用户可以使用这些项目，也可以不使用。返回 OnConsumePurchasedItemsListener 接口指定的项目数据和处理结果。

Note在一个 consumePurchasedItems() 方法调用中验证项目的购买并报告所有未报告的项目之后，我们建议立即报告已购买的消耗性项目，以避免发生系统过载或故障。

请求

public boolean consumePurchasedItems
(
  String                             _purchaseIds,
  OnConsumePurchasedItemsListener    _onConsumePurchasedItemsListener
)

参数

参数	类型	说明
_purchaseIds	String	（必需）消耗性应用程序内项目（要报告为已消耗）的购买和付款交易的一个或多个唯一标识符值（逗号分隔）
_onConsumePurchasedItemsListener		（必需）指定要返回的项目数据和处理结果的 `OnConsumePurchasedItemsListener` 接口的名称

返回值

true:请求已成功发送到服务器，并且结果将发送到 OnConsumePurchasedItemsListener 接口侦听器。
false:请求未发送到服务器并且未处理。

响应

void onConsumePurchasedItems(ErrorVo errorVo, ArrayList<ConsumeVo> consumeList)

参数

参数	类型	说明
errorVo	ErrorVo	已处理的请求结果
consumeList	ArrayList<ConsumeVo>	已消耗项目的列表注意：即使由于意外错误而无法消耗某些项目，这些项目仍将包括在 `_consumeList` 中，并且可以使用 ConsumeVo.getStatusCode() 检查每个项目的结果。

ErrorVo

Getter	返回类型	说明
getErrorCode()	int	响应代码有关详细信息，请参阅“响应代码”
getErrorString()	String	错误消息
getErrorDetailsString()	String	有关结果的其他信息
isShowDialog()	boolean	`true`:过程失败之后，将会显示错误消息对话框。 `false`：过程失败之后，不会显示错误消息对话框。

ConsumeVo

Getter	返回类型	说明
getPurchaseId()	String	Samsung IAP 为应用程序内项目的购买交易分配的唯一标识符
getStatusCode()	int	状态代码 `0` :成功 `1` :无效的购买 ID `2` :订单失败 `3` :非消耗性项目 `4` :已消耗 `5` :未授权的用户 `9` :意外的服务错误
getStatusString()	String	状态消息 `0` :“成功” `1` :“找不到具有此购买 ID 的订单。” `2` :“无法消耗此购买，因为它不是成功的订单。” `3` :“此类型的项目不是消耗性项目。” `4` :“已消耗此购买。” `5` :“无法消耗此购买，因为用户无权消耗此订单。” `9` :“服务错误”
getJsonString()	String	完全 JSON 有效负载

代码片段

Java

final String PURCHASEID = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590";

iapHelper.consumePurchasedItems(PURCHASEID, new OnConsumePurchasedItemsListener() {
    @Override
    public void onConsumePurchasedItems(@NonNull ErrorVo errorVo, @NonNull ArrayList<ConsumeVo> consumeList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (ConsumeVo item : consumeList) {
                // TODO: Get details of the consumption
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

val PURCHASEID: String = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590"

iapHelper.consumePurchasedItems(PURCHASEID)
{ errorVo: ErrorVo, consumeList: ArrayList<ConsumeVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in consumeList) {
            // TODO: Get details of the consumption
        }
    } else {
        // TODO: Handle the error
    }
}

获取订阅的优惠资格要求

getPromotionEligibility() 返回为客户提供的订阅项目定价选项，例如免费试用期和初始优惠价。在客户进行购买时，您就可以告知每位客户有资格享受的优惠。客户还可以在付款前查看可用优惠，从而更加积极地购买。

请求

public void getPromotionEligibility
(
  String _itemIds,
  OnGetPromotionEligibilityListener onGetPromotionEligibilityListener
)

参数

参数	类型	说明
_itemIds	String	(必需) 一个或多个应用程序内项目唯一 ID 值。使用逗号分隔多个值。例如，“coins,blocks,lives”
_onGetPromotionEligibilityListener		(必需) 定义用于发送定价策略的 `onGetPromotionEligibility()` 回调方法

返回值

void onGetPromotionEligibility(ErrorVo errorVo, ArrayList<PromotionEligibilityVo> pricingList)

参数

参数	类型	说明
errorVo	ErrorVo	已处理的请求结果
pricingList	ArrayList<PromotionEligibilityVo>	定价策略列表（参见 PromotionEligibilityVo).

ErrorVo

Getter	返回类型	说明
getErrorCode()	int	响应代码有关详细信息，请参阅“响应代码”
getErrorString()	String	错误消息
getErrorDetailsString()	String	有关结果的其他信息

PromotionEligibilityVo

Getter	返回类型	说明
getItemId()	String	已购项目的标识符。
getPricing()	String	对用户应用的定价： "FreeTrial" - 用户可以免费使用应用程序内项目的一个设定时间段。请查看免费试用期，了解有关此类订阅的更多信息。 "TieredPrice" - 在有限的时间内按照初始优惠价收费的订阅。请查看低层或折扣订阅，了解有关此类订阅的更多信息。 "RegularPrice" - 按照每个订阅期限的设定价格进行收费的订阅。请查看常规或常规层订阅，了解有关此类订阅的更多信息。

Getter

返回类型

说明

getItemId()

String

已购项目的标识符。

getPricing()

String

对用户应用的定价：

"FreeTrial" - 用户可以免费使用应用程序内项目的一个设定时间段。请查看免费试用期，了解有关此类订阅的更多信息。
"TieredPrice" - 在有限的时间内按照初始优惠价收费的订阅。请查看低层或折扣订阅，了解有关此类订阅的更多信息。
"RegularPrice" - 按照每个订阅期限的设定价格进行收费的订阅。请查看常规或常规层订阅，了解有关此类订阅的更多信息。

代码片段

Java

iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp", new OnGetPromotionEligibilityListener() {
    @Override
    public void onGetPromotionEligibility(@NonNull ErrorVo errorVo, @NonNull ArrayList<PromotionEligibilityVo> pricingList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (PromotionEligibilityVo pricing : pricingList) {
                // TODO: Get the pricing options of the subscription
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp")
{ errorVo: ErrorVo, pricingList: ArrayList<PromotionEligibilityVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in pricingList) {
            // TODO: Get the pricing options of the subscription
        }
    } else {
        // TODO: Handle the error
    }
}

更改订阅计划

changeSubscriptionPlan() 允许客户将现有订阅更改为相同订阅项目的其他等级。

更改可以是升级（从价格较低的等级更改为价格较高的等级，或者在两个同等价格的等级之间进行更改）或降级（从价格较高的等级更改为价格较低的等级）。

您必须指定 prorationMode 以选择如何对付款和当前订阅期限实施更改。

请求

public boolean changeSubscriptionPlan
(
  String _oldItemId,
  String _newItemId,
  ProrationMode _prorationMode,
  String _passThroughParam,
  OnChangeSubscriptionPlanListener _onChangeSubscriptionPlanListener
)

参数

参数	类型	说明
oldItemId	String	（必填）当前已订阅的订阅 ID
newItemId	String	（必填）即将订阅的订阅 ID
prorationMode	ProrationMode	（必填）在更改订阅时，有四种模式可供设置： `INSTANT_PRORATED_DATE`: 立即升级或降级订阅。剩余订阅时间将根据差价进行调整，并通过推迟下一次账单日的方式，将其计入新订阅周期。无需额外付款。 `INSTANT_PRORATED_CHARGE`: 仅适用于升级的订阅。立即升级订阅，但账单周期不变。向用户收取剩余期限的差价。 `INSTANT_NO_PRORATION`: F仅适用于升级的订阅。立即升级订阅，在续订时按新价格收费。账单周期不变。 `DEFERRED`: T续订时升级或降级订阅。续订时按新价格收费。降级将始终按该模式执行。请参见按比例调整模式，详细了解四种模式。
passThroughParam	String	可选唯一标识符（最大值：255 字节），由您的 Android 应用程序分配给购买和付款交易。指定后，该值将由 `OnPaymentListener` 接口返回。当从 Samsung IAP 服务器 API 调用 iap/v6/receipt 以验证购买时，该值将由 pathThroughParam 字段返回。
onChangeSubscriptionPlanListener		（必需） `OnChangeSubscriptionPlanListener` 接口的名称，该接口指定要返回的购买和付款交易数据、项目数据和处理结果。

返回值

true - 请求已成功发送到服务器，并且结果将发送到 OnChangeSubscriptionPlanListener 接口侦听器。
false - 请求未发送到服务器并且未处理。

响应

void onChangeSubscriptionPlan(ErrorVo errorVo, PurchaseVo purchaseVo)

参数

参数	类型	说明
errorVo	ErrorVo	已处理的请求结果
purchaseVo	PurchaseVo	包含购买结果的对象

ErrorVo

Getter	Return Type	Description
getErrorCode()	int	响应代码（例如 -1003）有关详细信息，请参阅“响应代码”
getErrorString()	String	错误消息（例如“已购买”。）
getErrorDetailsString()	String	有关结果的其他信息（例如 IS9224/6050/NwCbCAxypi）
isShowDialog()	boolean	`true`：过程失败之后，将会显示错误消息对话框。 `false`：过程失败之后，不会显示错误消息对话框。

PurchaseVo

Getter	返回类型	说明
getItemId()	String	应用程序内项目的唯一 ID
getItemName()	String	应用程序内项目的标题
getItemPrice()	Double	应用程序内项目以本地货币表示的当前本地价格（例如 7.99） Note: When displayed, this string always includes the two digits to the right of the decimal point (and does not display the currency symbol). For example, if the local price is 8 euros, the value "8.00" is displayed. If you don't want to display the decimal point and the two digits to the right of the decimal point when the price is a whole number, use getItemPriceString() instead.
getItemPriceString()	String	本地货币符号和价格（本地货币格式）：货币符号 + 价格（例如 £7.99）价格 + 货币符号（例如 66815₫） Note: When displayed, if the price is a whole number, the decimal point and the two digits to the right of the decimal point are not displayed. For example, if the local price is 8 euros, the value "€8" is displayed. If you want to display the two digits to the right of the decimal point (even if the price is a whole number), use getItemPrice() instead.
getCurrencyUnit()	String	本地货币的符号（例如 €、£ 或 $）
getCurrencyCode()	String	本地货币的货币代码（3 个字符）（例如 EUR、GBP、USD）
getItemDesc()	String	应用程序内项目的说明
getType()	String	应用程序内项目的类型： `"item"`:消耗性项目或非消耗性项目 `"subscription"`:自动定期订阅
getIsConsumable()	boolean	应用程序内项目是否为消耗性项目 `true`：消耗性应用程序内项目 `false`：非消耗性应用程序内项目（非消耗性项目或自动定期订阅）注意：我们建议在验证消耗性应用程序内项目的购买后，通过调用 consumePurchasedItems() 来将项目报告为已消耗。
getPaymentId()	String	Samsung IAP 为应用程序内项目的付款交易分配的唯一标识符
getPurchaseId()	String	Samsung IAP 为应用程序内项目的购买交易分配的唯一标识符
getPurchaseDate()	String	项目购买的日期和时间 (YYYY-MM-DD HH:mm:ss)
getVerifyUrl()	String	自 IAP 6.0 起已弃用请参阅“验证购买”以获取 IAP 服务器 URL，从而验证使用由 `getPurchaseId()` 返回的购买 ID 进行的购买。
getPassThroughParam()	String	您的应用程序为项目购买和付款交易分配的唯一标识符如果未分配直通参数，将返回空字符串 ("")。
getItemImageUrl()	String	项目的图像和缩略图的 URL
getItemDownloadUrl()	String	用于下载项目的 URL
getOrderId()	String	订单的唯一标识符
getJsonString()	String	完全 JSON 有效负载

代码片段

Java

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE,
    "pLKjLKjLJL87=76df56rf+4f5",
    new OnChangeSubscriptionPlanListener() {
        @Override
        public void onChangeSubscriptionPlan(@NonNull ErrorVo errorVo, @Nullable PurchaseVo purchaseVo) {
            if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
                if (purchaseVo != null) {
                	// TODO: Check details about your newly purchased subscription
                    
                    String passThroughParam = purchaseVo.getPassThroughParam();
                    // TODO: If you have set a PassThroughParameter in the request,
                    //       you can verify the PassThroughParameter here.
                }
            } else {
         	   // TODO: Handle the error
            }
        }
});

Kotlin

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE,
    "pLKjLKjLJL87=76df56rf+4f5")
	{ errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
        if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
                // TODO: Check details about your newly purchased subscription

                val passThroughParam: String = purchaseVo.passThroughParam
                // TODO: If you have set a PassThroughParameter in the request,  
                //       you can verify the PassThroughParameter here.
            }
        } else {
            // TODO: Handle the error
    	}
	}

响应代码

响应代码（值）	说明
IAP_ERROR_NONE (0)	成功
IAP_PAYMENT_IS_CANCELED (1)	付款已取消
IAP_ERROR_INITIALIZATION (-1000)	初始化 IAP 失败注意：可能错误的详细信息： `10000` :IAP 客户端应用程序无效。 `10001` :Samsung 结账应用程序无效。 `10011` :服务初始化失败。请重试。
IAP_ERROR_NEED_APP_UPGRADE (-1001)	需要升级 IAP
IAP_ERROR_COMMON (-1002)	运行 IAP 时出错注意：可能错误的详细信息： `1005` : 当订阅发生变动时，原有的订阅项目将不再存在 `1006` : 当订阅发生变动时，原有的订阅项目将不再有效 `1012` : 当订阅发生变动时，所指定的项目并不是一种订阅类型 `1014` : 订阅变更已申请 `7002`:由于为可疑交易，已被阻止 `9000`:设置 OPERATION_MODE_TEST_FAILURE 时 `getOwnedList()` 失败 `9005` :设置 OPERATION_MODE_TEST_FAILURE 时 `consumePurchasedItems()` 失败 `9006` :`PassThroughParam` 未采用 Base64 编码 `9007` :`PassThroughParam` 超过最大长度 `9010` :尚未消耗该项目 `9013` :设置 OPERATION_MODE_TEST_FAILURE 时 `getProductsDetails()` 失败 `9014` :设置 OPERATION_MODE_TEST_FAILURE 时 `startPayment()` 失败 `9122` :无效的 MCC `9132`:无效的令牌或用户 ID `9200` :服务错误（无效的 MCC、MNC 或 CSC） `9226` :`consumePurchasedItems()` 中的购买 ID 为空或无效 `9440` :连接蜂窝网络的设备不可用 `9441` :服务暂时不可用 `9701` :认证失败 `100001` :由于出现意外错误，请求结果未正常返回 `100008` :不同意运行时权限 `100010` :设置 OPERATION_MODE_TEST 并且用户不是已许可的测试者时，`startPayment()` 失败
IAP_ERROR_ALREADY_PURCHASED (-1003)	再次购买非消耗性项目或者在订阅过期前再次购买订阅时出错。注意：可能错误的详细信息： `9224` :再次购买非消耗性项目或者在订阅过期前再次购买订阅
IAP_ERROR_WHILE_RUNNING (-1004)	发出不包含任何信息的付款请求时出错。
IAP_ERROR_PRODUCT_DOES_NOT_EXIST (-1005)	请求的项目不可用时出错注意：可能错误的详细信息： `9202` :在分发应用程序的国家/地区或设备中，请求的项目无效。请在卖家门户中检查应用程序分发条件。 `9207` :当前操作模式下，请求的 itemID 不存在。请检查 ItemID。
IAP_ERROR_CONFIRM_INBOX (-1006)	向服务器发出购买请求之后，应用程序未收到购买结果时出错。在这种情况下，需要确认已请求购买的项目，因为购买可能已成功完成。
IAP_ERROR_ITEM_GROUP_DOES_NOT_EXIST (-1007)	项目组 ID 不存在时出错。注意：可能错误的详细信息： `9201` :不存在已注册的项目信息。请在卖家门户中检查应用程序内购买激活和项目注册情况
IAP_ERROR_NETWORK_NOT_AVAILABLE (-1008)	网络不可用时出错。
IAP_ERROR_IOEXCEPTION_ERROR (-1009)	IOException
IAP_ERROR_SOCKET_TIMEOUT (-1010)	SocketTimeoutException
IAP_ERROR_CONNECT_TIMEOUT (-1011)	ConnectTimeoutException
IAP_ERROR_NOT_EXIST_LOCAL_PRICE (-1012)	此项目在该国家/地区中不可销售。注意：可能错误的详细信息： `9134` :本地价格不存在（不支持的 MCC）
IAP_ERROR_NOT_AVAILABLE_SHOP (-1013)	IAP 在该国家/地区中未提供服务。注意：可能错误的详细信息： `9259` :MCC 有效，但不支持 Galaxy Store
IAP_ERROR_INVALID_ACCESS_TOKEN (-1015)	Samsung 帐户的访问令牌无效。

Examples of error pop-up windows.

Note在错误代码中，初始斜杠之前显示的第一组数字应对应于如上响应代码的说明中的一个数字。例如，在第一个弹出窗口中，9224 显示在响应代码 IAP_ERROR_ALREADY_PURCHASED 的说明中。在第二个弹出窗口中，9014 显示在响应代码 IAP_ERROR_COMMON 的说明中。