服务端集成 · 事件采集 · Restful API

说明如何通过 Gravity Engine RESTful API 上报用户行为与用户属性，包括认证、请求体、返回结果和混合上报要求。

引力引擎支持使用 API 方式直接上报用户行为事件和用户属性事件，您可以配合引力引擎客户端 SDK 实现混合上报。

在开始对接此接口前，建议您先阅读数据规则章节，在熟悉引力引擎的数据格式与数据规则后，再阅读本指南进行对接。

服务端接入 Restful API，完成事件的服务端报送功能，您需要注意以下几点：

服务端仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 initialize 方法完成；
客户端和服务端使用的用户 client id 需要保持一致；
在客户端完成 initialize 方法调用之后，服务端才能开始做事件采集上报，否则上报不成功；
服务端接入事件上报时，请参考元事件页面下关于事件的详情属性；
请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（$city、$province、$country、$browser、$browser_version 属性可以不上报，引力后端会自动采集）；
关于属性的更多信息，请您参考事件属性页面。

接口信息

请求地址

https://backend.gravity-engine.com/event_center/api/v1/event/collect/

请求方法

POST

query 参数

参数名称	必填	参数说明
`access_token`	Y	当前 app 的 `access_token`

body 参数

参数名	必填	类型	描述
`client_id`	Y	string	用户唯一 ID
`client_ip`	N	string	如果有值，则引力引擎会取该 `ip` 作为 `$ip` 字段（强制替换）
`client_ua`	N	string	如果有值，则引力引擎会取该 `ua` 作为 `$ua` 字段（强制替换）
`event_list`	Y	EventObject[]	事件列表，具体参见 EventObject

EventObject

参数名	必填	类型	描述
`type`	Y	string	事件类型，可选值：`track`、`profile`，分别对应用户埋点事件、用户属性事件
`event`	Y	string	用户埋点事件英文名称请参考引力后台-设置-元事件，用户属性事件名称参考这里
`time`	Y	number	事件发生毫秒级时间戳，只接收相对服务器时间在前 10 天至后 1 小时之内的数据，超过范围的数据将不会入库
`time_free`	N	bool	默认为 `false`，当为 `true` 时会取消对 `time` 参数的校验（一般用于历史数据导入）
`properties`	Y	struct	事件属性/用户属性，具体需要参考引力引擎后台-设置-元数据中的内容

通过 API 上报时，请在每个事件的 properties 中设置 "$lib": "api"，与混合上报模式保持一致。

请求示例

先填写测试应用的 Access Token 和已初始化成功的 ClientID。下面在发送时生成当前毫秒时间戳；生产业务应使用订单实际支付时间。此命令会向真实采集接口上报一条 6 元测试付费事件，请只在确认过的测试应用中执行，并使用未重复的测试订单号。

ACCESS_TOKEN='YOUR_ACCESS_TOKEN'
CLIENT_ID='YOUR_INITIALIZED_CLIENT_ID'
EVENT_TIME_MS=$(node -p 'Date.now()')

curl "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=${ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"client_id\": \"${CLIENT_ID}\",
    \"event_list\": [{
      \"type\": \"track\",
      \"event\": \"\$PayEvent\",
      \"time\": ${EVENT_TIME_MS},
      \"time_free\": false,
      \"properties\": {
        \"\$lib\": \"api\",
        \"\$pay_amount\": 600,
        \"\$pay_type\": \"CNY\",
        \"\$order_id\": \"YOUR_UNIQUE_TEST_ORDER_ID\",
        \"\$pay_reason\": \"测试商品\",
        \"\$pay_method\": \"微信\",
        \"\$is_first_pay\": false
      }
    }]
  }"

上述命令依赖本地 Node.js 生成时间戳。美元符号前的反斜杠用于避免 shell 将预置事件和属性名当作变量展开，复制时请保留。用户属性操作仍使用同一外层结构，并按数据规则设置 type、event 和 properties。

响应结果

响应中 code: 0 表示接口返回传输成功。仍需在事件流按 ClientID 核对实际入库情况，包括订单号、金额和属性类型；HTTP 200 本身不能代替业务结果检查。

响应示例：

{
    "data": {},
    "extra": {
        "error": "",
        "errors": []
    },
    "code": 0,
    "msg": "成功"
}

Restful API

本页内容