1 功能介绍

重要！

监管部门对隐私政策的要求：

• 必须要经过 用户同意相关协议 后，
  • 游戏（包括打包在应用内的第三方SDK，下同）才能获取一定的用户隐私数据；
  • 否则，会被认定为违规、并通报整改，可能将导致应用审核不通过，严重者强制被下架。
• 游戏在使用特定权限时（如 android.permission.ACCESS_NETWORK_STATE），
  1. 必须先告知用户为何需要使用该权限，
  2. 经用户同意后，才可以向系统申请该权限（整个过程用户需要两次确认）；
• 相关接入事项:
  1. 4.2 协议接入

监管部门对防沉迷要求：

• 游戏必须接入未成年人防沉迷机制：
  1. 限制未成年人游戏时长，支持强制下线机制；
  2. 限制未成年人游戏充值；
• 相关接入事项:
  1. [4.11 CP踢出玩家下线通知]

监管部门对账号删除功能要求：

• 上架安卓国内渠道和苹果App Store必须拥有账号删除（账号注销）功能：
• 按照下面流程接入后，使用打包工具打官方渠道包，SDK自带账号删除功能，无需单独接入

本文介绍如何快速实现账号登陆、必要数据上报与调起支付，让您了解一个完整的接入流程。

以下事项为必接清单：

1. 设置SDK回调
2. SDK初始化
3. iOS闪屏（用于iOS平台）
4. 实现SDK回调方法
5. 账号登录
6. 角色上报
7. 退出登录
8. 调起支付
9. 游戏退出(Android专有)

2 前置条件

1. 请检查当前获取的 HeroUSDKPlugin插件为最新版本 点击这里下载
2. 已完成 快速接入的 第一步
3. 在HeroUSDK管理后台 (opens new window)中创建游戏并获取初始化所必须的参数，详见[4.3 初始化 -参数说明]（可联系游戏运营获取）
   • usdkProductId
   • usdkProductKey

• 注意： USDK插件目前只适配移动端,因此打包必须在真机上运行，否则所有插件中回调不成功

3 时序图

4 接入步骤

接入步骤可以参考时序图

4.1 配置融合参数

4.1.1 UE4插件配置

第一步：联系游戏运营在HeroUSDK管理后台 (opens new window)的游戏管理-游戏首页中获取初始化所必须参数，详见本节参数说明。

第二步：复制参数前，一定要先在，发行渠道配置-> 例如：【英雄互娱-iOS正版】或【全球SDK-谷歌商店】-> 打包参数及状态，配置包名、渠道参数、签名等信息

第三步：从中台拷贝参数复制到文件/打包项目/打包设置/插件/HeroUSDK配置文件中中台参数，并确保有网络情况下点击解析配置按钮，如图:

拉取配置成功后会自动填充渠道参数,如图:

配置参数说明

方法	说明	类型	重要性
中台参数	中台生成	string	必须
渠道参数	根据配置获取	string	必须
渠道	全球、国内渠道[二选一]	string	必须

注意事项

• 渠道配置是打包iOS需要使用.打Android母包时渠道默认即可
• 从中台复制参数后点击解析配置需要UE4编辑器处于联网状态,获取渠道配置需要联网
• 中台参数复制到UE4编辑器后,默认保存在DefaultEngine.ini配置文件中.

4.2 设置回调监听对象

场景介绍 需要 在SDK插件初始化之前设置回调监听对象，且只能初始化一次, 设置后才可以收到各端的相关回调方法,多次设置可能出现回调异常问题

收到USDK各种监听回调后，建议研发根据游戏自身业务处理不同的逻辑

• 第一步导入HeroUsdkSupportNotify.h文件

#include "HeroUsdkSupportNotify.h"

• 第二步 创建C++类并继承HeroUsdkSupportNotify类

class HeroUsdkSupportNotifyImpl : public HeroUsdkSupportNotify
{

}

• 第三步 实现HeroUsdkSupportNotify类中相关方法,参考如下必须实现的回调方法

void SetNotify(HeroUsdkSupportNotify *notify)

HeroUsdkSupportKit::GetInstance()->SetNotify(new HeroUsdkSupportNotifyImpl());

该监听回调方法详见如下,以下为必须实现的回调方法

