EN

# 五、平台接口

对于上线至奇遇商店的应用,必须勾选启用奇遇平台插件Online Subsystem QIYU,否则在上传应用提交审核时,无法通过平台检测。

# 5.1 初始化

如果您需要使用奇遇平台功能,必须先按照以下内容初始化奇遇SDK:

Plugins-Online Subsystem QIYU-Platform栏填入初始化参数:

图5.1 Platform初始化参数界面

参数说明

  • App ID, App Secret:请您在登录奇遇开发者网站后,点击“管理 - 我的应用 - 新增”创建您的应用,系统将会给每个应用生成唯一App ID和App Secret。

    创建应用后,点击 “API” 查看App ID,App Secret信息

  • 配置文件

要使用Online Subsystem QIYU插件,需要在项目目录下的Config文件夹内找到Android文件夹(没有则创建),在Android文件夹中找到一个名为AndroidEngine.ini(没有则创建)的文件,然后添加或者修改相关条目信息:

[OnlineSubsystem]
DefaultPlatformService=QIYU

[OnlineSubsystemQIYU]
bEnabled=true

路径示例:YourProjectDir/Config/Android/AndroidEngine.ini

  • Blueprint
函数名称 蓝图 功能 原接口(已弃用)
Init QIYUSDK 初始化SDK
output:
Code:返回码
Was Successful:是否成功
RequesSDKInit()
  • C++

    接口为异步接口,下面是提供的的示例代码:

static void InitQIYUSDK(FQIYUInitQiyuSDKCompleteResult&& OnSuccess, FQIYUInitQiyuSDKCompleteResult&& OnFailure);

MyActor.h

class AMyActor
{
...
UFUNCTION()
		void OnSuccessResults(const FString& Code, bool bWasSuccessful);
	UFUNCTION()
		void OnFailureResults(const FString& Code, bool bWasSuccessful);
	UPROPERTY(BlueprintAssignable)
		FQIYUInitQiyuSDKCompleteResult OnSuccess;
	UPROPERTY(BlueprintAssignable)
		FQIYUInitQiyuSDKCompleteResult OnFailure;...

};
----

MyActor.cpp

void AMyActor::Test()
{
OnSuccess.AddDynamic(this,&AMyActor::OnSuccessResults);
OnFailure.AddDynamic(this,&AMyActor::OnFailureResults);
UOnlineSubsystemQIYUUtils::InitQIYUSDK(MoveTemp(OnSuccess), MoveTemp(OnFailure));
}

void AMyActor::OnSuccessResults(const FString& Code, bool bWasSuccessful)
{
// todo
}

void AMyActor::OnFailureResults(const FString& Code, bool bWasSuccessful)
{
// todo
}
返回码 原因
S0000 成功
S9000 系统异常
S9001 应用ID或秘钥为空
B1009 获取Token失败
B3021 应用ID或秘钥错误

# 5.2 奇遇账户

在应用程序中获取奇遇用户的帐户状态和信息。

  • Blueprint
函数名称 蓝图 功能 原接口(已弃用)
Is Logged In 获取设备账号登录状态
Input:
In Player Controller :用户控制器
Output:
True:账号已登录
False:账号未登录
RequestisAccountLogin
GetQIYUIdentity 获取账号信息:
Input:
In Player Controller :用户控制器
Output:
Results:返回用户信息
Error:调用失败时的错误代码
Was Successful:是否成功
RequestAccountInfo
  • C++
  1. 请求获取账号是否登录
static bool UKismetSystemLibrary::IsLoggedIn(const APlayerController * SpecificPlayer);
  1. 请求获取账号信息

​ 接口为异步接口,下面提供代码参考:

static void UOnlineSubsystemQIYUUtils::GetQIYUIdentity(APlayerController* InPlayerController, FQIYUIdentityCompleteResult&& OnSuccess, FQIYUIdentityCompleteResult&& OnFailure);
错误码 原因
S0000 调用成功
S9000 系统异常

奇遇后台提供了校验用户账户有效性的服务端接口,参见 4. 3 奇遇用户认证API (opens new window)

