# 小游戏SDK 对接文档

# 注意

此SDK对接文档,标注必接的接口请在第一次接入时则必须接入,其余未标注说明必接的接口,可视运营情况及相关说明,再进行对接。

# 获取对接物料

开始对接时,我方会提供SDK文件和如下4个参数,如未获取,请联系我方运营或技术获取

参数字段 参数说明 示例
unionPacketCode 对接的唯一包ID 10000
gameId 游戏ID 10000
gameKey 登录加密Key 1111
gamePayKey 支付加密Key 1111

# 引入SDK

import UnionSDKUtils from 'union-channel.min.js';

const UnionSDK = new UnionSDKUtils();

后续调用其他接口使用UnionSDK对象进行调用即可

# 接口调用说明

接口调用都以下面格式进行调用:

/**
 * 方法调用示例
 * {string} apiName 方法名
 * {object|any} data 调用参数
 * {function} success 成功回调
 * {function} fail 失败回调
 **/
UnionSDK[apiName]({data, success, fail}) 

如调用支付接口:

UnionSDK.purchase({
    data: {
        count: 1,
        ...
    },
    success: ({code, msg, data}) => {
        // code 状态码 200-成功
        // msg 状态说明
        // data 返回数据
    },
    fail: ({code, msg}) => {
        // code 状态码
        // msg 状态说明
    }
})

# 初始化接口(必接)

# 初始化示例

UnionSDK.init({
    success: ({code, msg, data}) => {
        const {isbn, privacyUrl, serviceUrl, operName, softNo, softName, publishName, authNo, unionPacketCode} = data;
        // do something
    }, fail: ({msg}) => {
        // do something
        console.log(msg);
    }
});

# 登录接口(必接)

需要在初始化接口成功后调用

# 登录示例

UnionSDK.login({
    success: ({code, msg, data}) => {
        // 登录成功
        const {auth, cid, gameId, isbn, openId, privacyUrl, serviceUrl, sign, signVer, tags, ts} = data;
    }, fail: ({msg}) => {
        // 登录失败
        console.log(msg);
    }
});

# 登录返回字段说明

参数 类型 例子 备注
openId string u-10000-579b2fe6d188e1a82dcb06cfff96ebf 用户唯一标识
gameId number 100000 游戏ID
ts string 1701931432675 毫秒级时间戳
signVer number 1 签名版本,当前默认1
sign string 642029cf0c290e38a95ef59d232b338f 登录签名
cid string 10000 渠道标识
tags string tags 用户标签
pcode String pcode 渠道包标识

# 服务端登录验证(必接)

验证登录接口返回后的sign满足以下字段签名,是则验证通过

sign = md5(`${openId}|${gameId}|${ts}|${gameKey}`)

# 判断是否开启支付入口(必接)

不管安卓还是iOS平台均可用使用此接口进行判断

UnionSDK.isAvailable({
    data: {
        apiName: "purcahse",
        props: {
            roleId: "112112",
            roleName: "3333",
            roleLevel: 12
        }
    },
    success: ({code}) => {
        // 支持支付,可打开所有支付入口
    },
    fail: () => {
        // 不支持支付,游戏需要对支付入口进行屏蔽,包括支付活动入口
    }
});

# 支付接口(必接)

需要在登录成功后调用

# 支付示例

UnionSDK.purchase({
    data: {
        openId: "u12317272",
        gameId: 100000,
        roleId: "147176212",
        roleName: "齐天大圣",
        roleLevel: "10",
        roleVipLevel: "2",
        roleFight: "12612",
        serverId: "1001",
        serverName: "1001服",
        gameOrderCode: "16253651265x17631221231212",
        gameOrderCustomInfo: "16253651265x17631221231212",
        gameProductCode: "1001",
        gameProductName: "100元宝",
        gameProductPrice: 100,
        ts: "1699349488262",
        signVer: 1,
        sign: "c9889204a2860cfd6938fec8a51c78ec"
    },
    success: ({code, msg, data}) => {
        // 支付成功
    },
    fail: ({msg}) => {
        // 支付失败|取消支付
        console.log(msg);
    }
});

