指尖H5游戏对接文档

版本 修改人 修改时间 修改内容
v1.0 zibin.zhang 2019/10/25 新建对接文档
v1.1 zibin.zhang 2019/12/20 修改获取功能开关状态方式,改用switchStatus字段获取
V1.2 zibin.zhang 2019/12/30 功能按钮新增实名认证功能

1. 接入步骤说明


  1. 游戏接入指尖游戏平台要先申请gameId以及密钥(game_secret)。
  2. 接口所有参数编码统一为utf-8
  3. 游戏方需提供测试和正式的地址: 游戏入口地址、支付回调地址。

2. 初始化


  • 1.引入js地址://client.hhycdk.com/hitalksdk.js (注意:尽量不要添加http,以便自适应http和https协议)
    • 全局对象:hitalkOpenSDK
  • 2.初始化参数:调用init()接口加载初始化参数
    • 请在引入js后,尽早的加载init()接口,以得到完整的SDK功能。

参数说明:

参数名 类型 是否必须 说明 示例
gameId int 固定值,向平台申请获取 123
callback init()初始化完成后的回调,没有参数 hitalkOpenSDK.init(function(){},{gameId:key});

示例:

<head>
    <script type="text/javascript" src="//client.hhycdk.com/hitalksdk.min.js"></script>
</head>
<script >
		
        hitalkOpenSDK.init(function(res){//初始化sdk
					if(res.retCode!=0){
						console.log("初始化失败")
						return
					} 
					//获取功能开关状态
					var status=hitalkOpenSDK.switchStatus 
					
					//调用登录接口
					 hitalkOpenSDK.login(function(res){
							......
					 });
         },{gameId:key});  //向平台申请获得gameId


</script>

3. 登录


  • url:游戏方提供,前提需要在游戏页面引入平台js文件
  • 必须在init()初始化完成回调之后调用

接口调用示例:

//调用登录接口,在初始化完成之后调用,获取玩家openId等信息
         hitalkOpenSDK.login(function(res){
   			if(res.retCode===0){
   				console.log('fingerPlayer登录成功: res=>' + JSON.stringify(res));
   			}else{
   				console.log('fingerPlayer登录失败: res=>' + JSON.stringify(res));
   			}
        });

返回参数说明:

参数名 类型 是否必须 说明 示例
retCode String 状态码 0:成功;1;失败
retMsg String 描述 错误描述
data json 登录参数 返回玩家登录的参数,retCode==0时,data才会有参数

data参数:

参数名 类型 是否必须 说明 示例
openId String 玩家标识(32位) 2c01ccd8acab70ddb9d068925b155c7a
timestamp int 时间戳,单位:秒 1571911285349
snUserInfoJson String 额外参数 Json字符串格式
sign String 签名信息 (需要做登录签名验证) 签名规则:sign=md5(openId+timestamp+game_secret).toUpperCase();转大写。

4. 支付


4-1. 发起订单充值
  • 玩家在游戏内发起充值,调用平台用户支付窗口,游戏完成下单后调用sdk支付接口发起支付,订单状态以服务端支付回调通知为准。
  • 非必须字段,如果不需要,可以填默认值,但参数名必须要有。

参数说明:

参数名 类型 是否必须 说明
gameId int 平台给游戏的唯一标识
openId String(32) 玩家唯一标识
roleId String 角色Id
roleName String 角色名称
roleLevel int 角色等级
vipGrade int VIP等级
areaId String 区服id
areaName String 区服名称
productId String 商品编号
productName String 商品名称
productDescribe String 商品描述
amount int 购买金额(单位:分)
gameOrderNo String 游戏方支付订单号
timestamp String 时间戳,单位:秒
zoneKey String 专区标识,默认值: hitalkZone
extension String(64) 透传字段,支付回调时会原样返回,默认值:""
sign String 签名信息(参见签名算法)

示例:

    var params = {
        gameId: 111,
        openId: '8eae882ce1ba976ea53a273631a8234b',
        roleId: '12342',
        roleName: '见过玉堂',
        roleLevel: 58,
        vipGrade: 0,
        areaId: '99998',
        areaName: '测试服',
        productId: '80001',
        productName: '6元充值',
        productDescribe: '首充活动',
        amount: 600,
        gameOrderNo: '1909300024067NHXvrHq',
        extension: '',
        timestamp: '1548777111',
        zoneKey: 'hitalkZone',
        sign: '3eef5471b39cc970c7e49e34a5cb533c'
    }

    hitalkOpenSDK.gamePay(params, function(res) {
        console.log('支付:' + JSON.stringify(res))
    })
4-2. 支付回调通知
  • 玩家在使用sdk充值成功后,由发行平台服务端发起支付完成通知游戏方,游戏验证信息后,再给玩家发送道具。

请求地址:
游戏方提供url地址

请求方式:
POST

参数说明:

参数名 类型 说明
issueOrderNo String 平台订单号
gameOrderNo String 游戏方订单号
amount int 购买金额(单位:分)
extension String 透传字段
paymentStatus int 支付状态; 1:支付成功 2:支付失败
timestamp int 时间戳,单位秒
sign String 签名校验,规则参见签名算法

返回结果:

参数名 类型 是否必须 说明
code int 0:成功;1;失败
msg String 描述信息
{
	"code": 0,
	"msg": "success"
}

5. 签名算法


  1. 将非空参数值的参数按照参数名ASCII码从小到大排序(字典序a-z),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串A;
  2. sign = md5(A + game_secret).toUpperCase(); sign转大写; +为字符串连接符不参与签名;
  3. 特别注意以下重要规则:
    • 参数名ASCII码从小到大排序(字典序a-z);
    • 如果参数的值为空不参与签名;
    • 参数名区分大小写;
    • 验证签名时,传送的sign参数不参与签名,其余的参数都要参与签名,将生成的签名与该sign值作校验。

Java代码示例:

    /*
     * 拼接签名字符串规则1
     * 格式key1=value1&key2=value2…(key升序,sign和空value不参与签名,)
     * key按照参数名ASCII码从小到大排序(字典序,即升序)
     *
     * @Author: zibin.zhang
     */
    public static String sortJoinSign(final Map<String, Object> data) {
        Set<String> keySet = data.keySet();
        String[] keyArray = keySet.toArray(new String[keySet.size()]);
        Arrays.sort(keyArray);
        StringBuilder str = new StringBuilder();
        for (String key : keyArray) {
            Object val = data.get(key);
            if (val == null || val.equals("") || key.equals("sign")) {
                continue;
            }
            String strVal = val.toString().trim();
            str.append(key).append("=").append(strVal).append("&");
        }
        if (str.length() > 0) {
            str = str.deleteCharAt(str.length() - 1);
        }
        System.out.println("--------- 拼接的preStr:" + str.toString());
        return str.toString();
    }
	
	
	
	
    /**
     * 测试demo
     *@Author: zibin.zhang
     */
    @Test
    public void demoSign(){
        String sign="";//发行平台传入检验的签名字符串
        String game_secret="";//签名的密钥,向发行平台申请获取

        Map<String,Object> map=new HashMap<>();
        map .put("gameId",123);
        map .put("order",123);

       String str=SortJoinUtil.sortJoinSign(map)+game_secret;
       String mySign=DigestUtils.md5DigestAsHex(str.getBytes()).toUpperCase();
       if(mySign.equals(sign)){
           System.out.println("签名验证成功");
       }else{
           System.out.println("签名验证失败");
       }
    }

JavaScript 代码示例:

            // 排序拼凑字符串(key1=value1&key2=value2…)key升序、空value不参与签名
            sortJoinObj1: function (obj) {
                var str = '';
                var keys = Object.keys(obj).sort();
                for (var i = 0, n = keys.length, key, value; i < n; ++i) {
                    key = keys[i];
                    value = obj[key];
                    // 值为空时不参与签名
                    if (!value) {
                        continue;
                    }
                    str += key + '=' + value+ '&';
                }
                if (str.length > 0) {
                    str = str.deleteCharAt(str.length - 1);
                }
                return str;
            },

6. 玩家数据上报


6-1. 上报接口
  • 数据上报调用统一接口

hitalkOpenSDK.gameReport(action,params,callback);

参数说明:

参数名 类型 说明
action number 上报类型,1:注册/2:创角/3:登录/4:角色升级/5:vip上报
params json 上报的数据,以json格式传递,具体参数详见6-3
callback 上报结果返回,详见6-4

返回结果:

示例:

	//注册上报示例
	hitalkOpenSDK.gameReport(1, {"createTime": "1571996891"}, function (res) {
        console.log("注册数据上报:" + JSON.stringify(res));
    });


	//创角、登录、角色升级、vip上报示例
    var params = {
        "roleId": "85434522",
        "roleName": "天通苑",
        "roleLevel": 67,
        "vipGrade": 0,
        "areaId": "1",
        "areaName": "测试区服",
        "roleTurnup": 0,
        "createTime": "1571996891",
        "moneyNum": 0,
        "familyID": "",
        "familyName": ""
    }
	
    hitalkOpenSDK.gameReport(2, params, function (res) {
        console.log("创角数据上报:" + JSON.stringify(res));
    });
6-2. 上报类型说明
  1. 注册上报: 玩家进入游戏内,在创角之前上报。
    注册上报的数据与其他上报不同,可以参考示例中的案例

  2. 创角上报: 游戏内创建角色时上报。

  3. 登录上报: 玩家进入游戏时上报。

  4. 升级上报: 玩家游戏内角色等级发生变化上报。

  5. Vip上报: 玩家vip等级发生变化时上报,该上报暂时不用实现。