# 5.3 深度链接

当您有两个独立的应用程序时:例如一个单人游戏和一个多人游戏。如果你想要在两个应用程序中实现应用程序深度链接,用户可以从单人应用程序加入多人游戏应用。 深度链接需要在发出请求的应用程序和目标应用程序中进行集成。接下来的部分将描述这两个应用程序所需的实现。

  • Blueprint
函数名称 蓝图 功能 原接口(已弃用)
Deeplink 获得深度链接信息:
Output:
Result:返回DeepLink信息
Code:成功码S0000
Was Successful:调用是否成功
Result节点:
RequestDeepLinkParam
LaunchOtherApp 请求切换到其他应用:
Input:
Appid :深度链接APPID
Key :深度链接Key(注:Key参数为小写字母)
Value :深度链接值
RequestLaunchOtherApp
LaunchHome 返回Home:
Input:
Key :跳转应用的Key(当key的值为login 时,会跳转到登录界面)
Value :传入home的值
RequestLauchHome
  • C++
  1. 请求获取Deeplink信息

​ 接口为异步接口,下面提供代码参考:

static void UOnlineSubsystemQIYUUtils::GetDeepLink(FQIYUDeeplinkCompleteResult&& OnSuccess,FQIYUDeeplinkCompleteResult&& OnFailure)
  1. 跳转到其他app
static void UOnlineSubsystemQIYUUtils::LaunchOtherApp(const FString& AppId, const FString& Key,const FString& Value)
  1. 返回大厅
static void UOnlineSubsystemQIYUUtils::LaunchHome(const FString& Key,const FString& Value)

Launch Home 参数示例:

Key Value 备注
"store" "123456" 跳转到 APPID 为123456的游戏的商品详情页
"login" "" 跳转到登录界面
"dlc" "123456" 跳转到 SKU 为123456的DLC的商品详情页

Deeplink返回码

返回码 原因
S0000 调用成功
S9000 系统异常

# 5.4 数据存档

在奇遇商店上线的内容,需要存档用户数据,防止用户在版本升级、卸载重装后丢失已有数据和档案。如果您的应用需要存档用户数据,请使用奇遇SDK提供的Prefs应用数据持久化功能,退出游戏前记得调用Save保存。

函数名称 蓝图 功能
Prefs_GetFloat(FString Key,float DefaultValue) 返回存档文件中的key对应的float值,不存在返回defValue
Prefs_GetInt(FString Key,int32 DefaultValue) 返回存档文件中的key对应的int值,不存在返回defValue
Prefs_GetString(FString Key,FString DefaultValue) 返回存档文件中的key对应的string值,不存在返回defValue
Prefs_SetFloat(FString Key,float Value) 设置给定key的float值
Prefs_SetInt(FString Key,int32 Value) 设置给定key的int值
Prefs_SetString(FString Key,FString Value) 设置给定key的string值
Prefs_HasKey(FString Key) 存档文件中的key存在返回true,否则返回false
Prefs_Save() 所有修改后,需要调用Save
Prefs_DeleteAll() 清空存档文件
Prefs_DeleteKey(FString Key) 删除存档文件中的key

注:

  • 奇遇设备支持多账号登陆和退登,所以在使用Prefs提供的方法时,需将奇遇账号信息连同需要存储的数据关联,以实现针对每个用户正确的档案数据。

  • QiyuPrefs为本地存档方案,支持应用升级、卸载重装后保留用户数据,并非“云存档”。

# 5.5 应用内支付

应用内支付支持用户在应用里购买虚拟商品、代币等内容。开发者可在奇遇开发者平台创建、配置、编辑商品信息,再通过SDK提供的接口集成进应用中。应用内支付仅支持“应用”使用,不支持“游戏”使用。

奇遇商品支付通过"手机短信-链接跳转到微信/支付宝"完成,主要流程如下图所示,您可根据流程和SDK Demo完成内支付功能的接入和开发。

图3.5 奇遇商品支付流程

# 5.5.1 开发者平台配置

参见3.5.1 开发者平台配置 (opens new window)

# 5.5.2 SDK 接口

