广告事件上报

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

区分渠道

如果需要区分哪些渠道可以通过调用查询广告参数接口查询链接的参数，通过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
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	{}	返回数据

示例

请求示例

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

返回示例

{
   "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 上报：

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

实际转发给 MgskyAds：

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