# 支付请求参数字段说明

参数 类型 例子 备注
openId string u-10000-579b2fe6d188e1a82dcb06cfff96ebf 用户唯一标识
gameId number 100000 游戏ID
ts string 1701931432675 毫秒级时间戳
signVer number 1 签名版本,当前默认1
sign string 642029cf0c290e38a95ef59d232b338f 支付下单签名,看下面签名规则
roleId string 147176212 角色ID
roleName string 齐天大圣 角色名称
roleLevel string 10 角色等级
roleVipLevel string 2 角色VIP等级
roleFight string 12612 角色战力
serverId string 1001 区服ID
serverName string 1001服 区服名称
gameOrderCode string 16253651265x17631212 游戏订单号
gameOrderCustomInfo string 16253651265x17631212 订单自定义字符串,支付回调时会原样返回
gameProductCode string 1001 游戏商品计费点
gameProductName string 100元宝 游戏商品名称
gameProductPrice number 100 支付金额,单位(分)

# 服务端支付签名及回调接入(必接)

# 支付调起签名字段

// gamePayKey,支付加密Key 参考2.1对接物料获取 
sign = md5(`${gameId}|${openId}|${roleId}|${serverId}|${gameOrderCode}|${gameProductCode}|${gameProductPrice}|${ts}|${gamePayKey}`);

# 支付回调接口

游戏方需要根据下面文档对接完成后提供URL地址给到我方进行配置,游戏在正常支付完成后,游戏方会收到我方接口调用。

# 通知方式

HTTP POST

# 通知格式

application/json

# 请求参数说明

本协议中所有字符串使用UTF8编码

参数 类型 例子 备注
openId string u-10000-579b2fe6d188e1a82dcb06cfff96ebf 用户唯一标识
gameId number 100000 游戏ID
ts string 1701931432675 毫秒级时间戳
signVer number 1 签名版本,当前默认1
sign string 642029cf0c290e38a95ef59d232b338f 支付下单签名,看下面签名规则
roleId string 147176212 角色ID
serverId string 1001 区服ID
orderCode string i-10000010000-20231109150147645-745gm 我方订单号
gameOrderCode string 16253651265x17631212 游戏方调起支付时传入的游戏订单号
gameOrderCustomInfo string 16253651265x17631212 游戏方调起支付时传入的游戏自定义参数
gameProductCode string 1001 游戏商品计费点
gameProductPrice number 100 支付金额,单位(分)
isSandBox number 0 是否测试订单,1-是测试订单,0-否
discountPrice number 0 优惠金额,单位(分)

# 回调签名字段说明

sign=md5(`${gameId}|${gameOrderCode}|${orderCode}|${gameProductPrice}|${gameProductCode}|${serverId}|${roleId}|${openId}|${ts}|${gamePayKey}`);

# 回调返回说明

返回类型:字符串

  1. 成功返回小写字母:"ok"
  2. 失败返回:"失败原因"

# 回调接口其他注意事项

  1. 游戏接入时,必须验证订单信息跟游戏方本地下订单信息进行匹配,防止中途被人串改
  2. sign值必须要验证,gamePayKey必须由服务端保存,防止泄漏
  3. 订单有可能会出现多次同步,请做好幂等性,并返回“ok”
  4. 同步失败情况,我方会根据定义好的规则进行多次尝试

# 上报角色数据(必接)

# 示例

UnionSDK.report({
    data: {
        type: 2,
        openId: "u-128312",
        gameId: 100000,
        roleId: "147176212",
        roleName: "齐天大圣",
        roleLevel: "10",
        roleVipLevel: "2",
        roleFight: "12612",
        serverId: "1001",
        serverName: "1001服",
        ts: "1699349488262",
        signVer: 1,
        sign: "7cf7446ea63561f55f061be48fb6442d"
    },
    success: ({code, msg, data}) => {
        // code 状态码 200-成功
        // msg 状态说明
        // data 返回数据
    },
    fail: ({msg}) => {
        // 失败
    }
});

