# 接入验收与排错

> 来源：https://help.gravity-engine.com/docs/getting-started/integration-checklist
> 按准备、初始化、事件入库、归因联调和上线五个阶段验收 Gravity Engine 接入，提供常见故障的排查顺序与支持信息清单。



代码集成完成后，请用测试用户走完本页流程。**初始化成功、事件入库、广告归因成功和媒体回传成功是不同的验收项，应分别确认。**

## 1. 准备接入信息 [#1-准备接入信息]

| 检查项   | 通过标准                                                                                                     |
| ----- | -------------------------------------------------------------------------------------------------------- |
| 应用与环境 | 明确测试使用的引力应用 ID、目标平台、SDK 版本及国内/海外节点；测试数据与正式数据的归属已确认                                                       |
| 接入方式  | 已按 [SDK 总览](/docs/client-sdk/sdk-overview) 选择技术栈；服务端补充上报时已阅读 [混合上报模式](/docs/client-sdk/hybrid-reporting) |
| 凭证    | SDK/事件采集使用引力应用 Access Token；OpenAPI 使用开发者应用 `app_key`；微信/抖音平台 Token 与两者分别管理                              |
| 采集方案  | 明确事件名、触发时机、属性类型、金额单位和上报端；自定义事件及属性已在后台配置                                                                  |
| 用户标识  | 客户端与服务端使用同一引力应用、同一 [ClientID](/docs/client-sdk/client-id)，业务登录后不会随意切换标识                                  |
| 权限与网络 | 已按对应平台文档配置网络权限及合法域名，并确认 SDK 的启动时机符合项目的隐私授权流程                                                             |

## 2. 验证初始化 [#2-验证初始化]

1. 按对应平台快速集成文档配置 SDK，区分启动配置 `setupAndStart` 和用户初始化 `initialize`。
2. 观察初始化成功回调或返回结果；发生异常时先排查错误，不继续发送依赖初始化的事件。
3. 记录本次测试的应用 ID、SDK 版本、ClientID 和初始化时间，用同一个 ClientID 核对后续数据。
4. 如需服务端上报，先把客户端初始化成功后的 ClientID 传给业务服务端，再触发上报。

初始化调用次数及后续冷启动行为以对应平台文档为准。不要通过更换 ClientID 并重新初始化来关联业务账号；业务账号应使用对应平台的用户属性方法记录。

## 3. 验证事件入库 [#3-验证事件入库]

在后台 [事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 开启“加载实时数据”，按测试 ClientID 筛选，再逐项触发实际业务操作。

| 验收项  | 核对内容                                              |
| ---- | ------------------------------------------------- |
| 事件   | 应采集的事件均出现，事件名和触发次数符合预期；无需的业务事件不必为验收额外接入           |
| 用户   | 事件归属当前测试用户，客户端和服务端事件没有落到两个 ClientID 下             |
| 时间   | 使用实际事件时间；事件采集 `time` 为毫秒时间戳，常规实时上报不启用 `time_free` |
| 属性   | 必填属性完整，数据类型与元数据定义一致；错误数据页面没有相关校验错误                |
| 付费   | 使用测试订单验证，金额单位为分，例如 6 元传 600；订单号准确，客户端/服务端的上报职责已明确 |
| 广告观看 | 如有广告变现业务，核对广告平台、广告位和 eCPM；以对应 SDK 文档要求的单位传入       |
| 用户属性 | 更新后值符合预期；累加、首次设置、清空等操作分别验证，避免误用删除全部属性的方法          |

接口返回 `code=0` 后仍需核对入库结果。报表可能有更新延迟，不应仅凭报表尚未出现数据就重复补报。

## 4. 验证归因与媒体回传 [#4-验证归因与媒体回传]

1. 创建独立的联调推广活动，避免使用正在投放的活动进行试验。
2. 按 [归因联调指南](/docs/attribution/integration-testing) 核对点击记录、设备标识或启动参数、初始化时间、窗口期及归因结果。
3. 如需向自有业务系统接收结果，按用途选择 [归因回调](/docs/attribution/attribution-callback) 或 [事件回调](/docs/attribution/event-callback)，核对实际请求和服务端响应。
4. 如需向广告媒体回传转化，单独核对媒体回传状态；事件已入库或已收到业务回调，不能代替媒体回传验收。
5. 按媒体和事件核对所有回传来源，确认引力回传、媒体 SDK 与自有 API 没有重复上报同一转化。

## 5. 常见问题排查顺序 [#5-常见问题排查顺序]

| 现象           | 优先排查                                                                              |
| ------------ | --------------------------------------------------------------------------------- |
| 初始化失败        | 当前应用 Access Token、必填参数、ClientID、网络权限及国内/海外节点是否匹配                                  |
| 初始化成功但看不到事件  | 是否已触发事件、是否按当前 ClientID 筛选、SDK 是否仍在缓存、网络请求是否发出；再查看事件流的错误数据                         |
| 事件出现在错误数据中   | 事件和属性是否已配置，名称、必填字段和数据类型是否符合 [数据规则](/docs/getting-started/data-rules)              |
| 服务端上报失败      | 客户端是否已初始化成功，应用与 ClientID 是否一致，`event_list` 结构、毫秒时间戳及 `properties.$lib="api"` 是否正确 |
| OpenAPI 验签失败 | 是否使用开发者应用 `app_key`，是否按实际请求体重新生成 `sign` 和 `Authorization`，是否误用了后台登录 Token         |
| 事件正常但归因为自然量  | 是否收到有效点击，标识符或启动参数能否匹配，是否在有效窗口内；不要先通过反复换 ClientID 或补造点击数据排查                        |
| 付费或 ROI 异常   | 金额单位、订单号、事件次数、重复回传以及报表的时间范围和更新频率                                                  |
| 小游戏广告收入未出现   | 广告观看事件、平台 Token 接入模式及有效性、对应报表的更新时间                                                |

## 6. 上线交接与获取支持 [#6-上线交接与获取支持]

上线前记录已通过的验收项及未使用的功能，按少量投放验证后再扩大投放的顺序推进。测试开关和日志级别按对应 SDK 文档调整。

如仍有问题，请向引力运营或技术支持提供：应用 ID、平台及 SDK 版本、ClientID、问题发生时间及所在时区、预期结果与实际结果、脱敏后的请求/响应和错误日志。归因问题另附推广活动 ID、媒体名称、点击时间及设备标识类型；订单问题另附测试订单号与金额单位。

请勿在公开问题单中附上完整 Access Token、`app_key`、AppSecret 或 `Authorization`；设备标识及用户信息按必要范围脱敏。