场景介绍 用于监听USDK初始化的结果，来处理对应的逻辑，如等待USDK初始化成功后，才能做登录操作

void usdk_onInitCallBack(HeroUsdkResult result,FString msg) {} ;

场景介绍

• Android 由于同意协议操作比UE渲染界面更早，在渲染界面前已经同意了协议，可能无法收到usdk_onProtocolAgree回调
• 为了符合国内隐私政策，可以直接在4.3 初始化后，做相关隐私获取的操作

void usdk_onProtocolAgree();

场景介绍 USDK登录结果回调，根据返回结果做登录成功和失败后的操作

void usdk_onLoginCallBack(HeroUsdkResult result,FString userInfo,FString msg) {};

场景介绍 USDK切换账号回调，点击切换账号时，会回调此状态，可根据游戏自身业务做相关逻辑处理

void usdk_onSwitchAccountCallBack(HeroUsdkResult result,FString msg) {};

场景介绍 登录失效回调，登录失效后，可根据游戏自身业务做相关逻辑处理，如：回到登录界面，重新登录

void usdk_onLoginInvalid(FString msg){} ;

场景介绍 支付回调，根据返回结果做支付成功和失败后的操作

void usdk_onPayCallBack(HeroUsdkResult result,FString paymentOrder,FString msg){};

场景介绍 退出登录回调，退出登录后，可根据游戏自身业务做相关逻辑处理，如：回到登录界面，重新登录

void usdk_onLogoutCallBack(HeroUsdkResult result,FString msg)  {};

场景介绍 退出游戏回调

void usdk_onExitCallBack(HeroUsdkResult result,FString msg) { };

场景介绍 注销完成回调，注销完成后，可根据游戏自身业务做相关逻辑处理，如：回到登录界面，重新登录

void usdk_onAccountCancellation(HeroUsdkResult result, FString msg){} ;

4.3 初始化

调用时机

• 必须在实现4.2 设置回调监听对象后，调用初始化方法
• 初始化方法尽可能的早调用

//初始化融合SDK
HeroUsdkSupportKit::GetInstance()->init() ;

void usdk_onInitCallBack(HeroUsdkResult result,FString msg) {
    if (result == HeroUsdkSuccess) {
        //初始化成功
        //这里可以做其他三方sdk的初始化操作或者游戏的加载操作
        //安卓国内官方渠道与安卓全球渠道调用初始化就会立即返回成功，避免因网络原因阻碍了游戏在这里的相关操作
    } else {
        //初始化失败，msg为错误信息
        //这里研发自行处理是否给玩家弹框提示
    }
}

4.4 闪屏【Android无需配置】

场景介绍

用于统计闪屏结束后的用户留存 , iOS将调用示例中代码复制到闪屏结束后即可

#if PLATFORM_IOS

//游戏播放完过渡视频上报闪屏
HeroUsdkSupportKit::GetInstance()->postSplashScreenEndSuccess();

#endif

void postSplashScreenEndSuccess()

4.5 协议接入

WARNING

请注意，国内有隐私政策要求!

隐私政策要求：游戏必须经过用户同意相关隐私协议，才能获取涉及用户隐私的数据。否则，可能导致应用审核不过，严重时会导致游戏下架。

4.5.1 获取协议内容

场景介绍

用于在游戏主界面或者设置界面，需要使用USDK协议内容的场景

操作步骤

第一步： 获取USDK协议内容，根据中台的配置，可能返回多个协议(具体字段说明详见下表)，每个协议包括协议名称及协议url。

第二步：将调用示例代码复制到使用的地方即可

备注：如果没有协议，返回nil

FString protocolResult = HeroUsdkSupportKit::GetInstance()->getProtocolResult() ;
//protocolResult为协议内容JSON字符串
{
	"userAgrName": "英雄互娱用户协议",
	"priAgrName": "英雄互娱个人信息保护政策",
	"userAgrUrl": "https://www.yingxiong.com/p/agreement_global.html?productId=17287&cid=0",
	"childAgrName": "英雄互娱儿童个人信息保护政策",
	"priAgrUrl": "https://www.yingxiong.com/p/per_adu?productId=17287&cid=0",
	"childAgrUrl": "https://www.yingxiong.com/p/per_child?productId=17287&cid=0",
}

FString getProtocolResult()

协议返回值字段说明

