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

2.1.2 输入

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

2.1.3 输出

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

字段	必须	类型	说明
code	是	String	返回码，参见错误码章节
msg	是	String	接口调用信息提示

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格式的字符串：

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

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格式的字符串：

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

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格式的字符串：

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

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 输入

参数	必须	类型	说明
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计算，得到签名串。

2.5.3 输出

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

字段	必须	类型	说明
code	是	String	错误码
msg	是	String	错误信息
item	是	JSON对象	用户信息

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	发生未知网络错误