服务端集成 · 事件采集 · 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	事件属性/用户属性，具体需要参考引力引擎后台-设置-元数据中的内容

请求示例

curl 'https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=<ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "client_id": "user_client_id",
    "client_ip": "114.138.179.81",
    "event_list": [
        {
            "type": "track",
            "event": "$MPLaunch",
            "time": 1669860000000,
            "time_free": true,
            "properties": {
                "$is_first_time": false,
                "$scene": "1069",
                "$screen_width": 360,
                "$screen_height": 800,
                "$os": "android",
                "$manufacturer": "realme",
                "$city": "南京市",
                "$trace_id": "c1a953d236db6591661543419e436677"
            }
        },
        {
            "type": "profile",
            "event": "profile_set_once",
            "time": 1669824000000,
            "time_free": true,
            "properties": {
                "$signup_time": "2022-12-01 00:00:00"
            }
        }
    ]
}'

响应结果

如果收到返回参数，code: 0，则代表数据传输成功。

响应示例：

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

Restful API

本页内容