高效率完成一次接入80个手游渠道SDK——游戏接入SDK客户端篇

一、引言

通常，游戏开发商并不会只在一个渠道上线他们的游戏，接入越多的渠道，代表着可能获取越多的用户，但同时也代表着越多的接入SDK工作量、工期和费用。一款游戏要有足够的用户，甚至需要接入30家以上的各种渠道，以保障自己的市场覆盖率。
单个SDK接入流程在一位有经验的全职客户端程序、一位全职服务端程序员、一位全职QA处理的情况下，需要3天时间才能完成。因此当一款产品面对30个甚至更多不同需求的渠道SDK时，人员成本和时间成本就会急剧增加。

所以我们需要一个通用接口，来处理各种渠道的需求，这就是统一渠道SDK接入框架。

二、资源导入

下载地址：

将TypeSDKLibrary文件夹整个添加到Unity工程中，注意结构需要与截图统一。建议游戏中与当前导入的脚本命名冲突的文件，需要由开发者自行修改冲突的类名

添加后的目录结构如下所示

三、代码接入

１、接入流程简要描述

SDK普通接入逻辑示意图

1.1在调用其它API前需先调用初始化接口对SDK进行初始化。

1.2在完成初始化接口调用后方可调用登录接口，登录成功选择角色进入游戏后需要调用提交用户信息接口。

1.3登录成功后如果需要切换账号，需调用登出接口。

1.4对于有依赖于登录用户的接口，如支付，提交用户信息接口，需要调用获取用户信息接口拿到相关数据，如user_id….

1.5在游戏退出时需要调用退出接口。

SDK的接入需要接入程序员实现接口的调用和回调函数的响应两个部分逻辑

a. 回调函数的响应主要通过设置监听来实现，具体请看第二节（回调函数的处理）

回调侦听的事件类型	事件说明
TypeEventType.EVENT_INIT_FINISH	SDK初始化完毕
TypeEventType.EVENT_LOGIN_SUCCESS	登录成功回调
TypeEventType.EVENT_PAY_RESULT	支付结果回调
TypeEventType.EVENT_LOGOU	登出完毕回调
TypeEventType.EVENT_RELOGIN	重新登录成功回调
TypeEventType.EVENT_CANCEL_EXIT_GAME	取消杀应用回调

b. 接口的调用主要为以下的接口调用，将会下后面详细讲解每个接口的调用

接口列表

函数名称	功能说明
InitSDK	SDK初始化
Login	显示登录界面
Logout	执行渠道登出，清理渠道用户缓存
PayItem	显示支付界面
ShowPersonCenter	显示用户中心（如果渠道支持）
ExitGame	大退游戏（等于杀进程）
IsHasRequest	判断渠道是否支持某功能（例如：用户中心）
UpdatePlayerInfo	提交用户信息到渠道（渠道要求在进入游戏后调用）

2、回调函数的处理

typesdkbaselib中已经提供了预先注册完毕所有回调侦听的cs文件：U3DTypeEventListener.cs接入方需要在U3DTypeEventListener监听类中，根据不同回调事件实现相应的游戏逻辑。

也可以根据自己需要，在游戏内合适的地方，参考demo自行注册相关的函数侦听。

注：接入方只能修改以下方法实现相应的逻辑，U3DTypeEventListener类中其它代码段建议不要更改，以免影响功能。

部分需要界面响应的监听，请判断当时场景，避免造成游戏逻辑混乱。如，在PVP时检测到用户切换账号。

//初始化完成后回调函数
void NotifyInitFinish(U3DTypeEvent evt)
{
//游戏需要等待此回调才允许调用登录接口。
}

    //登录操作完成后的回调函数
    void NotifyLogin(U3DTypeEvent evt){
        //解析渠道登录成功返回的信息，一般有user_token,user_id...
              //此时返回的结果不能作为登录依据，需要进过服务端验证，取的服务器返回的最终数据。
        //CP方需要将信息解析为CP服务器约定的数据格式转发给游戏服务器，并由游戏服务器转发至TypeSDK Server以完成游戏的登录验证
         string userId = evt.evtData.GetData(U3DTypeAttName.USER_ID);
}

    //更新渠道更新检测完成后回调
