关闭目录

指尖发行平台对接文档

版本 修改人 修改时间 修改内容
v1.0 zibin.zhang 2019/10/25 新建对接文档
v1.1 zibin.zhang 2019/12/20 修改获取功能开关状态方式,改用switchStatus字段获取
v1.2 zibin.zhang 2019/12/30 功能按钮新增实名认证功能
v1.3 zibin.zhang 2020/02/27 支付签名规则zoneKey字段不需要参与签名,已对接的游戏规则不变
v1.4 zibin.zhang 2020/03/19 新增小游戏接口
v1.5 zibin.zhang 2020/03/30 1.上报数据新增玩家战力字段 2.新增日语渠道文档

一、客户端API

1. 接入步骤说明


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

2. 初始化


  • 1 引入js文件

    • 1.1 H5引入地址:
      • 正式用地址://client.hhycdk.com/hitalksdk.js
      • 测试用地址://client-dev.hhycdk.com/hitalksdk.js
        尽量不要添加http,以便自适应http和https协议
    • 1.2 小游戏则通过本地引入:xyxConfig.js和hitalkSdkXyx.js
      注意:xyxConfig.js必须在hitalkSdkXyx.js文件之前引入
  • 2.初始化参数:调用init()接口加载初始化参数

    • 请在引入js后,尽早的加载init()接口,以得到完整的SDK功能。
    • 全局对象:hitalkOpenSDK

参数说明:

参数名 类型 是否必须 说明 示例
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. 发起订单充值

  • 玩家在游戏内发起充值,调用平台用户支付窗口,游戏完成下单后调用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 时间戳,单位:秒
extension String(64) 透传字段,支付回调时会原样返回,默认值:"",需要Base64 编码
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',
        sign: '3eef5471b39cc970c7e49e34a5cb533c'
    }

    hitalkOpenSDK.gamePay(params, function(res) {
        console.log('支付:' + JSON.stringify(res))
    })

5. 玩家数据上报


5-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));
    });
5-2. 上报类型说明
  1. 注册上报: 玩家进入游戏内,在创角之前上报。
    注册上报的数据与其他上报不同,可以参考示例中的案例

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

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

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

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

5-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 玩家转生数
rolePower number 0 玩家战力
familyID string '' 家族ID
familyName string '' 家族名称

6. 游戏内推广功能按钮


  • 游戏内显示的按钮;用于推广的相关接口,包括微信关注,分享,收藏等功能
6-1. 平台支持的功能类型
参数名 类型 说明
shareMessage json 分享
showFocus json 关注微信公众号
verifyRealName json 实名认证
collection json 收藏
gamePay json 是否开启支付功能
6-2. 获取功能开关状态
  • 功能描述:【是否显示功能按钮】获取该渠道是否需要显示这个功能按钮
  • 平台提供查询接口是否在游戏显示功能按钮及状态
  • 在游戏初始化时需要获取功能开关状态
    var switch=hitalkOpenSDK.switchStatus //获取功能开关状态
				
    //是否显示分享按钮
     if (switch.shareMessage) {
        // 显示分享按钮
		
		//获取分享人Id,如果shareUID字段不存在则不是分享链接进入的玩家
		let shareUID=switch.shareMessage.shareUID
		
    } else {
        // 隐藏游戏内分享按钮
    }


     /**
     * 是否显示关注公众号功能, 关注奖励只发放一次,已领取不显示
     * false:已关注(不显示),true:未关注(显示)
     */
    if (switch.showFocus) {
        // 显示关注微信公众号二维码按钮
    } else {
       // 隐藏游戏内关注微信公众号二维码按钮
    }
	
	
	//获取实名认证(防沉迷)信息
     if (switch.verifyRealName) {
        // 需要执行防沉迷
		var realNameStatus=switch.verifyRealName.status //0:成年,1:未成年,2:未填写
		var age=switch.verifyRealName.age	//年龄
    } else {
        // 不需要执行防沉迷
    }


	//是否显示收藏按钮
     if (switch.collection) {
        // 显示收藏按钮
    } else {
        // 隐藏游戏内收藏按钮
    }
	
	
	//是否是否需要支付功能
     if (switch.gamePay) {
        // 需要支付功能
    } else {
        // 不需要支付功能
    }
	
	
6-3. 实现功能按钮接口
  • 功能描述:【执行功能】执行相关功能,实现该功能接口
  • 玩家点击功能按钮时,执行调用接口功能

调用接口:

hitalkOpenSDK.gameExtraAction(action, params, callback)

参数说明:

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

callback回调参数:

参数名 类型 说明
retCode number 0:成功,-1:失败
retMsg String 错误信息

示例:

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

		//调用收藏功能接口
        hitalkOpenSDK.gameExtraAction("collection",{},function(res){
				//收藏操作返回结果
        });

二、服务端API

1. 支付回调通知

  • 玩家在使用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"
}

2. 角色查询接口

  • 游戏方提供根据玩家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"
		}
	]
}

3. 签名算法


  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;
            },

三、QQ小游戏服务端接口

1. 查询代币余额

1-1. 请求地址

向平台申请

1-2. 请求方式

POST

Content-Type:application/json

1-3. 请求参数

参数名 类型 描述 是否必须
openid string 用户标识 必须
timestamp number 时间戳 ,单位:秒 必须
sign string 以上两个参数的签名,规则参考签名算法 必须

1-4. 响应结果

//成功返回结果,code=0
{
    code: 0,
}

//失败返回结果,code=1
{
    code: 1,
    msg:"错误描述"
}

2. 内容安全

暂时只需要实现文字内容校验

2-1. 请求地址

向平台申请

2-2. 请求方式

POST

Content-Type:application/json

2-3. 请求参数

