菜单

事件上报接口

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

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

接口信息

请求地址

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，则代表数据传输成功。

请求示例：

 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",
    "event_list": [
        {
            "type": "track",
            "event": "$MPLaunch",
            "time": 1669860000000,
            "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,
            "properties": {
                "$signup_time": "2022-12-01 00:00:00"
            }
        }
    ]
}'

上一个

混合上报模式

下一个

小游戏Token接入

最近修改: 2025-11-14Powered by