字段	类型	说明
priAgrName	string	个人信息保护协议名称
priAgrUrl	string	个人信息保护协议url
userAgrName	string	用户协议名称
userAgrUrl	string	用户协议url
childAgrName	string	儿童个人信息保护协议名称
childAgrUrl	string	儿童个人信息保护协议url

4.5.2 同意协议通知

场景介绍

此接口仅用于游戏使用USDK的协议弹出框，用于监听协议弹出框用户是否点击了同意。

备注：游戏未收到用户同意协议的回调前，自身及接入的其他三方SDK都不能产生任何获取隐式数据行为，如不能调用init，login等接口

通知回调方法

void usdk_onProtocolAgree() {
    //点击同意协议之后回调方法
}

4.5.3 点击同意通知

场景介绍

• 此接口仅用于游戏使用自己的协议弹出框，而不使用USDK的。在用户点击同意后，游戏需要调用此接口通知USDK,以便USDK继续走登录流程。

• 需要游戏自己绘制协议界面

调用方法

void setAgreeProtocol()

调用示例

HeroUsdkSupportKit::GetInstance()->setAgreeProtocol();

4.6 登陆

4.6.1 融合登录

场景介绍

为了优化玩家的登录体验，需要在登录时接入登录接口、用户中心接口、客服接口三个接口

• 前置登录界面
  • 在游戏更新前显示登录界面，以避免更新过程中导致玩家流失并无法联系客服
  • 游戏到登录界面时自动调用登录接口
    • 未登录过的玩家，弹出登录界面，点击登录后快速进入游戏，无登录浮窗
    • 已登录过的玩家，无感知自动登录并快速进入游戏，无登录浮窗
• 自绘用户中心按钮
  • 在登录界面上提供账号中心按钮，方便玩家查询当前账号、切换账号、绑定手机、联系客服等
• 自绘联系客服按钮
  • 在登录界面上提供联系客服按钮，方便玩家在登录出现问题时直接联系客服解决。

//SDK登录
HeroUsdkSupportKit::GetInstance()->login();

// 打开用户中心
HeroUsdkSupportKit::GetInstance()->showAccountCenter();

// 打开客服界面
HeroUsdkSupportKit::GetInstance().OpenService();

/*
 *  登录
 */
void login()

/*
 *  打开用户中心
 */
void showAccountCenter();

/*
 *  客服中心
 */
void HeroUsdkSupportKit::OpenService()

void usdk_onLoginCallBack(HeroUsdkResult result,FString userInfo,FString msg) {
    if(result == HeroUsdkSuccess) {
        //登录成功

        // 若已有玩家正在游戏中，收到该回调，需要回到游戏主界面，切换玩家数据
        // 否则直接进入游戏登录操作
        struct FUserInfo Result ;
        FJsonObjectConverter::JsonObjectStringToUStruct(userInfo, &Result, 0, 0);
    } else if(result == HeroUsdkFailed) {
        //登录失败
    } else if(result == HeroUsdkCancel) {
        //取消登录
    }
}

FUserInfo字段说明

字段	类型	说明
plat	string	平台固定值
accessToken	string	授权token
sdkUserId	string	用户ID
userName	string	登录用户名

拓展字段说明

由于不同游戏有特殊的业务需求，这里会返回些拓展字段，供游戏根据自身业务使用

字段	类型	说明
accessCode	string	授权code[iOS]

字段	类型	说明
serverMessage	string	服务器消息[android]
isFristLogin	string	是否首次登录[android]
extendParams	string	拓展信息[android]
channelToken	string	渠道token[android]

4.6.2 切换账号

场景介绍

用于游戏内SDK登录界面，给玩家提供切换账号操作

切换账号回调

void usdk_onSwitchAccountCallBack(HeroUsdkResult result,FString msg) {

    if (result == HeroUsdkSuccess) {
        // 切换账号成功
        // 若已有玩家正在游戏中，收到该回调，需要回到游戏主界面，切换玩家数据
        // 否则直接进入游戏登录操作
    } else {
        // 切换账号失败
    }
}

4.6.3 玩家被踢下线

场景介绍

游戏内游客玩家已达到最大试玩时间被踢下线回调

被踢下线回调

void usdk_onLoginInvalid(FString msg) {
    //msg为被踢下线原因
}

4.7 角色上报

