事件对接说明

通过统一的事件格式,快速对接各大广告平台,实现无缝的数据追踪与转化分析。

8种

标准事件类型

99.9%

事件上报率

<50ms

平均响应时间

标准事件列表

基础事件

访问打开 (page_view)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `page_view`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`page_url`	当前页面URL	string
`referrer`	来源URL（可选）	string

调用示例

// 示例：访问打开事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_010", "event_name": "page_view", "timestamp": 1678904234567, "channel_id": "facebook", "user_id": "u010", "page_url": "https://example.com/home", "referrer": "https://google.com" }

基础事件

点击按钮 (click_button)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `click_button`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`button_id`	按钮标识	string
`click_context`	点击场景描述（可选）	string

调用示例

// 示例：点击按钮事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_011", "event_name": "click_button", "timestamp": 1678905234567, "channel_id": "facebook", "user_id": "u011", "button_id": "btn_123", "click_context": "首页-注册按钮" }

基础事件

注册事件 (user_register)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `user_register`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`ip_address`	注册IP	string
`register_type`	注册类型 ("email"/"phone")	string
`email`	当类型为 "email"	string
`phone`	当类型为 "phone"	string
`source_channel`	注册渠道	string

调用示例

// 示例：注册事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_001", "event_name": "user_register", "timestamp": 1678901234567, "channel_id": "facebook", "user_id": "u001", "ip_address": "192.168.1.1", "register_type": "email", "email": "[email protected]", "source_channel": "website" }

基础事件

登录事件 (user_login)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `user_login`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`ip_address`	登录IP	string
`login_type`	登录方式	string
`account`	登录账号	string
`login_source`	登录来源	string

调用示例

// 示例：登录事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_002", "event_name": "user_login", "timestamp": 1678902234567, "channel_id": "facebook", "user_id": "u002", "ip_address": "192.168.1.2", "login_type": "password", "account": "[email protected]", "login_source": "web" }

转化事件

第一次充值 (first_purchase)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `first_purchase`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`ip_address`	充值IP	string
`amount`	充值金额	number
`currency`	货币类型	string
`product_id`	商品ID	string
`product_name`	商品名称	string
`payment_method`	支付方式	string
`user_source_channel`	用户归属渠道	string

调用示例

// 示例：第一次充值事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_003", "event_name": "first_purchase", "timestamp": 1678903234567, "channel_id": "facebook", "user_id": "u003", "ip_address": "192.168.1.3", "amount": 99.99, "currency": "USD", "product_id": "p001", "product_name": "Product A", "payment_method": "credit_card", "user_source_channel": "website" }

转化事件

充值提交 (payment_initiated)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `payment_initiated`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`ip_address`	发起支付IP	string
`amount`	订单金额	number
`currency`	货币类型	string
`cart_items`	购物车内容 (array/object)	string/array
`payment_method`	支付方式	string

调用示例

// 示例：充值提交事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_004", "event_name": "payment_initiated", "timestamp": 1678904234567, "channel_id": "facebook", "user_id": "u004", "ip_address": "192.168.1.4", "amount": 199.99, "currency": "USD", "cart_items": [ { "product_id": "p002", "quantity": 1 } ], "payment_method": "paypal" }

转化事件

提交成功 (submit_success)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `submit_success`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`order_id`	订单编号	string
`submit_status`	提交状态	string

调用示例

// 示例：提交成功事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_005", "event_name": "submit_success", "timestamp": 1678905234567, "channel_id": "facebook", "user_id": "u005", "order_id": "ord_1001", "submit_status": "success" }

转化事件

支付成功 (payment_success)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `payment_success`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`transaction_id`	交易编号	string
`payment_status`	支付状态	string

调用示例

// 示例：支付成功事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_006", "event_name": "payment_success", "timestamp": 1678906234567, "channel_id": "facebook", "user_id": "u006", "transaction_id": "txn_2001", "payment_status": "completed" }

转化事件

首次提现 (first_withdraw)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `first_withdraw`	string
`amount`	提现金额	number
`currency`	货币类型	string
`withdraw_method`	提现方式	string
`account_info`	提现账户信息	object

调用示例

// 示例：首次提现事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_w001", "event_name": "first_withdraw", "timestamp": 1678907234567, "channel_id": "facebook", "user_id": "u007", "amount": 1000.00, "currency": "USD", "withdraw_method": "bank_transfer", "account_info": { "bank_name": "Example Bank", "account_number": "****1234", "holder_name": "John Doe" } }

转化事件

提现成功 (withdraw_success)

请求参数

字段	描述	类型
`event_id`	唯一事件ID	string
`event_name`	固定为 `withdraw_success`	string
`timestamp`	时间戳	int
`merchant_id`	商户编号	string
`channel_id`	渠道编号	string
`user_id`	用户编号	string
`withdraw_id`	提现订单号	string
`status`	提现状态	string
`complete_time`	完成时间	int

调用示例

// 示例：提现成功事件 { "merchant_token": "MERCHANT_TOKEN_ABC", "merchant_id": "1001", "event_id": "evt_w002", "event_name": "withdraw_success", "timestamp": 1678908234567, "channel_id": "facebook", "user_id": "u008", "withdraw_id": "wd_1001", "status": "completed", "complete_time": 1678909234567 }

API 说明

公共参数

字段	描述	类型	是否必填
`merchant_token`	商户令牌,用于验证请求合法性	string	必填
`merchant_id`	商户编号,在平台注册时获得	string	必填
`event_id`	事件唯一标识,建议使用UUID格式	string	必填
`event_name`	事件名称,参考标准事件列表	string	必填
`timestamp`	事件发生时间戳(毫秒)	int	必填
`channel_id`	渠道编号,在创建渠道时获得	string	必填
`user_id`	用户唯一标识	string	必填

请求说明

接口地址


                            POST https://api.example.com/v1/events

请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

响应格式

{ "code": 200, "message": "success", "data": { "event_id": "evt_xxx", "accepted_at": "2024-01-20T10:30:45Z" } }

注意事项

所有请求必须包含完整的公共参数
timestamp 必须是毫秒级的时间戳
事件数据最长保留180天
单个请求大小不超过1MB