# 小游戏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}`);
# 回调返回说明
返回类型:字符串
- 成功返回小写字母:"ok"
- 失败返回:"失败原因"
# 回调接口其他注意事项
- 游戏接入时,必须验证订单信息跟游戏方本地下订单信息进行匹配,防止中途被人串改
- sign值必须要验证,
gamePayKey
必须由服务端保存,防止泄漏 - 订单有可能会出现多次同步,请做好幂等性,并返回“ok”
- 同步失败情况,我方会根据定义好的规则进行多次尝试
# 上报角色数据(必接)
# 示例
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();
},
});