西瓜 SDK 为 CP 提供礼包码的配置管理和礼包码的兑换实现。
礼包码兑换活动实现有以下三种方式:
CP 可以根据自身的需求选择一种方式进行接入。
发起方 | ActivityServer |
接收方 | GameServer |
接口类型 | HTTP POST Content-Type:application/json; charset=UTF-8 |
字符集编码 | UTF-8 |
安全机制 | 签名 |
请求地址 | 游戏服务器提供url |
功能描述 | 通知游戏礼包码兑换成功发放道具 |
JSON格式的字符串:
参数 | 必须 | 类型 | 说明 |
data | 是 | String | 请求对象JSON对象(详见下表Data JSON 对象结构) |
type | 是 | String | 类型(填写字符串常量"GIFT") |
ts | 是 | String | 当前时间戳,秒级,如20150723150028对应2015/7/23 15:00:28 |
sign | 是 | String | 签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥: 1)传入参数key按字母排序。 2)按key1=value1&key2=value2&...来拼接签名源串,将值为空的参数和sign签名字段去掉,不加入签名源串,key和value不进行任何编码(如不进行URLEncoder)。 然后对最后生成的字符串进行HmacSHA1计算,得到签名串。 |
Data JSON 对象结构
参数 | 必须 | 类型 | 说明 |
roleId | 是 | String | 角色编号 |
serverId | 是 | String | 服务器编号 |
zoneId | 是 | String | 游戏区编号 |
channelId | 是 | String | 渠道编号 |
items | 是 | JSON数组 | 礼包内容 e.g. [{"id":"123", "num":10}] |
返回结果为JSON格式的字符串,分别有如下几个字段:
字段 | 必须 | 类型 | 说明 |
code | 是 | String | 返回码,参见错误码章节 |
msg | 是 | String | 接口调用信息提示 |
URL:
http://activity.xgsdk.com:8040/mock-notify-game
POST Body:
{
"data": {
"channelId": "jinshan",
"items": [{
"id": "15-1-1-1",
"num": 1
}],
"roleId": "1002",
"serverId": "1",
"zoneId": "1"
},
"sign": "cb11ceceef0c109dd87fca11f10fb6edb8690a75",
"ts": "20160523140838",
"type": "GIFT"
}
{"code":0,"msg":"兑换成功"}
发起方 | ActivityServer |
接收方 | GameServer |
接口类型 | HTTP GET Accept:application/json; charset=UTF-8 |
字符集编码 | UTF-8 |
安全机制 | 签名,签名算法采用HmacSHA1 采用XgsdkServerKey为游戏服务端密钥, 对西瓜app ID进行HmacSHA1计算得到签名串, 游戏服务器在接受到请求后对签名进行校验,通过后返回结果 |
请求地址 | 游戏服务器提供url |
功能描述 | 礼包道具列表, 用于配置礼包内容 |
返回结果为JSON格式的字符串:
字段 | 必须 | 类型 | 说明 |
items | 是 | JSON对象数组 | 道具列表 |
URL:
http://activity.xgsdk.com:8040/push/gift/items-mock?sign=xxxxx
{ "items": [{ "id": "1", "name": "道具1" },{ "id": "2", "name": "道具2" }] }
发起方 | ActivityServer |
接收方 | GameServer |
接口类型 | HTTP GET Accept:application/json; charset=UTF-8 |
安全机制 | 签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥, 对西瓜app ID进行HmacSHA1计算得到签名串, 游戏服务器在接受到请求后对签名进行校验,通过后返回结果 |
字符集编码 | UTF-8 |
请求地址 | 游戏服务器提供url |
功能描述 | 获取游戏区服列表, 用于配置精准群体 -> 区服信息 |
返回结果为JSON格式的字符串:
字段 | 必须 | 类型 | 说明 |
items | 是 | JSON对象数组 | 道具列表 |
URL: http://activity.xgsdk.com:8040/push/gift/zones-mock?sign=xxxxx
{ "items": [{ "zoneId": "1", "zoneName":"区1", "serverId":"1", "serverName":"服1" },{ "zoneId": "2", "zoneName":"区2", "serverId":"2", "serverName":"服2" }] }
发起方 | ActivityServer |
接收方 | GameServer |
接口类型 | HTTP GET Accept:application/json; charset=UTF-8 |
字符集编码 | UTF-8 |
安全机制 | 签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥, 对西瓜app ID进行HmacSHA1计算得到签名串, 游戏服务器在接受到请求后对签名进行校验,通过后返回结果 |
请求地址 | 游戏服务器提供url |
功能描述 | 查询关卡信息,用于配置精准群体 -> 关卡信息 |
返回结果为JSON格式的字符串:
字段 | 必须 | 类型 | 说明 |
items | 是 | JSON对象数组 | 道具列表 |
URL: http://www.gameserver.com/mission?sign=xxxxx
{ "items": [{ "id": "1", "name": "关卡1" },{ "id": "2", "name": "关卡2" }] }
发起方 | ActivityServer |
接收方 | GameServer |
接口类型 | HTTP GET Accept:application/json; charset=UTF-8 |
字符集编码 | UTF-8 |
请求地址 | 游戏服务器提供url |
功能描述 | 查询用户信息,西瓜在收到用户兑换请求时根据角色ID向游戏服务器查询用户信息, 包括用户等级,所在区服,当前关卡等判断用户是否满足兑换条件(游戏服务器只需返回用户信息, 兑换判断逻辑由XG完成) |
参数 | 必须 | 类型 | 说明 |
roleId | 是 | String | 角色编号 |
serverId | 是 | String | 服务器编号 |
zoneId | 是 | String | 区ID |
missionId | 是 | String | 关卡ID(提供给游戏端来鉴定该用户是否通过此关卡) | sign | 是 | String | 签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥: 1)传入参数key按字母排序。 2)按key1=value1&key2=value2&...来拼接签名源串,将值为空的参数和sign签名字段去掉,不加入签名源串,key和value不进行任何编码(如不进行URLEncoder)。 然后对最后生成的字符串进行HmacSHA1计算,得到签名串。 |
返回结果为JSON格式的字符串:
字段 | 必须 | 类型 | 说明 |
code | 是 | String | 错误码 |
msg | 是 | String | 错误信息 |
item | 是 | JSON对象 | 用户信息 |
{ "code":0, "msg":"成功", "item": { "roleId": "1", "roleName":"小苹果", "zoneId":"1", "zoneName":"区1", "serverId":"1", "serverName":"服1", "missionId":"24", "missionName":"关卡24", "level":20, "isMissionPassed": true, "uid": "123456" } }
参数 | 说明 |
uid | 玩家uid |
roleId | 玩家角色ID |
zoneId | 游戏区ID |
serverId | 游戏服ID |
giftCode | 礼包码 |
参数 | 说明 | 必须 |
---|---|---|
response | JSON 格式,如:{"code":0,"msg":"兑换成功"}, code: 0为成功,其它为失败 | Y |
CP 需先将以上所有接口接入完成,然后在西瓜Web控制台中填写对应的接口配置,详细配置步骤如下:
选择“运营工具”->“礼包码”->“URL配置”
“礼包码管理”->“创建活动”
填写“活动名称”,选择“目标人群”,进行下一步
进行活动内容配置,进行下一步
进行自定义错误消息配置
以下错误码提示语为默认提示语,考虑到游戏的类型以及风格的差异,西瓜提供了自定义提示语功能用来满足不同游戏的需求(详情请前往西瓜Web控制台进行配置:“运营工具”->“礼包码”->“错误消息配置”)
错误码值 | 错误码提示语 |
---|---|
0 | 兑换成功 |
1000 | 礼包码无效,没有相应活动 |
1001 | 用户不存在 |
1002 | 活动未开始 |
1003 | 活动过期 |
1004 | 礼包码只能在指定区服使用 |
1005 | 对不起,该礼包码您已使用 |
1006 | 您领取次数已超过限制 |
1007 | 对不起,您在该活动中使用的礼包码数量已达上限 |
1008 | 礼包码在同一互斥组 |
1009 | 没有通过礼包码要求的关卡 |
1010 | 等级低于领取礼包最小等级要求 |
1011 | 等级高于领取礼包最大等级要求 |
1012 | 礼包无法在该渠道使用 |
2000 | 游戏服务器异常 |
2001 | 游戏服务器返回发放失败 |
2002 | 获取用户信息失败 |
3000 | 兑换服务器异常 |
3001 | 系统错误 |
3002 | 发生未知网络错误 |