渠道常见问题解答

本文档面向渠道发行商、应用渠道、Web 渠道和使用安卓 SDK 的接入方，整理接入、联调、上线、追踪、数据和结算过程中的常见问题。

1. 文档与接入方式

1.1 我应该选择 OpenAPI-V4 还是安卓 SDK？

如果渠道需要自定义 UI、跨端复用、服务端聚合、多游戏位请求或精细控制缓存和渲染逻辑，建议使用游戏位OpenAPI-V4对接文档。

如果渠道是安卓应用，并且希望快速集成标准游戏位组件，建议使用游戏位-安卓SDK文档。SDK 已封装初始化、游戏位加载、组件渲染、点击打开和曝光追踪等基础能力。

1.2 新项目还能使用旧版商户平台 OpenAPI 吗？

新项目请使用 OpenAPI-V4 或安卓 SDK。商户平台旧版OpenAPI旧版未来会停止服务。

1.3 游戏位接口和安卓 SDK 能同时使用吗？

可以，但不建议在同一个展示位置混用两套接入方式。通常做法是：

标准安卓原生页面使用安卓 SDK。
Web、WebView、小程序或自定义 UI 页面使用 OpenAPI-V4。
同一页面内如果同时存在两种接入方式，需要确保游戏位 ID、曝光追踪和点击追踪不会重复计算。

2. 凭证与环境

2.1 `client_id`、`api_key` 、`secret_key` 和 `slot_id` 分别是什么？

client_id 是渠道或商户的唯一标识，api_key secret_key 是接口签名密钥，slot_id 是具体游戏位标识。它们通常由 MiniGame 分配，并按测试环境和正式环境隔离。

2.2 测试环境和正式环境的参数可以混用吗？

不可以。测试环境的地址、凭证和游戏位 ID 仅用于开发联调。正式上线前需要切换为正式环境参数，并确认包体、服务端配置、缓存配置和运营后台配置均已同步切换。

2.3 `api_key` `secret_key` 可以放在客户端吗？

对于 OpenAPI-V4 而言，游戏位相关请求需要使用api_key 对请求签名，并由客户端直连，如APP被逆向可能存在密钥泄露风险，如有需求可通过密钥轮换机制降低风险。

secret_key 用于S2S服务端之间通信使用，绝对不可以放在客户端，如果泄露，请及时通过密钥轮换机制降低风险。

安卓 SDK 的初始化参数应按照 SDK 文档和商务分配方式配置，正式参数不要暴露在公开文档、日志或可被普通用户读取的位置。

2.4 签名失败通常是什么原因？

常见原因包括：

请求方法、请求路径、时间戳或请求体参与签名的内容与实际请求不一致。
请求体序列化后字段顺序、空值处理或编码方式发生变化。
时间戳超出允许窗口。
使用了错误环境的 client_id 或 api_key。
代理、网关或客户端 SDK 修改了请求体。

建议先固定一组请求体，在服务端打印待签名字符串、请求路径、时间戳和请求体摘要，与文档中的签名规则逐项比对。

3. 游戏位请求

3.1 一次请求可以获取多个游戏位吗？

OpenAPI-V4 支持一次请求多个游戏位，适合首页、详情页、推荐区等多个位置同时请求，减少网络往返。单次请求的游戏位数量应遵守接口文档限制，超过限制需要拆分请求。

3.2 接口返回成功但某个游戏位没有游戏怎么办？

可能原因包括：

slot_id 未配置或配置未生效。
当前国家、语言、屏幕方向或设备条件下没有可推荐内容。
游戏位策略、运营规则或库存限制导致无结果。
请求参数缺失，导致推荐服务无法命中合适内容。

处理建议：

确认 slot_id 是否属于当前 client_id。
补充 language、country、设备类型、屏幕方向等上下文信息。
记录 request_id 并提供给 MiniGame 支持排查。
前端需要准备空态兜底，避免页面布局异常。

3.3 游戏列表可以缓存吗？

可以做短时缓存，但需要注意：

不要缓存过长时间，否则会影响推荐实时性和运营策略生效。
响应中的追踪 URL 有有效期，过期后继续使用会导致追踪失败。
缓存命中时仍需确保曝光、可见性和点击事件按实际用户行为触发。
不建议跨用户复用包含个性化推荐结果和追踪参数的完整响应。

3.4 游戏链接可以自行拼接或修改吗？

不建议。响应中的游戏链接通常已经包含必要参数。渠道侧如需追加自有参数，应先确认不会破坏 MiniGame 参数、签名、归因和跳转逻辑。更稳妥的方式是通过双方约定的扩展字段或渠道配置处理。

3.5 如何处理接口超时或服务异常？

建议采用降级策略：

设置合理的请求超时时间，避免阻塞页面主流程。
对临时失败做有限重试，重试间隔应避免集中打满服务。
使用上一批短时缓存内容或展示空态。
记录状态码、业务错误码、request_id、请求耗时和渠道侧用户环境。

4. 事件追踪

4.1 曝光、可见性和点击追踪分别什么时候触发？

曝光追踪应在游戏卡片进入可视区域时触发；可见性追踪应在卡片连续可见超过指定时间后触发；点击追踪应在用户点击游戏卡片或按钮时触发。

OpenAPI-V4 响应中会返回对应的 trackers URL，客户端按实际行为发起请求即可。安卓 SDK 组件通常会内置曝光和点击追踪逻辑，接入方不需要重复上报。

4.2 追踪 URL 需要签名吗？

单条追踪 URL 已经预签名，客户端无需重新签名，也不应修改 URL 参数。直接发起请求即可。

如果使用批量追踪 API，则需要按照接口文档进行签名认证。

4.3 追踪失败会影响用户打开游戏吗？

不应影响。追踪失败应静默处理，不能阻断游戏打开、页面展示或用户操作。但渠道侧需要记录必要日志，方便后续排查曝光、点击和收入数据异常。

4.4 同一个游戏可以重复上报曝光吗？

同一个 imp_id 的同类型事件应避免重复上报。推荐按 imp_id 和事件类型做本地去重。页面刷新或重新请求游戏位后会产生新的追踪上下文，应以新的响应为准。

4.5 页面关闭时还有未发送的追踪怎么办？

Web 或 WebView 场景可使用浏览器支持的轻量发送能力处理页面卸载前的事件；安卓 SDK 场景按 SDK 的缓存和定时上报机制处理。无论哪种方式，追踪失败都不应阻塞用户离开页面。

5. 安卓 SDK

5.1 SDK 初始化应该放在哪里？

建议在 Application 或首个承载游戏位的 Activity 中尽早完成初始化，确保加载游戏位前已经设置环境、渠道凭证和用户标识。

5.2 SDK 环境应该如何配置？

开发和联调阶段使用测试环境；正式发版使用正式环境。需要特别注意构建类型、渠道包、灰度包和线上包不要误用测试环境参数。

5.3 SDK 已经处理曝光和点击后，还需要渠道自己上报吗？

标准 SDK 组件通常已经处理组件曝光、点击上报和打开游戏行为。渠道侧不应对同一个 SDK 组件重复调用 OpenAPI-V4 追踪 URL，否则会造成数据重复或口径不一致。

6. 数据与结算

6.1 为什么渠道侧曝光或点击数与 MiniGame 后台不完全一致？