运营活动-兑换礼包码

1. 文档概述

西瓜 SDK 为 CP 提供礼包码的配置管理和礼包码的兑换实现。
礼包码兑换活动实现有以下三种方式:

  • 游戏自行制作页面
  • 西瓜定制HTML5页面 + 西瓜提供HTML5页面加载组件
  • 西瓜定制HTML5页面(URL)+ 游戏实现HTML5页面加载组件

CP 可以根据自身的需求选择一种方式进行接入。

1.1 文档结构

  1. 文档概述
  2. 服务端接口
  3. 客户端接口
  4. 礼包码活动配置
  5. 错误码列表

2. 服务端接口

2.1 兑换礼包码通知接口

2.1.1 功能

发起方ActivityServer
接收方GameServer
接口类型HTTP POST Content-Type:application/json; charset=UTF-8
字符集编码UTF-8
安全机制签名
请求地址游戏服务器提供url
功能描述通知游戏礼包码兑换成功发放道具

2.1.2 输入

JSON格式的字符串:

参数必须类型说明
dataString请求对象JSON对象(详见下表Data JSON 对象结构)
typeString类型(填写字符串常量"GIFT")
tsString当前时间戳,秒级,如20150723150028对应2015/7/23 15:00:28
signString签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥: 1)传入参数key按字母排序。 2)按key1=value1&key2=value2&...来拼接签名源串,将值为空的参数和sign签名字段去掉,不加入签名源串,key和value不进行任何编码(如不进行URLEncoder)。 然后对最后生成的字符串进行HmacSHA1计算,得到签名串。

Data JSON 对象结构

参数必须类型说明
roleIdString角色编号
serverIdString服务器编号
zoneIdString游戏区编号
channelIdString渠道编号
itemsJSON数组礼包内容 e.g. [{"id":"123", "num":10}]

2.1.3 输出

返回结果为JSON格式的字符串,分别有如下几个字段:

字段必须类型说明
codeString返回码,参见错误码章节
msgString接口调用信息提示

2.1.4 请求样例

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" }

2.1.5 返回值样例

{"code":0,"msg":"兑换成功"}

2.2 查询礼包道具

2.2.1 功能

发起方ActivityServer
接收方GameServer
接口类型HTTP GET Accept:application/json; charset=UTF-8
字符集编码UTF-8
安全机制 签名,签名算法采用HmacSHA1 采用XgsdkServerKey为游戏服务端密钥, 对西瓜app ID进行HmacSHA1计算得到签名串, 游戏服务器在接受到请求后对签名进行校验,通过后返回结果
请求地址游戏服务器提供url
功能描述礼包道具列表, 用于配置礼包内容

2.2.2 输出

返回结果为JSON格式的字符串:

字段必须类型说明
itemsJSON对象数组道具列表

2.2.3 请求样例

URL:
http://activity.xgsdk.com:8040/push/gift/items-mock?sign=xxxxx

2.2.4 返回值样例

{ "items": [{ "id": "1", "name": "道具1" },{ "id": "2", "name": "道具2" }] }

2.3 查询区服

2.3.1 功能

发起方ActivityServer
接收方GameServer
接口类型HTTP GET Accept:application/json; charset=UTF-8
安全机制签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥, 对西瓜app ID进行HmacSHA1计算得到签名串, 游戏服务器在接受到请求后对签名进行校验,通过后返回结果
字符集编码UTF-8
请求地址游戏服务器提供url
功能描述获取游戏区服列表, 用于配置精准群体 -> 区服信息

2.3.2 输出

返回结果为JSON格式的字符串:

字段必须类型说明
itemsJSON对象数组道具列表

2.3.3 请求样例

URL: http://activity.xgsdk.com:8040/push/gift/zones-mock?sign=xxxxx

2.3.4 返回值样例

{ "items": [{ "zoneId": "1", "zoneName":"区1", "serverId":"1", "serverName":"服1" },{ "zoneId": "2", "zoneName":"区2", "serverId":"2", "serverName":"服2" }] }

2.4 查询关卡

2.4.1 功能

