AI-ready documentation
接入验收与排错
按准备、初始化、事件入库、归因联调和上线五个阶段验收 Gravity Engine 接入，提供常见故障的排查顺序与支持信息清单。
代码集成完成后，请用测试用户走完本页流程。初始化成功、事件入库、广告归因成功和媒体回传成功是不同的验收项，应分别确认。
1. 准备接入信息
| 检查项 | 通过标准 |
|---|---|
| 应用与环境 | 明确测试使用的引力应用 ID、目标平台、SDK 版本及国内/海外节点；测试数据与正式数据的归属已确认 |
| 接入方式 | 已按 SDK 总览 选择技术栈；服务端补充上报时已阅读 混合上报模式 |
| 凭证 | SDK/事件采集使用引力应用 Access Token；OpenAPI 使用开发者应用 app_key；微信/抖音平台 Token 与两者分别管理 |
| 采集方案 | 明确事件名、触发时机、属性类型、金额单位和上报端；自定义事件及属性已在后台配置 |
| 用户标识 | 客户端与服务端使用同一引力应用、同一 ClientID，业务登录后不会随意切换标识 |
| 权限与网络 | 已按对应平台文档配置网络权限及合法域名，并确认 SDK 的启动时机符合项目的隐私授权流程 |
2. 验证初始化
- 按对应平台快速集成文档配置 SDK，区分启动配置
setupAndStart和用户初始化initialize。 - 观察初始化成功回调或返回结果；发生异常时先排查错误，不继续发送依赖初始化的事件。
- 记录本次测试的应用 ID、SDK 版本、ClientID 和初始化时间，用同一个 ClientID 核对后续数据。
- 如需服务端上报，先把客户端初始化成功后的 ClientID 传给业务服务端，再触发上报。
初始化调用次数及后续冷启动行为以对应平台文档为准。不要通过更换 ClientID 并重新初始化来关联业务账号；业务账号应使用对应平台的用户属性方法记录。
3. 验证事件入库
在后台 事件流 开启“加载实时数据”，按测试 ClientID 筛选，再逐项触发实际业务操作。
| 验收项 | 核对内容 |
|---|---|
| 事件 | 应采集的事件均出现，事件名和触发次数符合预期；无需的业务事件不必为验收额外接入 |
| 用户 | 事件归属当前测试用户，客户端和服务端事件没有落到两个 ClientID 下 |
| 时间 | 使用实际事件时间；事件采集 time 为毫秒时间戳，常规实时上报不启用 time_free |
| 属性 | 必填属性完整，数据类型与元数据定义一致；错误数据页面没有相关校验错误 |
| 付费 | 使用测试订单验证，金额单位为分，例如 6 元传 600；订单号准确，客户端/服务端的上报职责已明确 |
| 广告观看 | 如有广告变现业务，核对广告平台、广告位和 eCPM；以对应 SDK 文档要求的单位传入 |
| 用户属性 | 更新后值符合预期；累加、首次设置、清空等操作分别验证，避免误用删除全部属性的方法 |
接口返回 code=0 后仍需核对入库结果。报表可能有更新延迟，不应仅凭报表尚未出现数据就重复补报。
4. 验证归因与媒体回传
- 创建独立的联调推广活动，避免使用正在投放的活动进行试验。
- 按 归因联调指南 核对点击记录、设备标识或启动参数、初始化时间、窗口期及归因结果。
- 如需向自有业务系统接收结果，按用途选择 归因回调 或 事件回调，核对实际请求和服务端响应。
- 如需向广告媒体回传转化，单独核对媒体回传状态；事件已入库或已收到业务回调，不能代替媒体回传验收。
- 按媒体和事件核对所有回传来源，确认引力回传、媒体 SDK 与自有 API 没有重复上报同一转化。
5. 常见问题排查顺序
| 现象 | 优先排查 |
|---|---|
| 初始化失败 | 当前应用 Access Token、必填参数、ClientID、网络权限及国内/海外节点是否匹配 |
| 初始化成功但看不到事件 | 是否已触发事件、是否按当前 ClientID 筛选、SDK 是否仍在缓存、网络请求是否发出；再查看事件流的错误数据 |
| 事件出现在错误数据中 | 事件和属性是否已配置，名称、必填字段和数据类型是否符合 数据规则 |
| 服务端上报失败 | 客户端是否已初始化成功，应用与 ClientID 是否一致，event_list 结构、毫秒时间戳及 properties.$lib="api" 是否正确 |
| OpenAPI 验签失败 | 是否使用开发者应用 app_key，是否按实际请求体重新生成 sign 和 Authorization，是否误用了后台登录 Token |
| 事件正常但归因为自然量 | 是否收到有效点击，标识符或启动参数能否匹配，是否在有效窗口内；不要先通过反复换 ClientID 或补造点击数据排查 |
| 付费或 ROI 异常 | 金额单位、订单号、事件次数、重复回传以及报表的时间范围和更新频率 |
| 小游戏广告收入未出现 | 广告观看事件、平台 Token 接入模式及有效性、对应报表的更新时间 |
6. 上线交接与获取支持
上线前记录已通过的验收项及未使用的功能，按少量投放验证后再扩大投放的顺序推进。测试开关和日志级别按对应 SDK 文档调整。
如仍有问题，请向引力运营或技术支持提供：应用 ID、平台及 SDK 版本、ClientID、问题发生时间及所在时区、预期结果与实际结果、脱敏后的请求/响应和错误日志。归因问题另附推广活动 ID、媒体名称、点击时间及设备标识类型；订单问题另附测试订单号与金额单位。
请勿在公开问题单中附上完整 Access Token、app_key、AppSecret 或 Authorization；设备标识及用户信息按必要范围脱敏。