en ko zh

IAP SDK 编程

实例化 Samsung 应用程序内购买

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

请求

public static IapHelper getInstance( Context _context )

参数

返回值

IapHelper

代码片段

Java

private IapHelper iapHelper = IapHelper.getInstance(context);

Kotlin

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

设置 IAP 操作模式

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

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

请求

public void setOperationMode( OperationMode _mode )

参数

代码片段

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
)

参数

返回值

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

响应

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

参数

OwnedProductVo

SubscriptionPriceChangeVo

代码片段

Java

iapHelper.getOwnedList(HelperDefine.PRODUCT_TYPE_ALL, (errorVo, ownedList) -> {
    if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
        for (OwnedProductVo item : ownedList) {
            if (item.getIsConsumable()) {
                // For consumable item, consume the item not yet consumed
                iapHelper.consumePurchasedItems(item.getPurchaseId(), (errorVo, consumeList) -> {
                    // TODO: Handle the result
                });
            } else {
                // For non-consumable item and subscription, acknowledge the purchase not yet acknowledged
                if (item.getAcknowledgedStatus() == HelperDefine.AcknowledgedStatus.NOT_ACKNOWLEDGED) {
                    iapHelper.acknowledgePurchases(item.getPurchaseId(), (errorVo, acknowledgedList) -> {
                        // TODO: Handle the result
                    });
                }
            }
                
            // Check if the subscription price has changed and user consent is required
            SubscriptionPriceChangeVo subscriptionPriceChangeVo = item.getSubscriptionPriceChange();
            if (subscriptionPriceChangeVo != null &&
                subscriptionPriceChangeVo.getPriceChangeMode() == HelperDefine.PriceChangeMode.PRICE_INCREASE_USER_AGREEMENT_REQUIRED &&
                !subscriptionPriceChangeVo.isConsented()) {
                // TODO: Induce user consent
            }
        }
    } 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) {
                // For consumable item, consume the item not yet consumed
                iapHelper.consumePurchasedItems(item.purchaseId) { errorVo: ErrorVo, consumeList: ArrayList<ConsumeVo> ->
                    // TODO: Handle the result
                }
            } else {
                // For non-consumable item and subscription, acknowledge the purchase not yet acknowledged
                if (item.acknowledgedStatus == HelperDefine.AcknowledgedStatus.NOT_ACKNOWLEDGED) {
                    iapHelper.acknowledgePurchases(item.purchaseId) { errorVo: ErrorVo, acknowledgedList: ArrayList<AcknowledgeVo> ->
                        // TODO: Handle the result
                    }
                }
            }
                
            // Check if the subscription price has changed and user consent is required
            val subscriptionPriceChangeVo = item.subscriptionPriceChange
            if (subscriptionPriceChangeVo != null &&
                subscriptionPriceChangeVo.priceChangeMode == HelperDefine.PriceChangeMode.PRICE_INCREASE_USER_AGREEMENT_REQUIRED &&
                !subscriptionPriceChangeVo.isConsented {
                // TODO: Induce user consent
            }
        }
    } else {
        // TODO: Handle the error
    }
}

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

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

请求

public void getProductsDetails
(   
    String                           _productIds,
    OnGetProductsDetailsListener     _onGetProductsDetailsListener
)  

参数

响应

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

参数

ProductVo

代码片段

Java

iapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp", (errorVo, 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 接口中指定的项目数据、交易结果和数据。

请求

public boolean startPayment
(
    String                  _itemId,
    OnPaymentListener       _onPaymentListener
)

参数

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

返回值

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

响应

void onPayment(ErrorVo errorVo, PurchaseVo purchaseVo)

参数

PurchaseVo

代码片段

Java

iapHelper.startPayment("Nuclear", (errorVo, purchaseVo) -> {
    if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
        if (purchaseVo != null) {
            if (purchaseVo.getIsConsumable()) {  
                // Consume the consumable item
                iapHelper.consumePurchasedItems(purchaseVo.getPurchaseId(), (errorVo, arrayList) -> {
                    // TODO: Handle the result
                });
            } else {
                // Acknowledge the non-consumable item or subscription
                iapHelper.acknowledgePurchases(purchaseVo.getPurchaseId(), (errorVo, arrayList) -> {
                    // TODO: Handle the result
                });
            }
        }
    } else {
        // TODO: Handle the error
    }
});

Kotlin

iapHelper.startPayment("Nuclear") { errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        if (purchaseVo != null) {
            if (purchaseVo.isConsumable) {          
                // Consume the consumable item
                iapHelper.consumePurchasedItems(purchaseVo.purchaseId) { errorVo: ErrorVo, arrayList: ArrayList<ConsumeVo> ->
                    // TODO: Handle the result
                }
            } else {   
                // Acknowledge the non-consumable item or subscription
                iapHelper.acknowledgePurchases(purchaseVo.purchaseId) { errorVo: ErrorVo, arrayList: ArrayList<AcknowledgeVo> ->
                    // TODO: Handle the result
                }
            }
        }
    } else {
        // TODO: Handle the error
    }
}

通知 Samsung IAP 购买交易已处理

应用程序向成功完成交易的用户授予权利后，应用程序需通知 Samsung IAP 购买交易已成功处理。

以下几节描述不同类型购买交易的确认流程。

消耗性项目

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

请求

public boolean consumePurchasedItems
(
  String                             _purchaseIds,
  OnConsumePurchasedItemsListener    _onConsumePurchasedItemsListener
)

参数

返回值

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

• false:请求未发送到服务器并且未处理。

响应

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

参数

非消耗性项目和订阅

acknowledgePurchases() 确认已经向用户授予一个或多个已购买的非消耗性项目或订阅的权利。返回 OnAcknowledgePurchasesListener 接口指定的项目数据和处理结果。

Request

public boolean acknowledgePurchases
(
  String                             _purchaseIds,
  OnAcknowledgePurchasesListener     _onAcknowledgePurchasesListener
)

Parameters

Return value

• true: 请求已成功发送到服务器，并且结果将发送到 OnAcknowledgePurchasesListener 接口侦听器。

• false: 请求未发送到服务器并且未处理。

Response

void onAcknowledgePurchases(ErrorVo errorVo, ArrayList<AcknowledgeVo> acknowledgedList)

Parameters

ConsumeVo/AcknowledgeVo

代码片段

Java (ConsumeVo)

final String PURCHASEID = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590";

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

Kotlin (AcknowledgeVo)

val PURCHASEID: String = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590"

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

获取订阅的优惠资格要求

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

请求

public void getPromotionEligibility
(
  String _itemIds,
  OnGetPromotionEligibilityListener onGetPromotionEligibilityListener
)

参数

返回值

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

参数

PromotionEligibilityVo

代码片段

Java

iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp", (errorVo, 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,
  OnChangeSubscriptionPlanListener _onChangeSubscriptionPlanListener
)

参数

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

返回值

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

响应

void onChangeSubscriptionPlan(ErrorVo errorVo, PurchaseVo purchaseVo)

参数

代码片段

Java

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE,
    (errorVo, purchaseVo) -> {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
             	// TODO: Check details about your newly purchased subscription
            }
        } else {
       	   // TODO: Handle the error
        }
});

Kotlin

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE)
	{ errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
        if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
                // TODO: Check details about your newly purchased subscription
            }
        } else {
            // TODO: Handle the error
    	}
	}

ErrorVo 和响应代码

ErrorVo

响应代码