> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 广告事件上报

目前系统支持 Facebook、TikTok、Kwai、MgskyAds 等多个广告平台的事件回传。
调用本 API 的调用方无需区分链接来自哪方广告平台，ROIBest 系统会自动区分并将事件回传至对应的来源。

::: tip 区分渠道
如果需要区分哪些渠道可以通过调用[查询广告参数](/developer/query-link-info.md)接口查询链接的参数，通过channel_id区分

- `"4"` = Facebook
- `"5"` = Tiktok
- `"9"` = Kwai
- `"10"` = Google
- `"20"` = 小步网络
- `"21"` = OKSPIN
- `"22"` = SNAPTUBE
- `"23"` = BIGO
- `"24"` = APPLUCK
- `"34"` = Trafficstars
- `"56"` = MG SKY
- `"58"` = Macan Native
- `"60"` = Propellerads
- `"61"` = MiniTrax
  :::

推广链接不可跨渠道投放，即在 MIS 中获取的 tiktok 渠道推广链接不可放在 Kwai 平台上，这会导致识别的来源出错，从而导致事件回传失败。

|        |                                                                                                                |
| :----- | :------------------------------------------------------------------------------------------------------------- |
| URL    | [https://sdk-report.roibestopenapi.com/report/fb/event](https://sdk-report.roibestopenapi.com/report/fb/event) |
| Method | POST                                                                                                           |

在调用本 API 之前，需要完成广告配置。并且调用 API 所传递的 link_id 必须是从广告平台进入生成的 ID。

## 请求参数

请使用 JSON 格式在 Request Body 中传递；`event_name` 请根据各个广告平台的事件名进行传递，`extra`里的数据请根据各个平台的对应事件的相关额外字段进行传递，我们会对应发送给各个平台。即`event_name`事件名和`extra`里的字段按各个平台不同的情况来写。

| 参数名        | 类型     | 是否必须 | 参考值                                   | 描述                                                        |
| :--------- | :----- | :--- | :------------------------------------ | :-------------------------------------------------------- |
| link_id    | string | 是    | 4740128923061846                      | 由系统生成的链接 ID                                               |
| event_name | string | 是    | Purchase                              | 从广告平台获取的事件名称或标识。（含自定义事件）                                  |
| extra      | object | 否    | `{"currency": "USD", "value": 19.99}` | 事件的额外参数。如果对应的事件需要传递额外参数放在本字段中，_**ROIBest 将会透传至对应的广告平台**_。 |

关于是否需要传递额外参数请查询各广告平台的事件定义。以下是 Facebook 平台部分需要提供的额外字段的事件：

| 事件名称  | 英文名称                 | 必填参数                      |
| :---- | :------------------- | :------------------------ |
| 加入购物车 | AddToCart            | event_name                |
| 加入心愿单 | AddToWishlist        | event_name                |
| 完成注册  | CompleteRegistration | event_name                |
| 留下线索  | Contact              | event_name                |
| 订阅    | Subscribe            | event_name                |
| 结账    | Purchase             | event_name、currency、value |

## 响应参数

服务器固定以 JSON 方式返回响应。

| 参数名  | 类型     | 参考值     | 描述            |
| :--- | :----- | :------ | :------------ |
| code | int    | 0       | 0 代表成功，其他代表失败 |
| msg  | string | success | 详细信息          |
| data | object | \{}     | 返回数据          |

## 示例

### 请求示例

```json
{
   "link_id": "4740128923061846",
  "event_name": "Purchase",
  "extra": {
      "currency": "USD",
      "value": 19.99,
      "is_upgrade_version": 1
   }
}
```

### 返回示例

```json
{
   "code": 0,
   "msg": "success",
   "data": {}
}
```

## MgskyAds 渠道说明

### 标准事件枚举

MgskyAds 仅识别以下 3 个标准事件，`event_name` 请从下表中选择：

| 事件常量                          | 含义      |
| :---------------------------- | :------ |
| `EVENT_COMPLETE_REGISTRATION` | 完成注册    |
| `EVENT_FIRST_DEPOSIT`         | 首次充值    |
| `EVENT_PURCHASE`              | 付费 / 购买 |

### API 上报事件映射

如果您在 API 调用中使用的 `event_name` 与上方标准枚举不一致（例如填写了 `purchase`、`pay`、`register` 等自定义名称），可以在 ROIBest MIS → 像素配置 → MgskyAds → 编辑弹窗中配置 **API 上报事件映射规则**。

配置映射后，ROIBest 会在转发前将自定义 `event_name` 自动替换为对应的 MgskyAds 标准事件：

- 匹配规则：**大小写不敏感**，自动忽略前后空格（`Purchase`、`purchase`、`PURCHASE` 视为同一项）
- 未命中映射：`event_name` **原名透传**至 MgskyAds，不丢弃、不报错
- 未配置任何映射：所有上报均以原 `event_name` 透传

**示例：**

映射配置（在 MIS 中设置）：

| 上报的事件名          | 映射为 MgskyAds 标准事件             |
| :-------------- | :---------------------------- |
| `purchase`      | `EVENT_PURCHASE`              |
| `pay`           | `EVENT_PURCHASE`              |
| `register`      | `EVENT_COMPLETE_REGISTRATION` |
| `first_deposit` | `EVENT_FIRST_DEPOSIT`         |

API 上报：

```json
{
  "link_id": "4740128923061846",
  "event_name": "Purchase",
  "extra": { "currency": "USD", "value": 19.99 }
}
```

实际转发给 MgskyAds：

```json
{
  "link_id": "4740128923061846",
  "event_name": "EVENT_PURCHASE",
  "extra": { "currency": "USD", "value": 19.99 }
}
```