游戏内邮件接入说明文档

1. 接入必读

该文档主要包含游戏内邮件发送任务接收接口的定义,接入后可通过掌趣统一后台进行游戏内邮件推送;

2. 准备工作

  1. 在掌趣MIS平台上创建需要接入邮件推送的产品和游戏服;
  2. 在掌趣MIS平台配置统一的邮件推送任务接收地址(支持单个游戏服配置);

    3. 接口说明

  • 接口协议:HTTP POST;
  • 交互数据格式:JSON格式(以UTF-8进行编码); 数据直接通过HTTP消息体传输(非KEY-VALUE模式);

4. 接口

4.1 游戏内邮件发送任务接收接口

该接口主要实现:统一由掌趣后台提交游戏内邮件发送任务至游戏服, 发送任务由掌趣后台管理,通过调用该接口通知各个游戏服进行发送给具体玩家; 发送规则需要支持邮件有效期按角色等级范围按角色VIP等级范围按角色列表 的方式进行发送;

  • 4.1.1 接口地址
    该接口由游戏服按接口规范实现, 提供接口地址给运营人员进行配置;

  • 4.1.2 请求参数

参数父节点 参数名称 类型 限制策略 说明
- emailId 字符串 必填 邮件唯一标识; 用来区分每一个邮件发送任务
- subject 字符串 必填 邮件主题信息
- content 字符串 必填 邮件详细内容
- serverId 字符串 必填 游戏服ID, 标注本邮件发往那个游戏服; 注意:若同一封邮件发往多个游戏服时,邮件唯一标识相同,顺序多次调用本接口通知每一个游戏服
- beginTime 数值 必填 邮件生效开始时间; 毫秒数,如:1521452724853
- endTime 数值 必填 邮件生效截止时间; 毫秒数,如:1521452724853
- roleLevel 字符串 选填 角色等级限制区间,以”-“分隔;闭区间; 空表示无此限制; 如:0-100
- roleVipLevel 字符串 选填 角色VIP等级限制区间,以”-“分隔;闭区间;空表示无此限制; 如:10-20
- roles 字符串 选填 指定角色ID, 多个以英文逗号”,”分隔;空表示无此限制; 如:10000,10001,10002,10003
- attachment 字符串 选填 道具附件列表,数组对象的json字符串, 空表示无附件
attachment[i] propId 字符串 必填 附件中单个道具ID
attachment[i] propNum 字符串 必填 附件中单个道具数量
attachment[i] customParam 字符串 选填 附件中单个道具的自定义参数
- checkSum 字符串 必填 校验码, 校验规则参见附件二
  • 4.1.3 返回参数
参数名称 类型 说明
status 字符串 0:成功; 1:失败;
reset 字符串 详细返回码; 参见附件一
desc 字符串 返回描述;
  • 4.1.4 请求示例
    1. {
    2.   "attachment":"[{\"propId\":\"1\",\"propNum\":\"10\",\"customParam\":\"扩展数据\"},{\"propId\":\"4\",\"propNum\":\"10\",\"customParam\":\"扩展数据2\"}]",
    3.   "beginTime":1522512000000,
    4.   "content":"祝游戏愉快",
    5.   "emailId":"8a838ab3628af06401628ea790b30003",
    6.   "endTime":1525017600000,
    7.   "serverId":"1010",
    8.   "roleLevel":"1-20",
    9.   "roleVipLevel":"1-19",
    10.   "roles":"",
    11.   "subject":"发送邮件",
    12.   "checkSum":"935AFF72B50B79007D664AB223EF9829"
    13. }
  • 4.1.5 返回示例
    1. {
    2. "status":"0",
    3. "desc":"成功",
    4. "reset":"000"
    5. }

附录一 (游戏邮件通知接口响应编码定义表)

响应码 描述
000 成功
500 未知异常
501 签名校验失败
400 不支持发送有效时间段
401 不支持按角色等级发送
402 不支持按角色VIP等级发送
403 不支持按角色列表发送
404 发送主题被禁止
405 发送内容被禁止
406 发送道具被禁止

附录二 (接口交互数据checkSum校验规则)

校验规则
参数(除checkSum外)按照字典顺序依次取值,如示例的json

  1. {
  2.   "attachment":"[{\"propId\":\"1\",\"propNum\":\"10\",\"customParam\":\"扩展数据\"},{\"propId\":\"4\",\"propNum\":\"10\",\"customParam\":\"扩展数据2\"}]",
  3.   "beginTime":1522512000000,
  4.   "content":"祝游戏愉快",
  5.   "emailId":"8a838ab3628af06401628ea790b30003",
  6.   "endTime":1525017600000,
  7.   "roleLevel":"1-20",
  8.   "roleVipLevel":"1-19",
  9.   "roles":"",
  10. "serverId":"1010",
  11.   "subject":"发送邮件",
  12.   "checkSum":"4E0CA6F89D05FEB1F3804256E043A107"
  13. }

需要校验的参数字符串为:
[{"propId":"1","propNum":"10","customParam":"扩展数据"},{"propId":"4","propNum":"10","customParam":"扩展数据2"}]1522512000000祝游戏愉快8a838ab3628af06401628ea790b3000315250176000001-201-191010发送邮件

最后需添加产品密钥(产品密匙可从MIS上获取),此处为测试密钥,如:12345453i1rm129rf2s8fy5j80ao0626

最后计算
MD5([{"propId":"1","propNum":"10","customParam":"扩展数据"},{"propId":"4","propNum":"10","customParam":"扩展数据2"}]1522512000000祝游戏愉快8a838ab3628af06401628ea790b3000315250176000001-201-191010发送邮件12345453i1rm129rf2s8fy5j80ao0626)

结果为:4E0CA6F89D05FEB1F3804256E043A107