# 混合上报模式

> 来源：https://help.gravity-engine.com/docs/client-sdk/hybrid-reporting
> 说明客户端 SDK 与业务服务端共同上报数据的混合模式，并以付费事件为例讲解用户标识传递和接入步骤。



如果您应用内有些事件需要通过自有后端直接报送给引力引擎，那我们推荐您使用 **混合上报模式** 来完成接入，继续阅读本篇文档，我们将以付费事件为例讲解混合上报模式的接入步骤。

## 1. 客户端接入 [#1-客户端接入]

客户端接入引力引擎提供的 SDK，不同客户端技术栈，对应不同的 SDK，具体可以参考 [SDK 总览](/docs/client-sdk/sdk-overview)。

> **注意**
> 客户端 SDK 会负责自采集很多基础事件和属性，这部分工作引力提供的 SDK 已经完成封装

## 2. 服务端接入 [#2-服务端接入]

服务端接入[事件收集上报接口](/docs/server-integration/event-collection/restful-api)，完成事件的服务端报送功能，您需要注意以下几点：

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

> **注意**
> **通过 API 上报请务必添加参数：`$lib`，并固定传入字符串`api`**

## 3. 付费事件示例与验收 [#3-付费事件示例与验收]

推荐顺序：客户端初始化成功 → 将当前 ClientID 传给业务服务端并关联订单 → 业务服务端确认支付成功 → 上报付费事件。先确定付费事件由哪一端负责，避免客户端和服务端各上报一次。

以下是放入 `event_list` 的单个事件对象，不是完整请求体。外层 `client_id`、`access_token` 和完整调用方式请参考 [事件采集 API](/docs/server-integration/event-collection/restful-api)。

`time` 为事件实际发生的毫秒时间戳，示例时间仅用于展示结构，调用前必须替换；实时业务请保持 `time_free=false`。`$pay_amount` 单位为分，示例的 600 表示 6 元；`$order_id` 使用真实业务订单号。设备与网络信息只传入已采集到的真实值，不要复制示例值。

```json
{
  "type": "track",
  "event": "$PayEvent",
  "time": 1669860000000,
  "time_free": false,
  "properties": {
    "$lib_version": "1.0",
    "$lib": "api",
    "$network_type": "4g",
    "$manufacturer": "HONOR",
    "$brand": "HONOR",
    "$model": "JLH-AN00",
    "$screen_width": 360,
    "$screen_height": 796,
    "$system_language": "zh_CN",
    "$os": "android",
    "$os_version": "Android 12",
    "$pay_amount": 600,
    "$pay_type": "CNY",
    "$order_id": "你的订单ID",
    "$pay_reason": "月卡",
    "$pay_method": "微信",
    "$is_first_pay": false,
    "$ip": "用户真实IP"
  }
}
```

收到成功响应后，请在 [事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 按相同 ClientID 核对订单号、金额和事件次数，再按 [接入验收与排错](/docs/getting-started/integration-checklist) 完成上线检查。