发起方ActivityServer
接收方GameServer
接口类型HTTP GET Accept:application/json; charset=UTF-8
字符集编码UTF-8
安全机制签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥, 对西瓜app ID进行HmacSHA1计算得到签名串, 游戏服务器在接受到请求后对签名进行校验,通过后返回结果
请求地址游戏服务器提供url
功能描述查询关卡信息,用于配置精准群体 -> 关卡信息

2.4.2 输出

返回结果为JSON格式的字符串:

字段必须类型说明
itemsJSON对象数组道具列表

2.4.3 请求样例

URL: http://www.gameserver.com/mission?sign=xxxxx

2.4.4 返回值样例

{ "items": [{ "id": "1", "name": "关卡1" },{ "id": "2", "name": "关卡2" }] }

2.5 查询用户信息

2.5.1 功能

发起方ActivityServer
接收方GameServer
接口类型HTTP GET Accept:application/json; charset=UTF-8
字符集编码UTF-8
请求地址游戏服务器提供url
功能描述查询用户信息,西瓜在收到用户兑换请求时根据角色ID向游戏服务器查询用户信息, 包括用户等级,所在区服,当前关卡等判断用户是否满足兑换条件(游戏服务器只需返回用户信息, 兑换判断逻辑由XG完成)

2.5.2 输入

参数必须类型说明
roleIdString角色编号
serverIdString服务器编号
zoneIdString区ID
missionIdString关卡ID(提供给游戏端来鉴定该用户是否通过此关卡)
signString签名,签名算法采用HmacSHA1,采用XgsdkServerKey为游戏服务端密钥: 1)传入参数key按字母排序。 2)按key1=value1&key2=value2&...来拼接签名源串,将值为空的参数和sign签名字段去掉,不加入签名源串,key和value不进行任何编码(如不进行URLEncoder)。 然后对最后生成的字符串进行HmacSHA1计算,得到签名串。

2.5.3 输出

返回结果为JSON格式的字符串:

字段必须类型说明
codeString错误码
msgString错误信息
itemJSON对象用户信息

2.5.4 请求样例

URL: http://activity.xgsdk.com:8040/push/gift/users-mock?roleId=1&zoneId=1=&serverId=1&missionId=24&sign=xxxxx

2.5.5 返回值样例

{ "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" } }

3.客户端接口

### 3.1 游戏提供界面 接口定义: ```cpp void exchangeGiftCode(const char* uid, const char* roleId, const char* zoneId, const char* serverId, const char* giftCode) ``` 接口说明:礼包码兑换
参数 说明
uid 玩家uid
roleId 玩家角色ID
zoneId 游戏区ID
serverId 游戏服ID
giftCode 礼包码
回调: ```cpp void onExchangeGiftCodeFinish(const char* response) ```
参数 说明 必须
response JSON 格式,如:{"code":0,"msg":"兑换成功"}, code: 0为成功,其它为失败 Y

4. 活动配置

CP 需先将以上所有接口接入完成,然后在西瓜Web控制台中填写对应的接口配置,详细配置步骤如下:

  • 选择“运营工具”->“礼包码”->“URL配置”

  • “礼包码管理”->“创建活动”

    填写“活动名称”,选择“目标人群”,进行下一步

  • 进行活动内容配置,进行下一步

  • 进行自定义错误消息配置

5.错误码列表

以下错误码提示语为默认提示语,考虑到游戏的类型以及风格的差异,西瓜提供了自定义提示语功能用来满足不同游戏的需求(详情请前往西瓜Web控制台进行配置:“运营工具”->“礼包码”->“错误消息配置”)

错误码值 错误码提示语
0 兑换成功
1000 礼包码无效,没有相应活动
1001 用户不存在
1002 活动未开始
1003 活动过期
1004 礼包码只能在指定区服使用
1005 对不起,该礼包码您已使用
1006 您领取次数已超过限制
1007 对不起,您在该活动中使用的礼包码数量已达上限
1008 礼包码在同一互斥组
1009 没有通过礼包码要求的关卡
1010 等级低于领取礼包最小等级要求
1011 等级高于领取礼包最大等级要求
1012 礼包无法在该渠道使用
2000 游戏服务器异常
2001 游戏服务器返回发放失败
2002 获取用户信息失败
3000 兑换服务器异常
3001 系统错误
3002 发生未知网络错误