6-3. 上报数据:
  • 非必须字段,如果没有该数据,可以填默认值,参数名必须要有。

注册上报参数说明:

参数名 类型 是否必须 默认值 说明
createTime string 时间戳,以上报类型为准;注册时间;单位:秒

创角、登录、升级上报参数说明:

参数名 类型 是否必须 默认值 说明
areaId string 角色区服ID
areaName string 角色区服名称
roleId string 角色id
roleName string 角色名称
roleLevel number 角色等级
vipGrade number 角色VIP等级
createTime string 时间戳,以上报类型为准;创角/登录/升级时间;单位:秒
moneyNum number 游戏内虚拟货币数量
roleTurnup number 0 玩家转生数
familyID string '' 家族ID
familyName string '' 家族名称

7. 游戏内推广功能按钮


  • 游戏内显示的按钮;用于推广的相关接口,包括微信关注,分享,收藏等功能
7-1. 平台提供的功能

支持的功能类型:

参数名 类型 说明
shareMessage String 分享
showFocus String 关注微信公众号
verifyRealName String 实名认证
7-2. 获取功能开关状态
  • 功能描述:【是否显示功能按钮】获取该渠道是否需要显示这个功能按钮
  • 平台提供查询接口是否在游戏显示功能按钮及状态
  • 在游戏初始化时需要获取功能开关状态
    var switch=hitalkOpenSDK.switchStatus //获取功能开关状态
				
    //是否显示分享按钮
     if (switch.shareMessage) {
        // 显示分享按钮
    } else {
        // 隐藏游戏内分享按钮
    }

     /**
     * 是否显示关注公众号功能, 关注奖励只发放一次,已领取不显示
     * false:已关注(不显示),true:未关注(显示)
     */
    if (switch.showFocus) {
        // 显示关注微信公众号二维码按钮
    } else {
       // 隐藏游戏内关注微信公众号二维码按钮
    }
	
	//获取实名认证(防沉迷)信息
     if (switch.verifyRealName) {
        // 需要执行防沉迷
		var realNameStatus=switch.verifyRealName.status //0:成年,1:未成年,2:未填写
		var age=switch.verifyRealName.age	//年龄
		
    } else {
        // 不需要执行防沉迷
    }
	
	
7-3. 调用接口功能按钮
  • 功能描述:【执行功能】执行相关功能,实现该功能接口
  • 玩家点击功能按钮时,执行调用接口功能

调用接口:

hitalkOpenSDK.gameExtraAction(action, params, callback)

参数说明:

参数名 类型 说明
action String 接口类型 ,详见平台支持的功能类型
params json 非必须,调用接口传递的数据,以json格式传递
callback 接口结果返回

示例:

		//调用分享功能接口
        hitalkOpenSDK.gameExtraAction("shareMessage",{},function(res){
				//分享操作返回结果
        });
		
		
		//调用关注公众号接口
		hitalkOpenSDK.gameExtraAction("showFocus");
		
		
		//调用实名认证接口
		hitalkOpenSDK.gameExtraAction("verifyRealName",{},function(res){
				//实名认证操作返回结果
				var realNameStatus=res.status //0:成年,1:未成年,2:未填写
				var age=res.age	//年龄
        });

8. 角色查询接口

  • 游戏方提供根据玩家openId和区服ID查询玩家角色信息。

请求地址:
游戏方提供查询url地址

请求参数:
请求参数可以根据游戏方接口进行调整。

参数名 类型 是否必须 说明
openId String 玩家的唯一标识
areaId String 区服id;不传该参数,就是查询所有区服数据
timestamp String 时间戳,单位:秒
sign String 签名字符串

返回参数:

参数名 类型 说明
code int 0:查询成功;1:查询失败
msg String 错误描述
data array 返回数组格式,单个区服信息,以json对象返回

以下data内的参数必须为查询成功返回:

参数名 类型 说明
areaId String 区服Id
areaName String 区服名称
roleId String 角色id
roleName String 角色名称
roleLevel int 角色等级
attack int 角色战力值
vipGrade int Vip等级
createTime String 时间戳,单位秒
updatedTime String 最后一次角色升级时间

返回格式示例:

{
	"code": 0,
	"msg": "success",
	"data": [{
			"areaId": "区服id",
			"areaName": "测试区服",
			"roleId": "角色编号",
			"roleName": "角色名称",
			"roleLevel": "角色等级",
			"attack": "角色战力值",
			"createTime": "1570132149",
			"vipGrade": 1,
			"updatedTime": "1571132149"
		},
		{
			"areaId": "区服id",
			"areaName": "测试区服",
			"roleId": "角色编号",
			"roleName": "角色名称",
			"roleLevel": "角色等级",
			"attack": "角色战力值",
			"createTime": "1570132149",
			"vipGrade": 1,
			"updatedTime": "1571132149"
		}
	]
}