void NotifyUpdateFinish(U3DTypeEvent evt){
       //建议等待此更新完成后，再进行游戏的更新逻辑，否则会造成渠道更新和游戏自身更新冲突。
}

    //支付结果通知回调，CP需根据支付返回结果完成相应逻辑，此处为客户端返回结果，不可作为支付到账依据，游戏需等待TypeSDK Server的支付成功回调。
    void NotifyPayResult(U3DTypeEvent evt){
        if (evt.evtData.GetData(U3DTypeAttName.PAY_RESULT).Equals("1"))
{ //支付完成，可尝试延迟刷新账户余额信息。
            Debug.Log("pay finished:" + evt.evtData.GetData(U3DTypeAttName.PAY_RESULT_DATA));
        }
        else
        {//支付失败，或取消。
            Debug.Log("pay failed:" + evt.evtData.GetData(U3DTypeAttName.PAY_RESULT_REASON));
        }
}

    //登出结果通知回调，说明用户已经做了退出账户操作，需要返回登录界面，并重新调用登录
    void NotifyLogout(U3DTypeEvent evt){
}

    //重登录结果通知回调，用户在渠道SDK进行用户切换操作，需要切换到新账号界面。
    void NotifyRelogin(U3DTypeEvent evt){
}

    //取消退出游戏通知回调，把退出游戏逻辑说明一下。
    void NotifyCancelExit(U3DTypeEvent evt){
}

3、SDK传递的基本数据类型

sdk用到的数据类型 都继承于U3DTypeBaseData，相关使用示例如下：

3.1创建U3DTypeBaseData对象

U3DTypeBaseData  baseData = new U3DTypeBaseData();

3.2设置一条属性

函数名	public void SetData(string attName,string attValue)
参数列表	string attName,	U3DTypeAttName中定义的字段
	string attValue	目前支持int，string，boolean 三种类型基本数据
返回值	Void

示例：

//（键名使用U3DTypeAttName定义的字段）
baseData.SetData(“键名”,”值”);

3.3获得一个string类型的属性 attname为标识

函数名	public string GetData(string attName)
参数列表	string attName,	U3DTypeAttName中定义的字段
返回值	String	指定key值的string类型value

3.4获得一个int类型的属性 attname为标识

函数名	public int GetInt (string attName)
参数列表	string attName,	U3DTypeAttName中定义的字段
返回值	Int	指定key值的int类型value

3.5获得一个bool类型的属性 attname为标识

函数名

函数名	public bool GetBool(string attName)
参数列表	string attName,	U3DTypeAttName中定义的字段
返回值	Bool	指定key值的boolean类型value

使用例子：

//新建一个对象
       U3DTypeBaseData egData = new U3DTypeBaseData ();
//给该对象赋值
egData.SetData (U3DTypeAttName.APP_KEY, "123456789");
//读取一个string类型数据readStr = "123456789
        string readStr = egData.GetData (U3DTypeAttName.APP_KEY);
//读取一个int类型数据readInt
        int readInt = egData.GetInt(U3DTypeAttName.APP_KEY); = 123456789

响应消息传递的消息类型

public class U3DTypeEvent

函数名	public bool GetBool(string attName)
成员变量列表	public TypeEventType evtType	该事件的类型（枚举）
	public U3DTypeBaseData evtData	该事件所包含的数据（可以通过上述函数获取相关数据）

事件对象例子

void LoginResult(U3DTypeEvent evt)
    {
        U3DTypeBaseData data = evt.evtData;
        string userID = data.GetData(U3DTypeAttName.USER_ID);
        string userToken = data.GetData(U3DTypeAttName.USER_TOKEN);
  }

4、接口接入与描述

(1)初始化

函数名	public void InitSDK()
说明	sdk的初始化接口，再调用其他sdk功能前，请务必先执行该接口，所有渠道都要求在应用启动开始就调用此接口。

调用例子

U3DTypeSDK.Instance.InitSDK();

 (2)登录