注:应用内支付需要用户先进行初始化操作。

# 初始化QiyuPay

函数名 蓝图 功能
Init QIYUPay img 初始化Pay
Output:
Code:返回码
Was Successful:是否成功
  • C++
static void InitQIYUPay(FQIYUInitQiyuPayCompleteResult&&OnSuccess,FQIYUInitQiyuPayCompleteResult&& OnFailure);
返回码 原因
S0000 初始化成功
S1000 SDK尚未初始化
S9000 系统异常
S9001 参数错误

# 获取商品列表

函数名 蓝图 功能
Read In App Purchase Information2 img 获取商品列表:
Input:
Product Identifiers:商品sku数组,当数组为空时获取全部商品。
Output:
In App Offer Information:返回的商品数组,包含商品的各种信息。
img 商品详情:
offer id:商品SKU
Title:商品名称
Regular Price:商品折扣价(单位为最小价格单位(分) )
Numeric Price:商品原价(单位为最小价格单位(分) )
Dynamic Dields:商品额外属性,是一个映射类型,其中的键ItemType的值为商品类型,例如
img
  • C++
void FTestStoreInterface::Test(UWorld* InWorld, const TArray<FString>& InOffersIds)
{
	auto OnlineSub = Online::GetSubsystem(InWorld, TEXT("QIYU"));
	if (OnlineSub != nullptr)
	{
		if (OnlineSub->GetIdentityInterface().IsValid())
		{
			LocalUserId = OnlineSub->GetIdentityInterface()->GetUniquePlayerId(0);
		}
		if (LocalUserId.IsValid())
		{
			if (OnlineSub->GetStoreV2Interface().IsValid())
			{
				for (const FString& OfferId : InOffersIds)
				{
					RequestOfferIds.Add(FUniqueOfferId(OfferId));
				}				
				OnlineSub->GetStoreV2Interface()->QueryOffersById(*LocalUserId, RequestOfferIds,
			FOnQueryOnlineStoreOffersComplete::CreateRaw(this, &FTestStoreInterface::OnQueryOnlineStoreOffersComplete));
			}
		}
	}
}

回调函数:

void FTestStoreInterface::OnQueryOnlineStoreOffersComplete(bool bWasSuccessful, const TArray<FUniqueOfferId>& OfferIds, const FString& ErrorString)
返回码 原因
S0000 查询成功
S1001 支付接口未初始化
B1001 查询结果为空
S9000 系统异常
S9001 参数错误

注:物品的价格单位为最小的价格单位(例如人民币的分),开发者使用时可以按自身的需求自行转换。

# 商品下单购买

函数名 蓝图 功能
Place Order img 下单购买物品:
Input:
In Product Identifier :商品的sku
Output:
Results:返回一个订单号
Code:调用失败时的错误代码
Was Successful:是否成功
  • C++
static void UOnlineSubsystemQIYUUtils::PlaceOrder(const FString& Sku, FQIYUPlaceOrderCompleteResult&& OnSuccess, FQIYUPlaceOrderCompleteResult&& OnFailure)
返回码 原因
S0000 成功下单
S1001 支付接口未初始化
B3007 设备识别码无效
B4010 您已购买过该SKU
B4009 您有一笔待支付订单
B1003 authCookie失效
B3019 商品不存在
S9000 系统异常
S9001 参数错误

# 查询订单结果

函数名 蓝图 功能
Query Order Result img 查询订单结果:
Input:
In Order Id:当成功下单时返回的订单号
output:
Results:返回一个订单详情
Code:调用失败时的错误代码
Was Successful:调用是否成功
img 订单详情:
Output:
Order Id:订单ID
Pay Date:支付时间
Sku:购买的商品sku
Order Status:订单状态
Paid Amount:支付金额(单位为最小价格单位(分))

C++

static void UOnlineSubsystemQIYUUtils::QueryOrderResult(const FString& OrderID, FQIYUQueryOrderResultCompleteResult&& OnSuccess, FQIYUQueryOrderResultCompleteResult&& OnFailure)
返回码 原因
S0000 查询成功
S1001 支付接口未初始化
B1003 authCookie失效
B3019 商品不存在
B1001 查询结果为空
S9000 系统异常
S9001 参数错误

