IAP 帮助程序编程
实例化 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 版发布和正常发布)。
OPERATION_MODE_PRODUCTION
。换言之,仅当卖家门户中的应用程序状态为正在注册或正在更新时,才必须设置 OPERATION_MODE_TEST
或 OPERATION_MODE_TEST_FAILURE
。模式 | 说明 |
---|---|
OPERATION_MODE_
|
startPayment() 请求将按指定的方式处理,执行财务交易以使请求成功,并返回实际结果(成功或失败)。 注意:所有其他 IAP 帮助程序请求将按如下方式工作:
|
OPERATION_MODE_
|
startPayment() 请求将按指定的方式处理,未发生财务交易除外(将不会针对项目购买向已许可的测试者计费),并且始终返回成功的结果。 有关 OPERATION_MODE_TEST 模式下显示的付款窗口的详细信息,请参见下面所示。注意:所有其他 IAP 帮助程序请求将按如下方式工作:
|
OPERATION_MODE_TEST_
|
所有 IAP 帮助程序请求将失败。 这旨在用作负面测试,以确保您的应用程序可以处理诸如输入和用户操作不正确这样的错误。 |
OPERATION_MODE_TEST
,则会显示下面的弹出窗口,并且付款窗口的右上角将显示 Sandbox
,指示将不会针对项目购买向应用程序用户计费。
请求
public void setOperationMode( OperationMode _mode )
参数
参数 | 类型 | 说明 |
---|---|---|
_mode | OperationMode | (必需)IAP 操作模式,用于控制对 IAP 帮助程序 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)
获取用户拥有的项目
getOwnedList()
返回应用程序用户通过先前的购买当前获得的应用程序内项目列表。
- 尚未使用且尚未报告为已消耗的消耗性项目
- 非消耗性项目
- 当前处于免费试用期或有效的订阅期限内的订阅项目(包括有效的订阅期限结束前已取消的订阅项目)
getOwnedList()
还返回 OnGetOwnedListListener
接口指定的项目数据和处理结果。
请求
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 |
包含应用程序用户拥有的应用程序内项目的对象 |
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 | 本地货币符号和价格(本地货币格式):
|
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) |
getSubscription |
String | 仅适用于订阅应用程序内项目,项目的当前订阅期限将过期的日期和时间 (YYYY-MM-DD HH:mm:ss) |
getPassThrough |
String | 您的应用程序为项目购买和付款交易分配的唯一标识符 如果未分配直通参数,将返回空字符串 ("")。 |
getJsonString() | String | 完全 JSON 有效负载 |
代码片段
Java
public class OwnedList implements OnGetOwnedListListener {
IapHelper.getOwnedList(IapHelper.PRODUCT_TYPE_ALL, this);
@Override
public void onGetOwnedProducts(ErrorVo _errorVo, ArrayList<OwnedProductVo> _ownedList) {
if (_errorVo != null) {
if (_errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
if (_ownedList != null) {
for (OwnedProductVo item : _ownedList) {
if (item.getIsConsumable()) {
// TODO: Consume the consumable item not yet consumed
}
}
}
} else {
// TODO: Handle the error
}
}
}
}
Kotlin
iapHelper.getOwnedList(IapHelper.PRODUCT_TYPE_ALL)
{ _errorVo: ErrorVo?, _ownedList: ArrayList<OwnedProductVo>? ->
if (_errorVo != null) {
if (_errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
if (_ownedList != null) {
for (item in _ownedList) {
if (item.isConsumable) {
// TODO: Consume the consumable item not yet consumed
}
}
}
} else {
// TODO: Handle the error
}
}
}
获取应用程序内项目详细信息
getProductsDetails()
返回应用程序中注册的一个、多个或所有应用程序内项目的信息。
返回 OnGetProductsDetailsListener
接口指定的项目数据和处理结果。
请求
public void getProductsDetails
(
String _productIds,
OnGetProductsDetailsListener _onGetProductsDetailsListener
)
参数
参数 | 类型 | 说明 |
---|---|---|
_productIds | String | (必需)由下面两项内容之一指定的一个或多个应用程序内项目 ID:
您可以从卖家门户中获取这些 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) |
getItemPriceString() | String | 本地货币符号和价格(本地货币格式):
|
getCurrencyUnit() | String | 本地货币的符号(例如 €、£ 或 $) |
getCurrencyCode() | String | 本地货币的货币代码(3 个字符)(例如 EUR、GBP、USD) |
getItemDesc() | String | 应用程序内项目的说明 |
getType() | String | 应用程序内项目的类型:"item" :消耗性项目或非消耗性项目"subscription" :自动定期订阅
|
getIsConsumable() | boolean | 应用程序内项目是否为消耗性项目true :消耗性应用程序内项目false :非消耗性应用程序内项目(非消耗性项目或自动定期订阅)
|
getSubscription |
String | 仅适用于订阅应用程序内项目,每个订阅期限的时间基本单位("YEAR" 、"MONTH" 、"WEEK" )。注意:单位必须为大写。 |
getSubscription |
String | 仅适用于订阅项目,时间基本单位的数值倍数(例如 1YEAR、2MONTH、4WEEK),用于确定项目的订阅期限 倍数与 getSubscriptionDurationUnit() 返回的值结合使用。
|
getTiered |
String | 仅适用于订阅项目,无论项目是否具有两层定价"Y" :项目具有一个或多个低层价格订阅期限,到期后采用常规价格期限"N" :项目仅具有常规价格订阅期限
|
getTieredPrice() | String | 仅适用于两层订阅项目,以本地货币表示的低层价格(例如 7.99) |
getTieredPriceString() | String | 仅适用于两层订阅项目,本地货币符号和价格(本地货币格式):
|
getTiered |
String | 仅适用于两层订阅项目,每个订阅期限的时间基本单位("YEAR" 、"MONTH" 、"WEEK" )。注意:单位必须为大写。 |
getTiered |
String | 仅适用于两层订阅项目,时间基本单位的数值倍数(例如 1YEAR、2MONTH、4WEEK),用于确定项目的订阅期限 倍数与 getTieredSubscriptionDurationUnit() 返回的值结合使用。
|
getTiered |
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
public class ProductsDetails implements OnGetProductsDetailsListener {
IapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp", this);
@Override
public void onGetProducts(ErrorVo _errorVo, ArrayList<ProductVo> _productList) {
if (_errorVo != null) {
if (_errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
if (_productList != null) {
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 != null) {
if (_errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
if (_productList != null) {
for (item in _productList) {
// TODO: Get details of the item
}
}
} else {
// TODO: Handle the error
}
}
}
购买应用程序内项目
startPayment()
启动对所指定应用程序内项目的购买和付款交易,并可通知最终用户该购买已成功还是失败。返回 OnPaymentListener
接口中指定的项目数据、交易结果和数据。
您可以指定 passThroughParam
参数值以增强购买安全性。使用由集成了 IAP 的应用程序创建和传递的 passThroughParam 值进行购买时,将在响应中返回值。
请求
public boolean startPayment
(
String _itemId,
String _passThroughParam,
OnPaymentListener _onPaymentListener
)
参数
参数 | 类型 | 说明 |
---|---|---|
_itemId | String | (必需)要购买的应用程序内项目的唯一标识符值。 |
_passThrough |
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) |
getItemPriceString() | String | 本地货币符号和价格(本地货币格式):
|
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 进行的购买。
|
getPassThrough |
String | 您的应用程序为项目购买和付款交易分配的唯一标识符 如果未分配直通参数,将返回空字符串 ("")。 |
getItem |
String | 项目的图像和缩略图的 URL |
getItem |
String | 用于下载项目的 URL |
getOrderId() | String | 订单的唯一标识符 |
getJsonString() | String | 完全 JSON 有效负载 |
代码片段
Java
public class PurchaseItem implements OnPaymentListener {
IapHelper.startPayment("Nuclear", "pLKjLKjLJL87=76df56rf+4f5", this);
@Override
public void onPayment(ErrorVo _errorVo, PurchaseVo _purchaseVO) {
if (_errorVo != null) {
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 != null) {
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
}
}
}

确认已购买的消耗性项目
consumePurchasedItems()
将一个或多个已购买的消耗性项目报告为已消耗,这样可以再次购买这些项目。应用程序用户可以使用这些项目,也可以不使用。返回 OnConsumePurchasedItemsListener
接口指定的项目数据和处理结果。
consumePurchasedItems()
方法调用中验证项目的购买并报告所有未报告的项目之后,我们建议立即报告已购买的消耗性项目,以避免发生系统过载或故障。请求
public boolean consumePurchasedItems
(
String _purchaseIds,
OnConsumePurchasedItemsListener _onConsumePurchasedItemsListener
)
参数
参数 | 类型 | 说明 |
---|---|---|
_purchaseIds | String | (必需)消耗性应用程序内项目(要报告为已消耗)的购买和付款交易的一个或多个唯一标识符值(逗号分隔) |
_onConsumePurchasedItems |
(必需)指定要返回的项目数据和处理结果的 OnConsumePurchasedItemsListener 接口的名称
|
返回值
-
true
:请求已成功发送到服务器,并且结果将发送到OnConsumePurchasedItemsListener
接口侦听器。 -
false
:请求未发送到服务器并且未处理。
响应
void onConsumePurchasedItems ( ErrorVo _errorVo, ArrayList<ConsumeVo> _consumeList );
参数
参数 | 类型 | 说明 |
---|---|---|
_errorVO | ErrorVo | 已处理的请求结果 |
_consumeList | ArrayList |
已消耗项目的列表 注意:即使由于意外错误而无法消耗某些项目,这些项目仍将包括在 _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 :无效的购买 ID2 :订单失败3 :非消耗性项目4 :已消耗5 :未授权的用户9 :意外的服务错误
|
getStatusString() | String | 状态消息0 :“成功”1 :“找不到具有此购买 ID 的订单。”2 :“无法消耗此购买,因为它不是成功的订单。”3 :“此类型的项目不是消耗性项目。”4 :“已消耗此购买。”5 :“无法消耗此购买,因为用户无权消耗此订单。”9 :“服务错误”
|
getJsonString() | String | 完全 JSON 有效负载 |
代码片段
Java
public class ConsumeItems implements OnConsumePurchasedItemsListener {
final String PURCHASEID = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590";
IapHelper.consumePurchasedItems(PURCHASEID, this);
@Override
public void onConsumePurchasedItems(ErrorVo _errorVo, ArrayList<ConsumeVo> _consumeList) {
if (_errorVo != null) {
if (_errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
if (_consumeList != null) {
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 != null) {
if (_errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
if (_consumeList != null) {
for (item in _consumeList) {
// TODO: Get details of the consumption
}
}
} else {
// TODO: Handle the error
}
}
}
响应代码
响应代码 (值) |
说明 |
---|---|
IAP_ERROR_NONE (0) |
成功 |
IAP_PAYMENT_IS_CANCELED (1) |
付款已取消 |
IAP_ERROR_INITIALIZATION (-1000) |
初始化 IAP 失败 注意:可能错误的详细信息:
|
IAP_ERROR_ (-1001) |
需要升级 IAP |
IAP_ERROR_COMMON (-1002) |
运行 IAP 时出错 注意:可能错误的详细信息:
|
IAP_ERROR_ (-1003) |
再次购买非消耗性项目或者在订阅过期前再次购买订阅时出错。 注意:可能错误的详细信息:
|
IAP_ERROR_WHILE_RUNNING (-1004) |
发出不包含任何信息的付款请求时出错。 |
IAP_ERROR_ (-1005) |
请求的项目不可用时出错 注意:可能错误的详细信息:
|
IAP_ERROR_CONFIRM_INBOX (-1006) |
向服务器发出购买请求之后,应用程序未收到购买结果时出错。 在这种情况下,需要确认已请求购买的项目,因为购买可能已成功完成。 |
IAP_ERROR_ (-1007) |
项目组 ID 不存在时出错。 注意:可能错误的详细信息:
|
IAP_ERROR_ (-1008) |
网络不可用时出错。 |
IAP_ERROR_ (-1009) |
IOException |
IAP_ERROR_SOCKET_TIMEOUT (-1010) |
SocketTimeoutException |
IAP_ERROR_CONNECT_TIMEOUT (-1011) |
ConnectTimeoutException |
IAP_ERROR_ (-1012) |
此项目在该国家/地区中不可销售。 注意:可能错误的详细信息:
|
IAP_ERROR_ (-1013) |
IAP 在该国家/地区中未提供服务。 注意:可能错误的详细信息:
|
IAP_ERROR_INVALID_ACCESS_TOKEN (-1015) |
Samsung 帐户的访问令牌无效。 |