第二步：接入开始

# 1 功能介绍

重要！

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

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

监管部门对防沉迷要求：

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

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

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

本文将介绍如何快速实现登陆、数据上报与支付，让开发者简单了解一个完整的接入。

完成本文必接功能，你可以实现

设置回调监听对象
融合初始化
iOS闪屏
实现融合回调方法
登录
角色上报
退出登录
支付
Android退出

# 2 前置条件

在开始接入前你需要确保以下条件已完成：

保证快速接入的第一步已完成
保证当前获取的引擎插件为最新版本
在USDK管理后台 (opens new window)中创建游戏并获取初始化所必须的参数,详见 [4.2 初始化 -参数说明]（可联系游戏运营获取）
注意： USDK插件目前只适配移动端,因此打包必须在真机上运行，否则所有插件中回调不成功

# 3 时序图

# 4 接入步骤

接入步骤可以参考时序图

# 4.1 设置回调监听对象

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

调用方法

public void setListener(HeroUSDKListener listener)

调用示例

HeroUSDK.getInstance ().setListener (this);

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

# 4.2 初始化

# 第一步：获取初始化接口参数

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

# 第二步：`herosdkcfg.xml`文件配置[仅Android]

herosdkcfg.xml文件为USDK(融合sdk)配置文件,文件内融合相关参数获取请在USDK管理后台 (opens new window)的游戏管理-游戏首页中获取

获取参数，详见本节参数说明
- _hu_pid_ HeroUSDK的必传参数,productID,接入时请将其替换为游戏对应的值
- _hu_pk_ HeroUSDK的必传参数,productKey,接入时请将其替换为游戏对应的值
配置文件截图如下:

# 第三步：配置参数进行初始化

方法	说明	类型	重要性
usdkProductId	设置产品id(后台中的ProductId)	string	必须
usdkProductKey	设置产品密钥 (后台中的ProductKey)	string	必须

方法	说明	类型	重要性
productId	产品ID	string	必须
projectId	项目ID	string	必须
serverId	服务器ID	string	必须
appKey	appKey	string	必须
appSecret	appSecret	string	必须
gameName	游戏名称	string	必须
cid	渠道ID	string	必须
pkg	游戏包名	string	必须

# 4.3 闪屏上报

场景介绍

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

# 4.4 协议接入

场景介绍

协议弹窗用于国家对隐私政策的要求，必须要同意相关协议，才能获取用户隐私，否则可能导致应用审核不过，或者被下架

# 4.4.1 获取协议内容

场景介绍

用于在游戏主界面或者设置界面，需要使用USDK协议内容的场景，仅支持iOS、Android端

操作步骤

第一步：获取USDK协议内容，根据USDK后台的配置（配置位置：USDK管理后台 (opens new window)-游戏管理-USDK管理-协议管理），可能返回多个协议(具体字段说明详见下表)，每个协议包括协议名称及协议url。

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

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

协议返回值字段说明

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

# 4.4.2 同意协议通知

场景介绍

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

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

通知回调方法

public override void usdk_onProtocolAgree()
{
	//这里处理同意协议后的逻辑
}

1
2
3
4

# 4.3.3 点击同意通知

场景介绍

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

调用方法

public void setAgreeProtocol()

调用示例

HeroUSDK.getInstance().setAgreeProtocol();

# 4.5 登陆

# 4.5.1 融合登录

场景介绍

用于游戏方调起登录界面，给玩家提供登录操作，如果成功会弹出登录界面

UserInfo字段说明

字段	类型	说明
plat	string	平台固定值[iOS、android、pc]
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.5.2 切换账号

场景介绍

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

切换账号回调


