活动发奖

业务场景

  1. 用户参与活动获得奖品后，活动服务端会给游戏服务端推送发放奖品通知，游戏服务端需将对应奖品发放至用户角色邮箱

注意事项

  1. CP 接口在响应之前，需做好签名和必须校验字段的值校验
    • 当 CP 服务端收到发放奖品通知，需立刻进行校验
    • 校验不通过，需返回具体不通过原因，参考文档末尾的状态码说明
  2. http 请求的重试，可能会导致数据重复推送，需要做好去重处理
    • 可能存在网络异常，导致益世界调用游戏服务端超时，游戏服务端实际已成功发奖
    • 游戏服务端若收到同一用户奖品ID和活动标识的重复发奖通知，要避免重复给玩家发奖，造成损失

流程图

接口地址

地址由CP提供

接口说明

  1. 协议：HTTPS
  2. 方式：POST
  3. ContentType：application/json;charset=utf-8
  4. 请求报文：
字段类型必需参与签名说明
appIdlong否是游戏ID
openIdstring是是SDK用户唯一标识
serverIdstring是是游戏区服ID
roleIdstring是是游戏角色ID
cpRewardIdstring是是CP奖品ID，由CP定义，多个用逗号分隔
userRewardIdlong是是用户奖品ID，根据此ID与活动标识去重，相同的用户奖品ID和活动标识认为是重复发放
actCodestring是是活动标识
extendstring是是扩展字段，根据CP跳转链接参数透传
timestamplong是是毫秒时间戳
signstring是否签名
  1. 响应报文：
字段类型必需说明
codeint是响应状态码，0：成功，其它为失败
msgstring否响应描述

请求示例

{
  "appId": 12345,
  "openId": "12345678912345678912345",
  "serverId": "123456",
  "roleId": "1234567890",
  "cpRewardId": "123",
  "userRewardId": 1,
  "actCode": "abc",
  "extend": "",
  "timestamp": 1668484881725,
  "sign": "3a4808703bdd793ceb54b14230b9c483"
}

响应示例

{
        "code": 0,
        "msg": "success"
}

签名规则

  1. 参数名区分大小写，按 ASCII 码从小到大排序（字典序）
  2. 只有值为 null 和 参数名不参与签名 的键值对，才不参与签名
  3. 使用 URL 键值对的格式，拼接成待签名字符串，签名 key 在最后拼接，再进行MD5计算
  4. 将生成的签名与入参 sign 值作校验，验签忽略大小写
String sign = md5(k1=v1&k2=v2...&key=appKey);

调试示例

import cn.hutool.crypto.SecureUtil;

import java.util.LinkedHashMap;
import java.util.Map;
import java.util.TreeMap;

public class DeliverRewardExample {
    public static String getMd5Sign(Map<String, Object> params, String appKey) {
        TreeMap<String, Object> sortedParams = new TreeMap<>(params);
        StringBuilder builder = new StringBuilder(512);
        sortedParams.forEach((k, v) -> {
            if (v != null) {
                builder.append(k).append("=").append(v).append("&");
            }
        });
        builder.append("key=").append(appKey);
        return SecureUtil.md5(builder.toString());
    }

    public static void main(String[] args) {
        Map<String, Object> notifyMap = new LinkedHashMap<>();
        notifyMap.put("appId", 12345L);
        notifyMap.put("openId", "12345678912345678912345");
        notifyMap.put("serverId", "123456");
        notifyMap.put("roleId", "1234567890");
        notifyMap.put("cpRewardId", "123");
        notifyMap.put("userRewardId", 1L);
        notifyMap.put("actCode", "abc");
        notifyMap.put("extend", "");
        notifyMap.put("timestamp", 1668484881725L);
        String appKey = "1234567890abcdef";
        System.out.printf("签名:%s%n", getMd5Sign(notifyMap, appKey));
    }
}

响应状态码

状态码说明
0成功
1000未知错误
1001验签失败
1002参数缺失
10001当前无法发奖，需要重推
10002奖品重复发放
10003角色不存在