# 参数字段说明

参数 类型 例子 备注
type int 1 角色上报类型,1-选服,2-创角,3-登录,4-升级,5-退出
openId String u-10000-579b2fe6d188e1a82dcb06cfff96ebf 用户唯一标识
gameId int 100000 游戏ID
ts String 1701931432675 毫秒级时间戳
signVer int 1 签名版本,当前默认1
sign String 642029cf0c290e38a95ef59d232b338f 支付下单签名,看下面签名规则
roleId String 147176212 角色ID
roleName String 齐天大圣 角色名称
roleLevel String 10 角色等级
roleVipLevel String 2 角色VIP等级
roleFight String 12612 角色战力
serverId String 1001 区服ID
serverName String 1001服 区服名称

# 服务端签名

sign = md5(`${gameId}|${openId}|${roleId}|${serverId}|${ts}|${gameKey}`);

# 判断接口是否可用(必接)

除初始化、登录、支付、上报接口外,其余的接口调用需要调用此接口进行判断,包括功能开关是否显示的判断也可以根据此接口返回判断

// 可传入 
// init,login,purchase,report,initShare,share,reportEvent,checkMessage,jumpService
// rewardVideo,isBindPhone,bindPhone,live,moreGame
UnionSDK.isAvailable({
    data: {
        apiName: "share",
    },
    success: ({code}) => {
        // 支持
    },
    fail: () => {
        // 不支持,do something
    }
});

# 言论敏感词检测接口(必接)

UnionSDK.isAvailable({
    data: {
        apiName: "checkMessage",
    },
    success: ({code}) => {
        UnionSDK.checkMessage({
            data: {
                content: "加微N181283"
            },
            success: ({code, data}) => {
                // 字符通过验证或过滤打星号等,使用data替换原字符
            },
            fail: () => {
                // 字符检测不通过
            }
        });
    },
});

# Vip接口(需要事先和我们运营方沟通)

参数和上报的保持一致 需要在每次进入游戏/升级/支付之后检查调用

UnionSDK.vip({
    data: {
        type: 2,
        openId: "u-128312",
        gameId: 100000,
        roleId: "147176212",
        roleName: "齐天大圣",
        roleLevel: "10",
        roleVipLevel: "2",
        roleFight: "12612",
        serverId: "1001",
        serverName: "1001服",
        ts: "1699349488262",
        roleServerDay: 3,
        signVer: 1,
        sign: "7cf7446ea63561f55f061be48fb6442d"
    },
    success: ({code, msg, data}) => {
        // code 状态码 200-成功
        // msg 状态说明
        // data 返回数据 看参数返回字段说明
    },
    fail: ({msg}) => {
        // 失败
    }
});

# 参数返回字段说明

参数 类型 例子 备注
vipShowType int 1 0 调用 SDK 方法 1 游戏内自定义 UI
vipShowStatus String 1 0 隐藏 1 显示
vipContent {} VIP返回需要显示的内容对象
vipContent.content String 内容 内容
vipContent.qrCodeUrl int 二维码地址 二维码地址
vipContent.title String 标题 标题
vipContent.custom String {} 附加参数方便扩展使用 json格式

# 消息订阅接口(微信小游戏专属)

tmplId 为我方运营提供

具体调用场景我方运营提供需求文档

tmplId 为 array 我方运营提供