public override void usdk_onSwitchAccountCallBack(HeroUSDKResult result, UserInfo userInfo,string msg)
{
	if (result == HeroUSDKResult.HeroUSDKResultSuccess)
	{
		//切换账号成功。
		//Android
		//若已有玩家正在游戏中，收到该回调，需要回到游戏主界面，切换玩家数据
		//负责直接进入游戏登录操作
	}
	else if (result == HeroUSDKResult.HeroUSDKResultFailed) {
        //切换失败,msg为错误信息
	}
	else if(result == HeroUSDKResult.HeroUSDKResultCancel)
    {
         //取消切换[android独有]
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

注意:切换账号回调,游戏只需要退出登录并返回到未登录页面。iOS端无法获取回调中的UserInfo字段

# 4.5.3 玩家被踢下线

场景介绍

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

被踢下线回调


public override void usdk_onLoginInvalid(string msg)
{
	//msg不为空时。为被踢下线理由,游戏收到此回调需要退出登录，并返回到未登录界面，调用SDK的`cpKickOffCallBackWithResult`接口，告知usdk游戏已经执行踢人操作
	//msg为空时收到此回调，USDK登录失效。游戏需要返回登录界面重新登录
}

1
2
3
4
5
6
7

# 4.6 角色上报

WARNING

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

场景介绍

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

参数说明

HeroHDCGameRoleInfo类字段说明

字段	类型	说明
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.6.1 角色登录

场景介绍

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

调用示例


HeroHDCGameRoleInfo gameRoleInfo = new HeroHDCGameRoleInfo();
gameRoleInfo.channelUserId = "100128";
gameRoleInfo.gameUserId = "100128";
gameRoleInfo.serverId = "1";
gameRoleInfo.serverName = "火星服务器";
gameRoleInfo.roleId = "000001";
gameRoleInfo.roleName = "钱多多";
gameRoleInfo.roleAvatar = "";
gameRoleInfo.level = "1";
gameRoleInfo.vipLevel = "2";
gameRoleInfo.gold1 = "3";
gameRoleInfo.gold2 = "4";
HeroUSDK.getInstance ().enterGame(gameRoleInfo);//角色登录

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 4.6.2 角色注册

场景介绍

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

调用示例


HeroHDCGameRoleInfo gameRoleInfo = new HeroHDCGameRoleInfo();
gameRoleInfo.channelUserId = "100128";
gameRoleInfo.gameUserId = "100128";
gameRoleInfo.serverId = "1";
gameRoleInfo.serverName = "火星服务器";
gameRoleInfo.roleId = "000001";
gameRoleInfo.roleName = "钱多多";
gameRoleInfo.roleAvatar = "";
gameRoleInfo.level = "1";
gameRoleInfo.vipLevel = "2";
gameRoleInfo.gold1 = "3";
gameRoleInfo.gold2 = "4";
HeroUSDK.getInstance ().createNewRole(gameRoleInfo);//创建角色

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 4.6.3 角色升级

场景介绍

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

调用示例


HeroHDCGameRoleInfo gameRoleInfo = new HeroHDCGameRoleInfo();
gameRoleInfo.channelUserId = "100128";
gameRoleInfo.gameUserId = "100128";
gameRoleInfo.serverId = "1";
gameRoleInfo.serverName = "火星服务器";
gameRoleInfo.roleId = "000001";
gameRoleInfo.roleName = "钱多多";
gameRoleInfo.roleAvatar = "";
gameRoleInfo.level = "1";
gameRoleInfo.vipLevel = "2";
gameRoleInfo.gold1 = "3";
gameRoleInfo.gold2 = "4";
HeroUSDK.getInstance ().roleLevelUp(gameRoleInfo);//角色升级

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 4.7 支付

# 4.7.1 发起购买

该步骤调用后，即可拉起支付：

请保证在开始前在usdk管理后台-商品管理中已完成游戏商品配置
支付前，请保证角色上报成功

参数说明

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

WARNING

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

# 4.8 退出登录

场景介绍

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

备注：安卓平台下面两种退出登录方式都是一样的，ios平台logoutAndSowLoginView这个方法退出会返回登录界面

1.退出登录不返回登录界面

2.退出登录返回登录界面

# 4.9 退出游戏[Android独有]

场景介绍

适用于游戏退出时，渠道退出回调，安卓需要接入

# 4.10 CP踢出玩家下线通知

场景介绍

根据国家政策必须接入此代码
此接口是游戏客户端上报至USDK即可，是客户端上报，与游戏服务端无关；游戏客户端在接收到回调方法usdk_onLoginInvalid后，游戏需要退出当前登录账户，并返回到未登录界面，调用cpKickOffCallBackWithResult接口上报给USDK，告知USDK游戏客户端已经执行踢人操作
仅支持iOS、Android，pc端使用

操作步骤

直接复制调用示例的代码到使用位置

调用示例

public override void usdk_onLoginInvalid(string msg) {

	//msg不为空时。为被踢下线理由,游戏收到此回调需要退出登录，并返回到未登录界面，调用SDK的`cpKickOffCallBackWithResult`接口，告知usdk游戏已经执行踢人操作
     Debug.Log(msg);
	 //写入游戏被踢下线逻辑
	
	//msg为空时收到此回调，USDK登录失效。游戏需要返回登录界面重新登录
}

1
2
3
4
5
6
7
8
9

# 5 测试指南

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

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

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

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

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

# 恭喜你完成快速接入，登陆与支付功能即可正常使用啦，如果Android平台可以直接在USDK管理后台打包，如果iOS平台则需要继续进行《第三步》。

# 推荐你了解USDK更多拓展功能～

# 信息获取-拓展功能

# 扫码登录-拓展功能

本文档对解决你的问题有所帮助？

# 1 功能介绍

# 2 前置条件

# 3 时序图

# 4 接入步骤

# 4.1 设置回调监听对象

# 4.2 初始化

# 第一步： 获取初始化接口参数

# 第二步：herosdkcfg.xml文件配置[仅Android]

# 第三步：配置参数进行初始化

# 4.3 闪屏上报

# 4.4 协议接入

# 4.4.1 获取协议内容

# 4.4.2 同意协议通知

# 4.3.3 点击同意通知

# 4.5 登陆

# 4.5.1 融合登录

# 4.5.2 切换账号

# 4.5.3 玩家被踢下线

# 4.6 角色上报

# 4.6.1 角色登录

# 4.6.2 角色注册

# 4.6.3 角色升级

# 4.7 支付

# 4.7.1 发起购买

# 4.8 退出登录

# 4.9 退出游戏[Android独有]

# 4.10 CP踢出玩家下线通知

# 5 测试指南

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

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

# 恭喜你完成快速接入，登陆与支付功能即可正常使用啦，如果Android平台可以直接在USDK管理后台打包，如果iOS平台则需要继续进行 《第三步》。

# 推荐你了解USDK更多拓展功能～

# 信息获取-拓展功能

# 扫码登录-拓展功能

# 第一步：获取初始化接口参数

# 第二步：`herosdkcfg.xml`文件配置[仅Android]

# 恭喜你完成快速接入，登陆与支付功能即可正常使用啦，如果Android平台可以直接在USDK管理后台打包，如果iOS平台则需要继续进行《第三步》。