WARNING

基础数据设置，在上报数据前，必须先初始化初始数据，数据必须是真实信息，有些字段如果没有，可以默认传1

场景介绍

• 角色上报接口，用于统计游戏方的角色等信息，必须在登录后调用
• 角色上报的信息，会用于中台进行数据分析
• roleId、roleName、serverId、serverName 支付下单时也会使用，不上报会影响到支付功能

参数说明

• FHeroHDCGameRoleInfo类字段说明

字段	类型	说明
channelUserId	String	渠道用户ID(玩家登录账号)	（必传）
gameUserId	String	游戏生成的账号ID	（必传）
serverId	String	区服ID	（必传）
serverName	String	区服名称	（必传）
roleId	String	角色ID	（必传）
roleName	String	角色名	（必传）
roleAvatar	String	头像	（选传）
level	String	角色等级	（必传-如游戏无此参数，则默认传1）
vipLevel	String	VIP等级	（必传-如游戏无此参数，则默认传1）
gold1	String	当前一级货币数量（充值获得）	（必传-如游戏无此参数，则默认传1）
gold2	String	当前二级货币数量（游戏内产出）	（必传-如游戏无此参数，则默认传1）

4.7.1 角色登录

场景介绍

用于角色登录时，调用此接口，上报前需要先调用角色上报基础接口，具体参数的值必须真实有效

调用示例

struct FHeroHDCGameRoleInfo gameRoleInfo ;
gameRoleInfo.channelUserId = "100128";
gameRoleInfo.gameUserId = "100128";
gameRoleInfo.serverId = "1";
gameRoleInfo.serverName = TEXT("火星服务器");
gameRoleInfo.roleId = "000001";
gameRoleInfo.roleName = TEXT("钱多多");
gameRoleInfo.roleAvatar = "";
gameRoleInfo.level = "1";
gameRoleInfo.vipLevel = "2";
gameRoleInfo.gold1 = "3";
gameRoleInfo.gold2 = "4";

//进入游戏
HeroUsdkSupportKit::GetInstance()->enterGame(gameRoleInfo) ;

4.7.2 角色注册

场景介绍

用于角色注册时，调用此接口，上报前需要先调用角色上报基础接口，具体参数的值必须真实有效 必接。

调用示例

struct FHeroHDCGameRoleInfo gameRoleInfo ;
gameRoleInfo.channelUserId = "100128";
gameRoleInfo.gameUserId = "100128";
gameRoleInfo.serverId = "1";
gameRoleInfo.serverName = TEXT("火星服务器");
gameRoleInfo.roleId = "000001";
gameRoleInfo.roleName = TEXT("钱多多");
gameRoleInfo.roleAvatar = "";
gameRoleInfo.level = "1";
gameRoleInfo.vipLevel = "2";
gameRoleInfo.gold1 = "3";
gameRoleInfo.gold2 = "4";

//创建角色
HeroUsdkSupportKit::GetInstance()->createNewRole(gameRoleInfo) ;

4.7.3 角色升级

场景介绍

用于角色升级时，调用此接口，上报前需要先调用角色上报基础接口，具体参数的值必须真实有效

调用示例

struct FHeroHDCGameRoleInfo gameRoleInfo ;
gameRoleInfo.channelUserId = "100128";
gameRoleInfo.gameUserId = "100128";
gameRoleInfo.serverId = "1";
gameRoleInfo.serverName = TEXT("火星服务器");
gameRoleInfo.roleId = "000001";
gameRoleInfo.roleName = TEXT("钱多多");
gameRoleInfo.roleAvatar = "";
gameRoleInfo.level = "1";
gameRoleInfo.vipLevel = "2";
gameRoleInfo.gold1 = "3";
gameRoleInfo.gold2 = "4";

//角色升级
HeroUsdkSupportKit::GetInstance()->roleLevelUp(gameRoleInfo) ;

4.8 支付

4.8.1 发起购买

参数说明

• FHeroUPaymentParameters类字段说明

字段	类型	说明
goodsId	string	商品ID
extraParams	string	透传参数
cpOrder	string	CP订单号
callbackUrl	string	内购回调地址，两种配置方式： 1、可由运营在后台-游戏管理中进行配置，若运营在后台进行了配置则此参数无效； 2、可由开发者在代码中写入 3、如果想实现不同区服的回调，则需要游戏自己区分区服实现