函数名	public void Login ()
说明	显示登录界面，若登录成功则会发送TypeEventType.EVENT_LOGIN_SUCCESS消息。请在登录界面自动执行调用，不要出现需要点击按钮才显示的情况。 当用户登录失败时需要，再次调用此接口。

调用例子

U3DTypeSDK.Instance.Login();

(3)提交用户信息

函数名	public void UpdatePlayerInfo ()
说明	在有些指定事件，需要设置用户相关信息并且提交。登录完成进入游戏、用户升级、建角。

调用例子

U3DTypeSDK.Instance.UpdatePlayerInfo()

当用户成功完全登录进入游戏后，需要设置用户相关信息并且提交

该函数的所有内容，不能使用SDK客户端本地缓存的数据，建议从服务端获得

需要设置的属性如下，当没有该属性时，请传空字符串

string ROLE_TYPE = “create_role”;//角色统计信息类型即调用时机，（createRole:创建角色，levelUp:角色升级，enterGame:选定角色进入游戏）（不能为空）
string SAVED_BALANCE = “0”;//当前角色余额（RMB购买的游戏币），默认为0
string USER_NAME = "user_name"; //用户名
string USER_TOKEN = "user_token"; //用户渠道验证用token
string USER_ID = "user_id"; //用户id
string USER_HEAD_ID = "user_head_id"; //用户头像id
string USER_HEAD_URL = "user_head_url"; //用户头像url
string VIP_LEVEL = “vip_level”;//VIP等级，没有传0
string PARTY_NAME = “party_name”;//工会名称,如：天下第一
string ROLE_ID = "role_id"; //角色id
string ROLE_NAME = "role_name"; //角色名字
string ROLE_LEVEL = "role_level"; //角色等级
string ROLE_CREATE_TIME = “role_create_time”;//角色创建时间，一定要服务器时间（单位/秒）
string ROLE_LEVELUP_TIME = “role_levelup_time”;//角色升级时间（单位/秒）
string ZONE_ID = "zone_id"; //所在大区id
string ZONE_NAME= "zone_name"; //所在大区名称
string SEVER_ID = "server_id"; //所在服务器id
string SERVER_NAME = “server_name”;//所在服务器名称
string EXTRA ="extra";

参数值	说明
"0"	进入游戏主场景（即正式登录游戏）
"1"	创建新角色
"2"	角色升级

设置方法示例：

U3DTypeSDK.Instance.GetUserData().SetData(U3DTypeAttName.USER_ID, "123");
U3DTypeSDK.Instance.GetUserData().SetData(U3DTypeAttName.EXTRA, "1");
U3DTypeSDK.Instance.UpdatePlayerInfo();

(4)支付

函数名	public string PayItem (U3DTypeBaseData _in_pay);
说明	在获取服务器订单号，并在TypeSDK Server服务器提交订单信息后，调用此接口启动渠道的支付界面，进行支付行为

调用例子

U3DTypeSDK.Instance.PayItem (U3DTypeBaseData _in_pay);

其中U3DTypeBaseData中

U3DTypeBaseData userData = U3DTypeSDK.Instance.GetUserData();

必填参数为：

