en zh

Unreal 插件

Samsung IAP Unreal Engine 插件附带了用于集成必需的所有内容。

将 Samsung IAP 集成到您的应用程序中

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

系统要求

要避免兼容性问题，插件需要以下 SDK：

• Epic Game launcher
• Android SDK
• Unreal Engine 4.18 或更高版本

安装 Samsung IAP 插件

1. 下载 Samsung IAP Unreal Engine 插件文件。

2. 如果 <unreal_project_directory> 目录下尚无 Plugins 文件夹，请创建该文件夹。

3. 将 SamsungIAP 文件夹及其中内容从 Samsung IAP Unreal 插件文件复制到上述Plugins文件夹。

4. 接下来打开编辑器，依次进入“编辑 → 插件”菜单，并启用 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_TEST);

获取用户拥有的项目

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

代码片段

samsung::IAP::getOwnedList("all");

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

侦听回调事件:

// 侦听器声明示例代码
void onGetOwnedProducts(int result, const FString& msg, const std::vector<samsung::OwnedProductVo>& data);

// 侦听器实现示例代码
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));
    }    
}

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

使用 getProductsDetails() 方法可获取有关部分或所有应用程序内项目（已在可供用户购买的应用程序中注册）的详细信息（例如项目 ID、价格和说明）：

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

代码片段

//获取有关三个应用程序内项目的信息 
samsung::IAP::getProductsDetails("com.mygame.product1, com.mygame.product2, com.mygame.product3");

//获取有关所有应用程序内项目的信息
samsung::IAP::getProductsDetails("");

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

侦听回调事件:

// 侦听器声明示例代码
void onGetProducts(int result, const FString& msg, const std::vector<samsung::ProductVo>& data);

// 侦听器实现示例代码
void SamsungIAPListener::onGetProducts(int result, const FString& msg, const vector<ProductVo>& data) {
    
    for(auto& i : data) {
        print(FString::Printf(TEXT(" Name: %s"), *i.mItemName));
    }    
}

购买应用程序内项目

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

您可以在调用 startPayment() 请求时选择性地指定混淆后的账号 ID 和配置文件 ID。这些混淆后的账号 ID 和配置文件 ID 会在响应中返回。Galaxy Store 使用此值来检测欺诈性支付行为。

samsung::IAP::startPayment("com.mygame.product1", "passThroughParam");

代码片段

samsung::IAP::startPayment("com.mygame.product1", "obfuscatedAccountId", "obfuscatedProfileId");

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

侦听回调事件:

// 侦听器声明示例代码
void onPayment(int result, const FString& msg, const samsung::PurchaseVo& data);

// 侦听器实现示例代码
void SamsungIAPListener::onPayment(int result, const FString& msg, const PurchaseVo& data) {
    
    print(FString::Printf(TEXT("Item: %s"), *data.mItemName));    
}

通知 Samsung IAP 购买交易已处理

消耗性项目

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

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

代码片段

samsung::IAP::consumePurchasedItems("purchase_id");

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

侦听回调事件:

// 侦听器声明示例代码
void onConsumePurchasedItems(int result, const FString& msg, const std::vector<samsung::ConsumeVo>& data);

// 侦听器实现示例代码
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));
    }    
}

非消耗性项目和订阅

使用 acknowledgePurchases() 方法可确认已经向用户授予一个或多个已购买的非消耗性项目或订阅的权利。

代码片段

samsung::IAP::acknowledgePurchases("purchase_id");

处理完成后，将触发 onAcknowledgePurchases 回调，该回调会返回非消耗型商品或订阅数据。

侦听回调事件:

// 侦听器声明示例代码
void onAcknowledgePurchases(int result, const FString& msg, const std::vector<samsung::AcknowledgeVo>& data);

// 侦听器实现示例代码
void SamsungIAPListener::onAcknowledgePurchases(int result, const FString& msg, const vector<AcknowledgeVo>& data) {
    
    for(auto& i : data) {
        print(FString::Printf(TEXT("Owned Item: %s"), *i.mPurchaseId));
    }    
}

获取订阅的优惠资格要求

使用 getPromotionEligibility() 方法可返回为客户提供的订阅项目定价选项，例如免费试用期和初始优惠价。

指定一个或多个唯一订阅ID值（逗号分隔）。

代码片段

//Get promotional offers of items and subscriptions
samsung::IAP::getPromotionEligibility("subItemId_1, subItemId_2");

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

侦听回调事件:

// 侦听器声明示例代码
void onGetPromotionEligibility(int result, const FString& msg, const std::vector<samsung::PromotionEligibilityVo>& data);

// 侦听器实现示例代码
void SamsungIAPListener::onGetPromotionEligibility(int result, const FString& msg, const vector<PromotionEligibilityVo>& data) {
    
    for(auto& i : data) {
        print(FString::Printf(TEXT("Owned Item: %s"), *i.itemID));
    }    
}

更改订阅计划

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

请参见按比例调整模式，详细了解四种模式。

代码片段

//Change from one subscription plan to another
samsung::IAP::changeSubscriptionPlan("oldItemId", "newItemId", PRORATION_MODE_INSTANT_PRORATED_DATE, "obfuscatedAccountId", "obfuscatedProfileId");

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

侦听回调事件:

// 侦听器声明示例代码
void onChangeSubscriptionPlan(int result, const FString& msg, const samsung::PurchaseVo& data);

// 侦听器实现示例代码
void SamsungIAPListener::onChangeSubscriptionPlan(int result, const FString& msg, const PurchaseVo& data) {
    
    print(FString::Printf(TEXT("Item: %s"), *data.mItemName));    
}