struct FHeroUPaymentParameters paymentParameters ;
paymentParameters.goodsId = "1000" ;
paymentParameters.extraParams = "customMsg" ;
FDateTime Time = FDateTime::Now();
int64 Timestamp = Time.ToUnixTimestamp();
FString NewString = FString::FromInt(Timestamp);
UE_LOG(LogTemp, Log, TEXT("NewString : %s"),*NewString) ;

paymentParameters.cpOrder = NewString ;
paymentParameters.callbackUrl = "callbackUrl" ;

struct FHeroHDCGameRoleInfo gameRoleInfo ;
gameRoleInfo.channelUserId = "100128";
gameRoleInfo.gameUserId = "100128";
gameRoleInfo.serverId = "1";
gameRoleInfo.serverName = TEXT("火星服务器");
gameRoleInfo.roleId = "000001";
gameRoleInfo.roleName = TEXT("钱多多");
gameRoleInfo.roleAvatar = "";
gameRoleInfo.level = "1";
gameRoleInfo.vipLevel = "2";
gameRoleInfo.gold1 = "3";
gameRoleInfo.gold2 = "4";

//内购
HeroUsdkSupportKit::GetInstance()->pay(paymentParameters,gameRoleInfo) ;

void pay(FHeroUPaymentParameters paymentParametersData,FHeroHDCGameRoleInfo roleInfo)

void usdk_onPayCallBack(HeroUsdkResult result,FString paymentOrder,FString msg){
    if (result == HeroUsdkSuccess) {
        //支付成功
    } else if(result == HeroUsdkFailed) {
        //支付失败
    } else if (result == HeroUsdkCancel) {
        //取消支付
    }
}

支付回调成功后字段说明

字段	类型	说明
plat	string	平台固定值[android]和[iOS]
sdkOrderId	string	订单号[android]和[iOS]
orderAmount	string	订单金额[iOS]
currency	string	币种[iOS]
cpOrderId	string	cp订单号[android]
extraParams	string	拓展信息[android]

WARNING

游戏判断充值支付是否成功到账，必须以游戏服务器收到的通知为准，不能以客户端的通知为准，因为部分渠道SDK客户端的支付通知不准确。

4.9 退出登录

场景介绍

适用于游戏退出登录时，清空SDK的登录信息

HeroUsdkSupportKit::GetInstance()->logout();

void logout()

void usdk_onLogoutCallBack(HeroUsdkResult result,FString msg)  {
    if (result == HeroUsdkSuccess) {
        //退出登录成功
    } else {
        //退出登录失败
    }
}

4.10 退出游戏[仅Android]

场景介绍

适用于游戏退出时，渠道回调

HeroUsdkSupportKit::GetInstance()-> exit();

void exit()

void usdk_onExitCallBack(HeroUsdkResult result,FString msg) {

    if (result == HeroUsdkSuccess) {
        //退出成功
    } else {
        //退出失败
    }
}

4.11 CP踢出玩家下线通知

场景介绍

• 根据国家政策必须接入此代码
• 此接口是游戏客户端上报至USDK即可，是客户端上报，与游戏服务端无关；游戏客户端在收到踢玩家下线通知后（void usdk_onLoginInvalid(FString msg)），在回调中调用cpKickOffCallBackWithResult接口上报给USDK，告知USDK游戏已经执行踢人操作，并且游戏界面需要回到登录界面

操作步骤

可以复制调用示例的代码

调用示例

void usdk_onLoginInvalid(FString msg) {
    HeroUsdkSupportKit::GetInstance()-> cpKickOffCallBackWithResult("被踢下线") ;
}

5 测试指南

如果在接入、测试过程中遇到问题，你可以点击查看常见问题

5.1 如何验证登入功能接入成功？

登陆接入是否的验证，只需要开发者在代码中检查在用户登陆后是否有登陆回调，若有，即表示该功能接入成功

5.2 如何验证支付功能接入成功？

支付成功的验证，只需要点击商品购买后，确保界面拉起支付验证界面即表示该功能接入成功。

恭喜你完成快速接入，登陆与支付功能即可正常使用啦， 推荐你了解USDK更多拓展功能～

信息获取-拓展功能

通用接口-拓展功能