//用户ID，渠道返回，没有填空
payData.SetData(U3DTypeAttName.USER_ID,userData.GetData(U3DTypeAttName.USER_ID))；
//用户token，登录验签完成后由游戏服务端返回，没有填空
payData.SetData(U3DTypeAttName.USER_TOKEN,userData.GetData(U3DTypeAttName.USER_TOKEN))；
//商品支付价格（单位：分）
payData.SetData(U3DTypeAttName.REAL_PRICE,”100");
//商品名称
payData.SetData(U3DTypeAttName.ITEM_NAME,"sk bi”);
//商品数量
payData.SetData(U3DTypeAttName.ITEM_COUNT,”1");
//所在服务器id（如果没有填“0”）
payData.SetData(U3DTypeAttName.SERVER_ID,”1”);
//所在服务器名字（如果没有填“server_name”）
payData.SetData(U3DTypeAttName.SERVER_NAME,”安卓一区”);
//所在大区id（如果没有填“0”），注意应用宝要求：账户分区ID_角色ID。每个应用都有一个分区ID为1的默认分区，分区可以在cpay.qq.com/mpay上自助配置。如果应用选择支持角色，则角色ID接在分区ID号后用"_"连接，角色ID需要进行urlencode。payData.SetData(U3DTypeAttName.ZONE_ID,”1”);
//所在大区名字（如果没有填“server_name”）
payData.SetData(U3DTypeAttName.ZONE_NAME,”华北一区”);

//内部订单号（必须填写，并保证多区情况下，订单号唯一）
payData.SetData(U3DTypeAttName.BILL_NUMBER,”NO_123456”);
//商品id（需和TypeSDK Server商品列表保持一致）
payData.SetData(U3DTypeAttName.ITEM_SEVER_ID,”id”);
//传递的额外参数（建议传入需要用来做订单标识的信息）
payData.SetData(U3DTypeAttName.EXTRA,”extra");
//商品描述
payData.SetData(U3DTypeAttName.ITEM_DESC,”desc”);
//玩家在游戏中的角色ID
payData.SetData(U3DTypeAttName.ROLE_ID,”role_1234”);
//玩家在游戏中的角色名字
payData.SetData(U3DTypeAttName.ROLE_NAME,”玩家编号001”);

当支付行为在客户端完成后，会接到回调消息：EVENT_PAY_RESULT

其中event的使用类似 login

event中data的参数包括以下内容

PAY_RESULT//支付结果（1/0/2）成功／失败(除取消)/支付取消
//说明：客户端收到“失败或支付取消”状态，建议客户端可以使用户直接发起下笔充值。
PAY_RESULT_REASON//支付结果的原因（失败原因）
PAY_RESULT_DATA

(5)登出

函数名	public void Logout ();
说明	调用渠道的登出逻辑，不会有界面显示，但是会把渠道账户注销，需要由cp自行回到登录界面

调用例子：

U3DTypeSDK.Instance.Logout()

登出成功则会发送 TypeEventType.EVENT_LOGOUT消息，发送的参数U3DTypeBaseData数据

(6)退出

函数名	public void ExitGame ();
说明	调用渠道退出应用程序逻辑，执行成功，则会关闭应用

U3DTypeSDK.Instance.ExitGame();

整个游戏的退出行为 ，建议交给sdk处理，并且添加 退出行为取消响应事件侦听TypeEventType.EVENT_CANCEL_EXIT_GAME 的函数

当退出成功后 由sdk执行系统的退出，当退出取消后，则会发送 取消退出事件，接入方需完成相应的逻辑。

(7)获取当前渠道ＳＤＫ配置参数

U3DTypeSDK.Instance.GetPlatformData()

包括以下内容：

CHANNEL_ID//渠道的id（由SDK组定义 和ConfigSever上的channel id统一）
SDK_NAME//渠道标记
CP_ID

以上参数 在CPSeting.txt中填写（接入方无需关心）

(8)用户中心

显示渠道用户中心

U3DTypeSDK.Instance.ShowPersonCenter()

隐藏用户中心

U3DTypeSDK.Instance.HidePersonCenter()

在调用这2个函数之前 需要先执行IsHasRequest(U3DTypeAttName.SUPPORT_PERSON_CENTER)函数 用以判定 是否需要支持该函数。

当支持时 这2个函数才会起效，并且需要在游戏内，需要有相应的图形入口，

当不支持时，这2个函数不会生效，游戏内页不需要相应的图形入口。

使用示例：

if(IsHasRequest(U3DTypeAttName.SUPPORT_PERSON_CENTER)){
       U3DTypeSDK.Instance.ShowPersonCenter();

或

U3DTypeSDK.Instance.HidePersonCenter();
pushData.DataToString(_json_data);
U3DSDK.instance.SendMessage(“receive_local_notify”,pushData);
}

(9)查询渠道是否弹出退出框

U3DTypeSDK.Instance.IsHasRequest(“support_exit_window”)

该项目已开源，大家有兴趣可以自己研究或使用接入
项目地址：
项目地址：