:物品的价格单位为最小的价格单位(例如人民币的分),开发者使用时可以按自身的需求自行转换。

# 查询单个商品的历史订单

函数名 蓝图 功能
Query History Orders img 查询某个商品的历史订单:
input:
In Sku Id:要查询的商品的Sku
In Page:要查询的页数
In Page Size:每页的订单数量
output:
Results:返回一个订单详情数组
Was Successful:是否成功
Code:调用失败时的错误代码
img 订单详情:
Order Id:订单ID
Pay Date:支付时间
Sku:购买的商品sku
Order Status:订单状态
Paid Amount:支付金额(单位为最小价格单位(分))

C++

static void UOnlineSubsystemQIYUUtils::QueryHistoryOrders(const FString& Sku, int32 CurrentPage, int32 PageSize, FQIYQueryHistoryOrdersCompleteResult&& OnSuccess, FQIYQueryHistoryOrdersCompleteResult&& OnFailure)
返回码 原因
S0000 查询成功
S1001 支付接口未初始化
B1003 authCookie失效
B3019 商品不存在
B1001 查询结果为空
S9000 系统异常
S9001 参数错误

:物品的价格单位为最小的价格单位(例如人民币的分),开发者使用时可以按自身的需求自行转换。

# 5.5.3 服务端支付结果通知

参见 4.2 服务端支付结果通知 (opens new window)

# 5.5.4 开发者自测

参见3.5.4 开发者测试账号 (opens new window)

# 5.6 DLC

奇遇平台提供应用可下载附加内容(Downloadable Add-on Content)的售卖。

开发者可在奇遇开发者平台创建、配置、编辑DLC信息,再通过SDK提供的接口集成进游戏中。DLC内容通过平台审核后,可在奇遇商店上架进行销售。用户在商店里购买游戏币、新的关卡、地图、媒体库等内容。进入游戏后,解锁新关卡,下载新资源。您可根据流程和SDK Demo完成DLC功能的接入和开发。

图5.6.1 DLC 权益下发流程

# 5.6.1 开发者平台配置

参见Platform SDK 3.6.1 (opens new window)

# 5.6.2 SDK接口

SDK提供以下客户端接口,支持应用完成DLC权益查验、文件下载功能:

  • 初始化
函数名 蓝图 功能
Init QIYUDLC img 初始化DLC
out:
Code:调用接口时的响应代码
返回码 原因
S0000 查询成功
S1000 SDK尚未初始化
S9000 系统异常
S9001 参数错误
  • 获取DLC列表
函数名 蓝图 功能
Get Assets List img 分页获取DLC列表
in:
In Cur Page: 要获取的当前页数
(参数值必须大于0,默认值为1)
In Page Size: 每页大小
(参数值必须大于0,默认值为10)
out:
Results: 返回的DLC数组
Code:调用接口时的响应代码
img Sku: SKU码
Name: DLC的名称
Type:DLC类型:1:持久型;2:消耗型
ChargeType: 付费类型:0,免费;1:付费
IconUrl: DLC 图标网络地址
OriginalPrice: 原价(价格单位为 人民币的分)
SalePrice: 售卖价(价格单位为 人民币的分)
ShortDescription: DLC简介
返回码 原因
S0000 查询成功
S1001 未初始化
B1001 查询结果为空
S9000 系统异常
S9001 参数错误
  • 获取当前用户指定DLC状态(适用于持久型DLC)
函数名 蓝图 功能
Get Assets Status img 获取指定DLC状态(含鉴权)
in:
In Sku: 要获取的DLC的SKU
out:
Result: 返回的DLC详情
Code:调用接口时的响应代码
img Sku: SKU码
Type:DLC类型:1:持久型;2:消耗型 //当前DLC的下载状态
DownloadStatus:
Available:可获得
InProgress:下载中 Downloaded:已下载
Pause:暂停中
Purchased: 是否已经支付
FilePath: 已经下载过DLC的地址
返回码 原因
S0000 查询成功
S1001 未初始化
B1001 查询结果为空
S9000 系统异常
B4015 不支持非持久化DLC鉴权
B1003 用户账户已过期
B4000 APP鉴权失败
B4013 DLC鉴权失败
  • 下载DLC文件