UnionSDK.subscribeMessage({
    data: {
        openId: "u-128312",
        gameId: 100000,
        roleId: "147176212",
        roleName: "齐天大圣",
        roleLevel: "10",
        roleVipLevel: "2",
        roleFight: "12612",
        serverId: "1001",
        serverName: "1001服",
        ts: "1699349488262",
        roleServerDay: 3,
        signVer: 1,
        tmplId:[]
    },
    success: ({code, msg, data}) => {
       // 如果达到条件 需要请求我方后端发送订阅消息接口
  		 // 不做到SDK是为了方便我方后端对其他小游戏类型进行扩展
    },
    fail: ({msg}) => {
        // 失败
    }
});

# 创建游戏圈按钮(微信小游戏专属)

具体调用场景我方运营提供需求文档

不需要关注成功失败的回调

详情说明可参考 :https://developers.weixin.qq.com/minigame/dev/api/open-api/game-club/wx.createGameClubButton.html

无需关注点击时间 用户点击微信会处理跳转游戏圈

UnionSDK.createGameClubButton({
    data: {
      icon: icon,
      style: {
        backgroundColor: 'backgroundColor',
        borderColor: 'borderColor',
        borderRadius: 0,
        borderWidth: 0,
        color: 'color',
        fontSize: 0,
        height: 0,
        left: 0,
        lineHeight: 0,
        textAlign: textAlign,
        top: 0,
        width: 0,
      },
      type: type,
    },
    success: ({code, msg, data}) => {
      
    },
    fail: ({msg}) => {
        
    }
});

# 获取游戏圈数据(微信小游戏专属)

具体调用场景我方运营提供需求文档

不需要关注成功失败的回调

详情说明可参考 :https://developers.weixin.qq.com/minigame/dev/api/open-api/game-club/wx.getGameClubData.html

无需关注点击时间 用户点击微信会处理跳转游戏圈

//type
//4	当天(自然日)点赞贴子数	无需传入	
//5	当天(自然日)评论贴子数
UnionSDK.getGameClubData({
    data: [
      {
       type:1
      }
    ],
    success: ({code, msg, data}) => {
      //data 返回数据
      //同type返回的value含义不同,见type表格说明
			//https://developers.weixin.qq.com/minigame/dev/api/open-api/game-club/wx.getGameClubData.html
      //   {
      //     watermark: {
      //       timestamp: 1703143844,
      //       appid: "wxc2d4852c2cca9e95"
      //     },
      //     dataList: [{
      //       dataType: {
      //         type: 1
      //       },
      //       value: 0
      //     }]
      // }
      
    },
    fail: ({msg}) => {
        
    }
});

# 设置分享参数(必接)

UnionSDK.isAvailable({
    data: {
        apiName: "initShare",
    },
    success: ({code}) => {
        UnionSDK.initShare({
            data: {
                title: "分享标题",
                content: "分享内容",
                icon: "默认图标",
                ext: "uid=24993", //多个参数使用&分割,如: uid=24993&activeId=8381
            },
            success: () => {
                // 分享成功,做发放奖励操作
            }
        });
    }
});

# 分享接口(必接)

UnionSDK.isAvailable({
    data: {
        apiName: "share",
    },
    success: ({code}) => {
        UnionSDK.share({
            data: {
                title: "分享标题",
                content: "分享内容",
                icon: "默认图标",
                ext: "uid=24993", //多个参数使用&分割,如: uid=24993&activeId=8381
            },
            success: () => {
                // 分享成功,做发放奖励操作
            }
        });
    }
});

# 自定义事件上报接口

# 示例

UnionSDK.isAvailable({
    data: {
        apiName: "reportEvent",
    },
    success: ({code}) => {
        UnionSDK.reportEvent({
            data: {
                eventName: "game-res-loading-start"
            },
        });
    },
});

# eventName可传值

事件名称 eventName说明
game-res-loading-start 游戏资源开始加载
game-res-loading-end 游戏资源加载完成
server-res-loading-start 选服后资源开始加载
server-res-loading-end 选服后资源加载完成

# 跳转客服接口

UnionSDK.isAvailable({
    data: {
        apiName: "jumpService",
    },
    success: ({code}) => {
        UnionSDK.jumpService();
    },
});