参数名称 类型 描述 是否必须
content string 要检测的文本内容,长度不超过 500KB 必须

2-4. 响应结果

//成功返回结果,code=0
{
    code: 0,
}

//失败返回结果,code=1
{
    code: 1,
    msg:"错误描述"
}

3. 红包提现

非必须接口,代理的红包提现功能接口,和平台确认后再进行对接

3-1. 请求地址

向平台申请

3-2. 请求方式

POST

Content-Type: application/json

3-3. 请求参数

参数名 类型 描述 是否必须
openid string 用户标识 必须
amt number 红包金额, 单位:分 必须
remark string 游戏自定义的透传参数 必须
sign string 以上三个参数的签名,规则参考签名算法 必须

3-4. 响应结果

参数名 类型 说明
code number 0:成功,1:失败
msg String 错误信息
//成功返回结果,code=0
{
    code: 0,
}

//失败返回结果,code=1
{
    code: 1,
    msg:"错误描述"
}

四、日语渠道(北京艾恩游)接口

1. 客户端API

1-1. 区分版本

从url入口地址获取版本标识(snPlatform)字段的值区分版本

版本名称 snPlatform 版本区别
官方版本(一般) normal 正常功能版本
官方版本(特殊) special 与一般版本只是金额单位不同
平台M版本 mm 在一般版本的基础上,按平台M版本修改需求进行修改,详见渠道需求文档
平台G版本 gg 在一般版本的基础上,按平台G版本修改需求进行修改,详见渠道需求文档

注:一般与特殊版本,玩家的数据是互通的,但是显示的金额单位不同; 平台M和平台G版本的玩家数据都是不互通的。

1-2. 扩展功能API

平台支持的功能类型:

参数名 类型 说明
contentCheck json 禁用文字检查(游戏内玩家输入文字时需做检查)
ig_textdata_create json 建立讯息(讯息处理功能)
ig_textdata_read json 读取讯息(讯息处理功能)
ig_textdata_update json 更新讯息(讯息处理功能)

各版本调用逻辑:
官方一般&特殊版本:
1.使用渠道方禁用字库,含有禁用文字时,提示含有禁用文字不让输出.调用contentCheck函数。

平台M版本:
1.先判断是否含有敏感文字(调用contentCheck函数) ,文字限制在12字节以内。
2.调用讯息处理函数ig_textdata_create 函数建立讯息获取textdata_id并保持到游戏DB。
3.显示信息时,用2获取到的textdata_id,通过ig_textdata_read 函数获取最新信息去显示。
4.更新信息时,使用2获取到的textdata_id和更新内容,调用ig_textdata_update 函数更新信息。
更新频率:每次修改时都需要更新

平台G版本:
1.暂时没要求调用contentCheck函数。
2.创建角色或家族名时,通过ig_textdata_create函数建立讯息获取textdata_id并保持到游戏DB。
3.第2次以后进入游戏时(既重新登录时),用2获取textdata_id,通过ig_textdata_read函数读取最新信息,并在游戏内显示。
更新频率:不需要每次修改时更新,在登录时去更新信息;对于出现在排名或家族里的玩家名字,如果玩家没登录的话需考虑定期刷新玩家的最新昵称信息(另外根据需求和渠道协商)

1-2-1. 禁用文字检查


使用渠道方禁用字库,含有禁用文字时,提示含有禁用文字不让输出

使用场景:

  • 游戏内输入文字等操作时,如聊天、角色名称、家族名、家族公告等等

调用接口:

hitalkOpenSDK.gameExtraAction("contentCheck", params, callback)

请求参数说明:

参数名 类型 说明
contentCheck String 接口类型 ,详见平台支持的功能类型
params String 检查的文字内容
callback json 接口结果返回

callback回调参数:

参数名 类型 说明
retCode number 接口请求成功码; 0:成功,-1:失败
retMsg String 错误信息
data boolean 校验内容结果

1-2-2. 建立讯息


使用场景:

  • 建立讯息,获取讯息id

调用接口:

hitalkOpenSDK.gameExtraAction("ig_textdata_create", params, callback)

请求参数说明:

参数名 类型 说明
ig_textdata_create String 接口类型 ,详见平台支持的功能类型
params json 保存讯息
callback json 接口结果返回

params参数说明:

参数名 类型 说明
textdata String 信息内容

callback回调参数:
成功回传

参数名 类型 说明
textdata_id number 讯息id
textdata String 信息内容

失败回传

参数名 类型 说明
error number 错误码

1-2-3. 读取讯息


使用场景:

  • 根据讯息id获取最新显示信息

调用接口:

hitalkOpenSDK.gameExtraAction("ig_textdata_read", params, callback)

请求参数说明:

参数名 类型 说明
ig_textdata_read String 接口类型 ,详见平台支持的功能类型
params json 传递数据
callback json 接口结果返回

params参数说明:

参数名 类型 说明
textdata_id number 讯息id

callback回调参数:
成功回传

参数名 类型 说明
textdata_id number 讯息id
textdata String 信息内容

失败回传

参数名 类型 说明
error number 错误码

1-2-4. 更新讯息


使用场景:

  • 更新讯息内容时调用

调用接口:

hitalkOpenSDK.gameExtraAction("ig_textdata_update", params, callback)

请求参数说明:

参数名 类型 说明
ig_textdata_update String 接口类型 ,详见平台支持的功能类型
params json 传递数据
callback json 接口结果返回

params参数说明:

参数名 类型 说明
textdata_id number 讯息id
textdata String 更新信息内容

callback回调参数:
成功回传

参数名 类型 说明
textdata_id number 讯息id
textdata String 讯息内容

失败回传

参数名 类型 说明
error number 错误码