en zh

Unreal 插件

Samsung IAP Unreal 插件附带了用于集成必需的所有内容。
此指南介绍了如何通过集成 Samsung IAP Unreal Engine 插件来使用 Samsung 应用程序内购买 (IAP) 功能。

开始使用

此部分介绍了如何通过集成 Samsung IAP Unreal Engine 插件来使用 Samsung 应用程序内购买 (IAP) 功能。

Samsung IAP Unreal 插件支持 Unreal Engine 4.18 或更高版本。

安装插件

复制并启用 Unreal Engine 插件。

如果 <unreal_project_directory>/Plugins 文件夹不存在，请创建该文件夹。

从存档中，将插件文件夹内容复制到 <unreal_project_directory>/Plugins。

在“编辑”->“插件”菜单中，启用 Samsung IAP 插件。

添加 Samsung IAP 依赖项

通过将 "SamsungIAP" 添加到 PublicDependencyModuleNames 部分中，以修改 <unreal_project_name>.Buld.cs 文件。

示例代码：

        PublicDependencyModuleNames.AddRange(new string[] {
            "Core", "CoreUObject", "Engine", "InputCore",
            "UMG", "Slate", "SlateCore",
            **"SamsungIAP"**
        });

集成 Samsung IAP 功能

此部分介绍了如何通过进行插件方法调用以支持应用程序内项目的提供和销售，从而将 Samsung IAP 功能集成到您的 Android 应用程序中的基础方面。

包括 IAP 标头文件

通过在您的工程的相关类中包括 IAP 标头文件 (IAP.h)，访问 Samsung IAP API。

示例代码：

#include "IAP.h"

设置 IAP 操作模式

使用 setOperationMode() 方法将 Samsung IAP 设置为下列三种操作模式之一：

SetOperationMode() 设置	说明
IAP_MODE_PRODUCTION	用于正常发布和 Beta 版发布的模式 所有请求都可以返回成功或失败的结果 注意：成功的购买请求和付款交易将导致对用户进行财务计费
IAP_MODE_TEST	用于应用程序开发和测试的模式 可以返回成功或失败的结果 已许可测试者的成功购买请求不会导致付款交易或财务计费 作为非许可测试者的用户的购买请求将导致显示错误消息 对于成功的请求，将返回成功的结果 对于失败的请求（例如，由于网络问题），将返回失败结果
IAP_MODE_TEST_FAILURE	用于应用程序开发和测试的模式 所有请求都将返回失败结果 购买请求不会导致付款交易或财务计费

应用程序开发和测试期间：

• 可以设置测试模式之一。
• 不得设置 IAP_MODE_PRODUCTION 模式。

对于 Beta 版发布：

• 必须设置 IAP_MODE_PRODUCTION 模式。
• 所有 Beta 版测试者可以免费下载付费 Beta 版应用程序。
• 未列入白名单的 Beta 版测试者购买应用程序内项目将会进行财务计费，这些测试者可以测试应用程序内购买功能。
• 列入白名单的 Beta 版测试者可以免费获得应用程序内项目，但他们无法测试购买功能。

对于验证测试和正常发布：

• 必须先设置 IAP_MODE_PRODUCTION 模式，然后才能提交应用程序及其应用程序内项目以供验证测试。

示例代码：

samsung::IAP::setOperationMode(IAP_MODE_TEST);

查询先前购买的项目

使用 getOwnedList() 方法可获取有关用户已购买的部分或所有项目的信息：

GetOwnedList() 设置	说明
PRODUCT_TYPE_ITEM	返回所有已购买的非消耗性项目和尚未消耗的消耗性项目
PRODUCT_TYPE_SUBSCRIPTION	返回具有有效订阅的所有已购买的订阅项目
PRODUCT_TYPE_ALL	返回所有已购买的非消耗性项目、尚未消耗的消耗性项目以及具有有效订阅的订阅项目

示例代码：

samsung::IAP::getOwnedList(PRODUCT_TYPE_ALL);

处理完成后，将触发 onGetOwnedProducts 回调，其中包含有关指定的已购买项目和 API 调用处理的信息。

查询提供的 Samsung IAP 项目

使用 getProductsDetails() 方法和以下参数设置可获取有关部分或所有已注册应用程序内项目（可供用户购买）的信息（包括本地化的说明、价格和货币符号）：

• 指定一个或多个唯一的应用程序内项目 ID 值（逗号分隔），以获取有关所指定项目的信息。
• 指定空字符串 ("") 以获取有关所有已注册项目的信息。

示例代码：

//Get information about three in-app items
samsung::IAP::getProductsDetails("com.mygame.product1, com.mygame.product2, com.mygame.product3");

//Get information about all in-app items
samsung::IAP::getProductsDetails("");

处理完成后，将触发 onGetProductsDetails 回调，其中包含有关指定的已注册项目和 API 调用处理的信息。

启动购买和付款交易

使用 startPayment() 方法可对指定的应用程序内项目启动购买和付款交易。

您可以自行指定直通参数，并在以后验证购买和付款交易时将其用于标识购买。您必须指定在交易成功时是否通过对话框通知用户。

示例代码：

//Start purchase and payment of an in-app item.
samsung::IAP::startPayment("com.mygame.product1", "pass_through_value", true);

处理完成后，将触发 onPayment 回调，
其中包含有关已购买的项目、交易和 API 调用处理的信息。

启用再次购买已购买的消耗性项目

使用 consumePurchasedItems() 方法和消耗性应用程序内项目的购买 ID，可以启用再次购买（无论用户是否实际使用了该项目）。

您的应用程序将在 onPayment 和 onGetOwnedList 回调中收到项目的购买 ID。示例代码：

//Consume Purchased Items
samsung::IAP::consumePurchasedItems(purchase_id);

处理完成后，将触发 onConsumePurchasedItems 回调，其中包含有关已消耗项目和 API 调用处理的信息。

侦听回调事件

实现 IAP 侦听器类以在所有 Samsung IAP 回调事件中接收信息。

侦听器声明示例代码：

class SamsungIAPListener : public samsung::IAPListener {
public:
    void onGetProducts(int result, const FString& msg, const std::vector<samsung::ProductVo>& data);
    void onGetOwnedProducts(int result, const FString& msg, const std::vector<samsung::OwnedProductVo>& data);
    void onPayment(int result, const FString& msg, const samsung::PurchaseVo& data);
    void onConsumePurchasedItems(int result, const FString& msg, const std::vector<samsung::ConsumeVo>& data);
};

侦听器实现示例代码：

using namespace std;
using namespace samsung;

void SamsungIAPListener::onGetProducts(int result, const FString& msg, const vector<ProductVo>& data) {
    
    for(auto& i : data) {
        print(FString::Printf(TEXT(" Name: %s"), *i.mItemName));
    }    
}

void SamsungIAPListener::onGetOwnedProducts(int result, const FString& msg, const vector<OwnedProductVo>& data) {
    
    for(auto& i : data) {
        print(FString::Printf(TEXT("Owned Item: %s"), *i.mItemName));
    }    
}

void SamsungIAPListener::onPayment(int result, const FString& msg, const PurchaseVo& data) {
    
    print(FString::Printf(TEXT("Item: %s"), *data.mItemName));    
}

void SamsungIAPListener::onConsumePurchasedItems(int result, const FString& msg, const vector<ConsumeVo>& data) {
    
    for(auto& i : data) {
        print(FString::Printf(TEXT("Owned Item: %s"), *i.mPurchaseId));
    }    
}