函数名 蓝图 功能
Download Asset img 请求下载指定DLC(含鉴权)
in:
In Sku: 要下载的DLC的SKU
out:
Code:调用接口时的响应代码
返回码 原因
S0000 查询成功
S1001 未初始化
C1002 储存空间不足
C1005 资源不存在
B4015 不支持非持久化DLC鉴权
B1003 用户账户已过期
B4000 APP鉴权失败
B4013 DLC鉴权失败
B3033 DLC版本错误

注意事项:

  1. 调用下载接口前,须先调用Get Assets Status查询资源的状态;当已购买未下载 或 有文件更新时,通过Get Assets Status接口查询DLC的状态,downloadStatus为Available,游戏需提示用户下载资源或升级。

  2. 支持后台下载,即设备息屏、回到Home(未退出)资源会继续下载。应用完全退出时下载会中断,重新启动应用后,开发者需要检查下载状态,决定是否需要继续下载,如下载没有完成需要再次调用Download Asset进行断点续下。

  • 获取下载进度
函数名 蓝图 功能
Set Download Update Notification img 设置下载通知事件
in:
Notifications: 被绑定的事件函数
img 下载的通知事件,每秒调用一次。
SKU:正在下载的SKU
Now:已经下载大小,单位为MB
Totak:目标下载大小,单位为MB
Code:下载过程中的状态码
Path:如果下载并MD5校验成功,返回文件地址
返回码 原因
S0000 查询成功
S1001 MD5 校验不通过
C1002 写入错误,储存空间不足
C1003 接收数据中断,可能是网络中断
C1004 向服务器发起连接请求失败
C1006 文件正在下载中
C1007 重复的下载请求
C1008 文件MD5正在校验中
C1000 系统异常
  • 解压文件压缩包
函数名 蓝图 功能
Un Zip File img 请求解压zip格式的压缩文件
in:
InPath: 需要解压的zip文件地址
InDest: 要解压到的文件地址
out:
FilePaths:返回所有文件解压后的文件地址
Code:调用接口时的响应代码
返回码 原因
S0000 解压成功
S1009 有一个任务正在解压中
C1000 解压失败
  • 跳转到商店指定DLC详情页
函数名 蓝图 功能
Launch Home img 跳转到Home:
in:
Key :跳转应用的Key
Value :值

参数示例:

Key Value 说明
dlc 123456 跳转到sku为123456的DLC的商品详情页。

# 5.6.3 服务器

# 5.6.3.1 服务器端查单接口

通过相关接口可以查看订单,请参见 4.1 服务器端查单接口 (opens new window)

# 5.6.3.2 服务端支付结果通知

对于消耗型DLC,用户支付完成后,奇遇平台会把相关支付结果及用户uid通过数据流的形式发给应用服务端,开发者需要接收处理,并按文档规范返回应答。

参见 4.2 服务端支付结果通知 (opens new window)

# 5.6.4 接入注意事项

  1. DLC发布和更新均需要经过平台审核,审核通过后上线到奇遇商店,审核标准参见《奇遇应用审核标准》
  2. 奇遇后台允许1个DLC对应上传1个文件,如果1个DLC包含多个文件,需压缩后上传
  3. 压缩文件类型的DLC下载后,如果需要解压,可通过SDK提供的解压zip方法,也可以使用第三方库实现加载前的解压功能。
  4. 对于持久型DLC,可通过客户端接口查验权益;对于消耗型DLC,用户可重复购买,平台无法标记游戏内多次权益下发的状态,需要开发者通过自己的游戏后台,接收奇遇后台的订单支付通知,进行权益下发并维护订单状态。

# 5.6.5 开发者自测

参见 3.6.5 开发者自测 (opens new window)

# 5.6.6 DLC Demo

请参见Platform Demo (opens new window)3.6.6 DLC Demo (opens new window)