第二步：开始接入 | Ultra开发接入文档

# 1 功能介绍

重要！

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

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

监管部门对防沉迷要求：

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

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

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

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

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

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

# 2 前置条件

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

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

# 3 时序图

# 4 接入步骤

接入步骤可以参考时序图

# 4.1 初始化

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

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

# 第二步：`BuildPipe.cs`文件修改配置

相关参数获取请在UltraSDK管理后台 (opens new window)的游戏管理-游戏首页中获取

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

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

参数说明

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

特别说明: 由于国内政策原因,Android初始化需要在同意协议之后调用.因此初始化流程有所区别,如下代码:


#if UNITY_ANDROID && !UNITY_EDITOR

UltraSDK.Instance.SdkProtocolAgree(() =>
{
	//init SDK
	Debug.Log("SdkProtocolAgree ");

	UltraSDK.Instance.InitWithUltraSDK(project, (code, msg) => {
		if (code == UltraSDKResult.UltraSDKResultSuccess)
		{
			Debug.Log("InitWithUltraSDK Success");
		} else {
			Debug.Log("InitWithUltraSDK Fail");
		}
	});
});

#endif

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

具体代码可参考Demo实例

# 4.2 闪屏上报

场景介绍

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

# 4.3 协议接入

场景介绍

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

# 4.3.1 获取协议内容

场景介绍

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

操作步骤

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

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

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

协议返回值字段说明

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

# 4.3.2 同意协议通知

场景介绍

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

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

通知回调方法


UltraSDK.Instance.SdkProtocolAgree(() =>
{
	//初始化其他SDK
});

1
2
3
4
5
6
7

# 4.3.3 点击同意通知

场景介绍

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

# 4.4 登陆

# 4.4.1 融合登录

场景介绍

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

字段说明

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

字段	类型	说明
plat	string	平台固定值[android]
accessToken	string	授权token[android]
sdkUserId	string	用户ID[android]
userName	string	登录用户名[android]
serverMessage	string	服务器消息[android]
isFristLogin	string	是否首次登录[android]
extendParams	string	拓展信息[android]
channelToken	string	渠道token[android]

# 4.5 角色上报

WARNING

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

场景介绍

角色上报接口用于统计游戏方的角色等信息，主要是方便UltraSDK根据角色查询业务异常，必须在完成登录后方可调用
角色上报的信息，会用于中台进行数据分析
roleId、roleName、serverId、serverName 支付下单时也会使用，不上报会影响到支付功能

参数说明

UltraGameRoleInfo类字段说明

字段	类型	说明
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）
sumPay	String	累计充值金额）	（必传-如游戏无此参数，则默认传1）

# 4.5.1 角色登录

场景介绍

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

调用示例


UltraGameRoleInfo gameRoleInfo = new UltraGameRoleInfo();
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";
gameRoleInfo.sumPay = "5";
//角色登录
UltraSDK.Instance.EnterGame(gameRoleInfo);

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

# 4.5.2 角色注册

场景介绍

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

调用示例


UltraGameRoleInfo gameRoleInfo = new UltraGameRoleInfo();
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";
gameRoleInfo.sumPay = "5";
//创建角色
UltraSDK.Instance.CreateNewRole(gameRoleInfo);

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

# 4.5.3 角色升级

场景介绍

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

调用示例


UltraGameRoleInfo gameRoleInfo = new UltraGameRoleInfo();
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";
gameRoleInfo.sumPay = "5";
//角色升级
UltraSDK.Instance.RoleLevelUp(gameRoleInfo);

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

# 4.6 支付

# 4.6.1 发起购买

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

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

参数说明

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

字段	类型	说明
plat	string	平台固定值[android]和[ios]
sdkOrderId	string	订单号[iOS、android]
orderAmount	string	订单金额[iOS]
currency	string	币种[iOS]
cpOrderId	string	cp订单号[android]
extraParams	string	拓展信息[android],iOS因为支付为异步操作，无法进行匹配。服务器端支付回调中会返回游戏订单号以及透传参数等

WARNING

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

# 4.7 退出登录

场景介绍

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

# 4.8 退出游戏[Android独有]

场景介绍

适用于游戏退出时，渠道退出回调，安卓需要接入
可以判断是否是渠道退出；游戏也可以自己定制退出弹框

# 4.8.1 退出游戏监听[必须接入]

不论你是使用USDK的Exit接口退出游戏，还是使用第三方接口实现退出游戏，你都应该接入[退出游戏]监听接口，以保证客户端实时接收到"渠道退出游戏结果"回调！

调用USDK内置函数退出游戏示例

# 4.9 CP踢出玩家下线通知

场景介绍

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

操作步骤

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

调用示例


//设置登录失效回调,设置时机在4.3.2同意协议回调之后
UltraSDK.Instance.SDKLoginInvalid(OnLoginInvalidCallBack);

private void OnLoginInvalidCallBack(UltraSDKLoginInvalidResult result, string msg)
{
	if (result == UltraSDKLoginInvalidResult.UltraSDKLoginInvalidKick)
	{
		showLog("onUltrasdkLoginInvalid 未成年人被踢下线", "msg: " + msg);
		//游戏退出当前登录账户,并返回到未登录界面.调用如下接口通知SDK踢人成功
		UltraSDK.Instance.cpKickOffCallBackWithResult(msg) ;
	}
	else
	{
		showLog("onUltrasdkLoginInvalid 登录失效", "msg: " + msg);
	}
}

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

# 5 测试指南

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

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

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

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

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

# 5.1 开发自测

# 登录功能

用户登录后，在代码中检查是否有登录回调，有回调即表示接入成功。

# 支付功能

点击商品购买后，确保界面能拉起支付验证界面，能拉起即表示接入成功（注：母包支付过程中，客户端点击后弹出的【支付成功】和【支付失败】选项仅用于发出客户端通知，服务器发货通知则是以是否使用此处创建的测试账号且账号余额足够为判断依据）。

# 5.2 QA测试

完成登录、支付功能自测后，提交QA测试，可参考母包测试用例 (opens new window)

# 恭喜你完成快速接入，登陆与支付功能即可正常使用啦，如果需要出渠道包详情见《第三步》。

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

# 信息获取-拓展功能

# 通用接口-拓展功能

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

# 1 功能介绍

# 2 前置条件

# 3 时序图

# 4 接入步骤

# 4.1 初始化

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

# 第二步：BuildPipe.cs文件修改配置

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

# 4.2 闪屏上报

# 4.3 协议接入

# 4.3.1 获取协议内容

# 4.3.2 同意协议通知

# 4.3.3 点击同意通知

# 4.4 登陆

# 4.4.1 融合登录

# 4.5 角色上报

# 4.5.1 角色登录

# 4.5.2 角色注册

# 4.5.3 角色升级

# 4.6 支付

# 4.6.1 发起购买

# 4.7 退出登录

# 4.8 退出游戏[Android独有]

# 4.8.1 退出游戏监听[必须接入]

# 4.9 CP踢出玩家下线通知

# 5 测试指南

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

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

# 5.1 开发自测

# 登录功能

# 支付功能

# 5.2 QA测试

# 恭喜你完成快速接入，登陆与支付功能即可正常使用啦，如果需要出渠道包详情见 《第三步》。

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

# 信息获取-拓展功能

# 通用接口-拓展功能

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

# 第二步：`BuildPipe.cs`文件修改配置

# 恭喜你完成快速接入，登陆与支付功能即可正常使用啦，如果需要出渠道包详情见《第三步》。