# 事件回调

> 来源：https://help.gravity-engine.com/docs/attribution/event-callback
> 说明如何配置事件回调，在用户触发指定事件时将事件数据与归因信息发送至业务服务器。



## 一、功能概述 [#一功能概述]

事件回调功能用于当用户在你的应用内触发指定事件时，系统自动将事件数据及用户归因信息回传到你配置的服务器地址。

### 适用场景 [#适用场景]

* 实时获取用户行为事件数据
* 与自有 BI/数据系统进行打通
* 基于事件数据进行二次营销或分析

## 二、配置步骤 [#二配置步骤]

### 1. 开启事件回调开关 [#1-开启事件回调开关]

在后台应用管理页面找到[事件回调](https://web.gravity-engine.com/#/manage/appmanage)配置模块，打开开关以启用功能。

### 2. 选择回调事件 [#2-选择回调事件]

在回调事件下拉框中，选择需要监听的事件类型（如激活、付费等）。

### 3. 配置回调地址 [#3-配置回调地址]

> **注意：请确保该地址为可公网访问的域名，且服务稳定。**

在回调地址输入框中，填写你的服务端接收数据的 URL。

### 4. 配置回调参数（可选） [#4-配置回调参数可选]

点击新增按钮，添加回调宏参数

系统会将这些参数追加到回调请求中，方便你在服务端进行识别。

| 参数类型  | 说明                  | 示例             |
| ----- | ------------------- | -------------- |
| 自定义参数 | 你自己定义的参数名           | `turbo_app_id` |
| 宏参数   | 系统预置宏参数变量，如引力 APPID | 引力 APPID       |

### 5. 设置请求方式 [#5-设置请求方式]

回调方法：固定为 `POST`

### 6. 设置超时与重试 [#6-设置超时与重试]

| 配置项  | 默认值     | 说明                 |
| ---- | ------- | ------------------ |
| 超时时长 | 2000 毫秒 | 服务端需在此时限内响应，否则视为超时 |
| 重试次数 | 1 次     | 请求失败后会自动重试的次数      |

## 三、签名生成 [#三签名生成]

引力在触发事件回调时，会携带签名参数，您可以考虑校验该值来避免接口被滥用，计算签名的步骤如下：

```python
import json
import hashlib
def get_sign(params: dict , access_token: str) -> str:
    """
    @param params: 请求体参数
    @param access_token: 引力 App 的 access_token（该参数在应用管理界面可以获取）
    """
    param_list = []
    for k, v in params.items():
        if k == "sign":
            continue
        param_list.append(f"{k}={json.dumps(v,sort_keys=True)}")
    param_list.sort()
    sb = "&".join(param_list) + access_token
    current_str = sb.replace("\"", "").replace(" ", "")
    return hashlib.md5(current_str.encode("utf-8")).hexdigest()
```

## 四、回调数据结构说明 [#四回调数据结构说明]

当事件触发后，引力服务端会以 `POST` 方式向你配置的回调地址发送以下 JSON 格式数据：

### 请求体格式 [#请求体格式]

```json
{
    "app_id": "your_app_id",
    "client_id": "your_client_id",
    "sign": "8bf4b8a9abadab70009b3f84cdd14eba",
    "events": [
        {
            "event": "eventname",
            "time": 1779439377000,
            "properties": {}
        }
    ],
    "callback_params": {
        "key1": "value1",
        "key2": "value2"
    }
}
```

### 字段说明 [#字段说明]

| 字段                    | 类型     | 说明                                     |
| --------------------- | ------ | -------------------------------------- |
| `app_id`              | string | 引力平台分配的应用 ID                           |
| `client_id`           | string | 客户唯一标识 ID                              |
| `sign`                | string | 签名，生成规则参考上方的签名生成                       |
| `events`              | array  | 事件列表，可同时包含多个事件                         |
| `events[].event`      | string | 事件名称（如 `$UserAttribution`、`$PayEvent`） |
| `events[].time`       | number | 事件发生时的毫秒级时间戳（Unix timestamp）           |
| `events[].properties` | object | 事件的事件属性，根据事件类型动态变化                     |
| `callback_params`     | object | 你在配置界面添加的宏参数和自定义参数                     |

## 五、接入示例 [#五接入示例]

### 回调请求示例 [#回调请求示例]

```bash
curl -X POST 'https://your-server.com/callback' \
-H 'Content-Type: application/json' \
-d '{
  "app_id": "your_app_id",
  "client_id": "your_client_id",
  "sign": "8bf4b8a9abadab70009b3f84cdd14eba",
  "events": [
    {
      "event": "eventname",
      "time": 1779439377000,
      "properties": {}
    }
  ],
  "callback_params": {
    "key1": "value1",
    "key2": "value2"
  }
}'
```

### 服务端响应要求 [#服务端响应要求]

您的服务端收到回调后，应在超时时间内返回 HTTP `200` 状态码，且响应结果为 JSON 格式 `{"code":0}`，表示回调成功。若返回非 `200` 状态码、响应结果不是 JSON 格式，或请求超时，系统将按照配置的重试次数进行重试。