推送角色事件

业务场景

  1. 为游戏提供更多触达玩家的机会，以达到促活跃、促付费等业务目的
  2. 数据使用方，包括但不限：华为快应用、oppo小游戏

注意事项

  1. 事件KEY 和 属性KEY，是配套使用的，注意区分字母大小写
  2. 属性KEY，对应的内容格式，不同渠道有不同的要求

接口地址

https://cp.gzxianc.com/open-api/v1/user/role-event-report

接口说明

  1. 协议：HTTPS
  2. 方式：POST
  3. ContentType：application/json;charset=utf-8
  4. 请求报文：
字段类型必需参与签名说明
appIdlong是是SDK的 appId
channelIdlong是是SDK的渠道id
openIdstring是是SDK用户唯一标识
roleIdstring是是游戏角色ID
eventKeystring是是事件KEY，【格式：普通字符串】，由 游戏运营 提供
eventPropertiesstring是是属性KEY，【格式：json字符串】
timestamplong是是毫秒时间戳
signstring是否签名
  1. 响应报文：
字段类型必需说明
codeint是状态码：0代表成功，非0代表失败
msgstring是响应描述

属性KEY说明

华为渠道

事件KEY和属性KEY，是渠道运营在华为后台自定义配置，具体信息由 【游戏运营】 提供，下面是某游戏的举例

事件名称事件KEY属性KEYeventProperties值
不良司建筑收益Construction_revenueRevenue_scale{"Revenue_scale":"99"}
粥铺安置收益Placement_incomeRefugees_number{"Refugees_number":"99"}
县学建筑收益School_revenueRevenue_Quantity{"Revenue_Quantity":"99"}

oppo渠道

字段类型必需说明
uniqueStrstring是32位数据唯一标识, 用于幂等。 重试的请求, 该字段的值保持不变
finishTimestring是用户在游戏中完成游戏行为的时间, 格式：yyyy-MM-dd HH:mm:ss

eventProperties值举例：{"uniqueStr":"cd3611dc666f4ddb83797fc668286d01","finishTime":"2025-06-01 09:18:27"}

请求示例

{
	"appId": 7010985,
	"channelId": 1441,
	"openId": "12345678912345678912345",
	"roleId": "2700033751",
	"eventKey": "ZCYLT_GAME_ZHAOXIAN_EVERY_1_FFFFFF_INSTANT_GAME_CP",
	"eventProperties": "{\"uniqueStr\":\"cd3611dc666f4ddb83797fc668286d01\",\"finishTime\":\"2025-06-01 09:18:27\"}",
	"timestamp": 1742528920316,
	"sign": "ecc0f3e8d3e3c29e3deb1f3a97954f12"
}

响应示例

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

签名规则

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

调试示例

import cn.hutool.crypto.SecureUtil;

import java.util.HashMap;
import java.util.Map;
import java.util.TreeMap;

public class SignExample {

    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) {
        String appKey = "AaBbCcDdEeFfGgHh";
        Map<String, Object> reqMap = new HashMap<>();
        reqMap.put("appId", 7010985L);
        reqMap.put("channelId", 1441L);
        reqMap.put("openId", "12345678912345678912345");
        reqMap.put("roleId", "2700033751");
        reqMap.put("eventKey", "ZCYLT_GAME_ZHAOXIAN_EVERY_1_FFFFFF_INSTANT_GAME_CP");
        reqMap.put("eventProperties", "{\"uniqueStr\":\"cd3611dc666f4ddb83797fc668286d01\",\"finishTime\":\"2025-06-01 09:18:27\"}");
        reqMap.put("timestamp", 1742528920316L);
        System.out.println(String.format("角色行为事件签名:%s", getMd5Sign(reqMap, appKey)));
    }
}