docs: 文档更新

聚合SDK/ZySdk对接文档(v1.2.0.6).md → 聚合SDK/ZySdk对接文档(v1.2.0.9).md

-# Game Center SDK 接入说明
+# Game Center SDK 接入说明
 # Game Center SDK 接入说明
 
-本文档面向 **准备接入本聚合 SDK 的 Android 客户端开发人员**，说明当前 SDK 的对外接口、传参字段和回调方法。
+> 当前文档版本：`v1.2.0.9`
+
+本文档面向 **准备接入本聚合 SDK 的 Android 客户端开发人员**，说明当前 SDK 的对外接口、传参字段、统一回调格式和错误码规范。
 
 ## 目录
 
@@ -36,21 +38,24 @@
 - SDK 角色信息上报
 - SDK 行为上报
 - SDK 支付
-- SDK 激励广告
+- SDK 平台激励广告接入（OPPO / vivo / Xiaomi / Huawei / Honor）
 - SDK 退出引导
 - SDK 全局事件监听
 - 统一方法入口接入
+- 统一出参格式
+- 统一错误码映射
 
 ---
 
 <a name="overview-changelog"></a>
 ### 2. 更新内容
 
-- `1.2.0.4`
-- 对外接入方式统一收口到 `ZySdk.callSdkMethod(...)`
+- `1.2.0.9`
+- 新增并统一平台广告接入说明，当前支持 `OPPO / vivo / Xiaomi / Huawei / Honor` 激励广告能力
+- 对外回调结果统一收口为固定根结构：`success / msg / errorCode / channelCode / data / ext`
+- 错误码统一按 SDK 标准化 9 位错误码对外返回，渠道原始错误码由 SDK 内部映射处理
+- `showAd`、广告事件、全局监听说明按当前实现更新，统一按 Android 对接口径描述
 - `sdkInit`、`sdkLogin`、`sdkPay` 等 `sdkXxx` 方式继续兼容保留
-- 文档统一按 Android 对接口径描述
-- 完善 `ISdkEventListener` 全局事件与广告事件说明
 
 ---
 
@@ -254,7 +259,7 @@ plugins {
 |---|---|
 | 回调接口 | `ZySdkCallback` |
 | 接口定义 | `fun onResult(result: String)` |
-| 返回值 | `result` 为 SDK 统一 JSON 字符串 |
+| 返回值 | `result` 为 SDK 统一 JSON 字符串，固定根结构为 `success / msg / errorCode / channelCode / data / ext` |
 
 ---
 
@@ -307,16 +312,18 @@ ZySdk.callSdkMethod(
 |:-----------:|:----------:|:----------:|:--------:|
 | `success` | Boolean | 是 | 接口调用是否成功 |
 | `msg` | String | 是 | 状态说明；成功时如未显式返回，SDK 默认补 `SUCCESS` |
-| `errorCode` | String | 是 | SDK 对外统一错误码；成功固定为 `1` |
+| `errorCode` | Int | 是 | SDK 对外统一错误码；成功固定为 `1` |
 | `channelCode` | String | 否 | 当前渠道编码，多渠道场景下用于标识当前渠道 |
-| `ext` | JsonObject | 否 | 扩展字段，非核心信息统一放在该对象内 |
 | `data` | JsonObject | 是 | 核心业务数据；无业务数据时固定返回 `{}` |
+| `ext` | JsonObject | 否 | 扩展字段，非核心信息统一放在该对象内；无扩展数据时通常返回 `{}` |
 
 **错误码说明**
 
-- 对外文档仅说明 SDK 统一错误码体系
-- 渠道原始错误码由 SDK 内部完成映射和兼容处理，不对接入方透出
-- 具体错误码取值与场景定义以平台侧提供的统一错误码规范为准
+- 对外统一返回 **标准化 9 位错误码**
+- 错误码按 `渠道编号 + 错误分类编号 + 4 位流水号` 进行归一
+- 渠道原始错误码由 SDK 内部完成映射和兼容处理，不作为对外长期协议字段
+- 未初始化、参数缺失等 SDK 自身前置校验失败，也会优先按对应分类返回标准错误信息
+- 具体映射明细可参考 SDK 内维护的错误码清单文档
 
 ---
 
@@ -347,10 +354,10 @@ ZySdk.callSdkMethod(
 |-----------------------------------|:----------:|:----------------------:|
 | `success` | Boolean | 是否成功 |
 | `msg` | String | 状态信息，必传 |
-| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `errorCode` | Int | SDK 对外统一错误码，成功固定为 `1` |
 | `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
 | `data` | JsonObject | 登录核心数据；无数据时返回 `{}` |
+| `ext` | JsonObject | 扩展字段 |
 | &emsp;&emsp;member_id | String | 用户 ID |
 | &emsp;&emsp;player_id | String | 玩家 ID |
 | &emsp;&emsp;username | String | 用户名 |
@@ -451,10 +458,10 @@ ZySdk.callSdkMethod(
 |:-----------:|:-------:|:--------:|
 | `success` | Boolean | 是否成功 |
 | `msg` | String | 返回说明，必传 |
-| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `errorCode` | Int | SDK 对外统一错误码，成功固定为 `1` |
 | `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
 | `data` | JsonObject | 角色上报结果数据；无数据时返回 `{}` |
+| `ext` | JsonObject | 扩展字段 |
 
 ---
 
@@ -551,10 +558,10 @@ ZySdk.callSdkMethod(
 |:-----------:|:-------:|:--------:|
 | `success` | Boolean | 是否成功 |
 | `msg` | String | 返回说明，必传 |
-| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `errorCode` | Int | SDK 对外统一错误码，成功固定为 `1` |
 | `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
 | `data` | JsonObject | 行为上报结果数据；无数据时返回 `{}` |
+| `ext` | JsonObject | 扩展字段 |
 
 ---
 
@@ -655,10 +662,10 @@ ZySdk.callSdkMethod(
 |:-----------:|:-------:|:--------:|
 | `success` | Boolean | 是否成功 |
 | `msg` | String | 返回说明，必传 |
-| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `errorCode` | Int | SDK 对外统一错误码，成功固定为 `1` |
 | `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
 | `data` | JsonObject | 支付结果核心数据；无数据时返回 `{}` |
+| `ext` | JsonObject | 扩展字段 |
 
 `data` 中可能包含订单标识、签名串、回传透传字段等支付结果信息，具体以平台侧对接文档和服务端约定为准；渠道原始字段名和原始状态码不作为对外长期协议。
 
@@ -669,6 +676,14 @@ ZySdk.callSdkMethod(
 
 当前对外广告能力统一走 `showAd`。
 
+**平台广告接入说明**
+
+- 当前 SDK 已统一接入 `OPPO / vivo / Xiaomi / Huawei / Honor` 平台激励广告能力
+- 接入方无需区分不同广告平台的加载、展示、预加载细节，只需按场景传入 `sceneId`
+- SDK 内部会根据当前渠道包完成广告配置拉取、广告 SDK 初始化、预加载、展示和事件分发
+- 当前渠道包只会包含对应平台广告能力，不会跨渠道加载其它平台 `RewardManager`
+- 广告对外事件、错误码和结果结构统一收口，接入方按统一协议处理即可
+
 **推荐调用方式**
 
 | 项 | 说明 |
@@ -732,16 +747,38 @@ ZySdk.callSdkMethod(
 |---|---|---|
 | `success` | Boolean | 是否成功 |
 | `msg` | String | 返回说明，必传 |
-| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `errorCode` | Int | SDK 对外统一错误码，成功固定为 `1` |
 | `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 广告扩展字段 |
+| `data` | JsonObject | 广告结果核心数据；无数据时返回 `{}` |
 | &emsp;&emsp;eventType | String | 广告事件类型 |
 | &emsp;&emsp;sceneId | String | 广告场景 ID |
 | &emsp;&emsp;placementId | String | 广告位 ID |
-| `data` | JsonObject | 广告结果核心数据；无数据时返回 `{}` |
+| `ext` | JsonObject | 广告扩展字段 |
 
 > 广告失败场景的渠道原始错误原因由 SDK 内部兼容处理，对外统一按 SDK 错误码体系返回。
 
+**`eventType` 说明**
+
+- `eventType` 是广告事件的统一事件名
+- 若使用统一入口 `callSdkMethod(activity, "showAd", paramJson, null)`，广告事件通过 `ISdkEventListener` 分发
+- 对 `ISdkEventListener` 而言，`data.eventType` 的值会对应触发同名广告方法
+- 例如 `eventType = "onAdPlayReward"` 时，会回调 `ISdkEventListener.onAdPlayReward(resultJson)`
+
+| `eventType` | `ISdkEventListener` 对应方法 |
+|---|---|
+| `onAdSubscribeFail` | `onAdSubscribeFail(resultJson)` |
+| `onAdPlayFailed` | `onAdPlayFailed(resultJson)` |
+| `onAdPlayReward` | `onAdPlayReward(resultJson)` |
+| `onAdOpen` | `onAdOpen(resultJson)` |
+| `onAdClick` | `onAdClick(resultJson)` |
+| `onAdImpression` | `onAdImpression(resultJson)` |
+| `onAdClose` | `onAdClose(resultJson)` |
+| `onAdPlayBegin` | `onAdPlayBegin(resultJson)` |
+| `onAdPlayEnd` | `onAdPlayEnd(resultJson)` |
+| `onAdDataEmpty` | `onAdDataEmpty(resultJson)` |
+| `onAdPreloadReady` | `onAdPreloadReady(resultJson)` |
+| `onAdReportFail` | `onAdReportFail(resultJson)` |
+
 ---
 
 <a name="quickstart-exit"></a>
@@ -793,10 +830,10 @@ ZySdk.callSdkMethod(
 |:-----------:|:-------:|:--------:|
 | `success` | Boolean | 是否成功 |
 | `msg` | String | 返回说明，必传 |
-| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `errorCode` | Int | SDK 对外统一错误码，成功固定为 `1` |
 | `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
 | `data` | JsonObject | 检查升级结果数据；无数据时返回 `{}` |
+| `ext` | JsonObject | 扩展字段 |
 
 ---
 
@@ -894,5 +931,7 @@ ZySdk.callSdkMethod(
 - `ZySdkCallback` 仍作为统一业务回调接口使用，接口定义为 `fun onResult(result: String)`
 - `ZyAdCallback` 仍作为单次 `showAd(...)` 的广告回调接口使用
 - `resultJson` 与 `result` 均为 SDK 统一 JSON 字符串结构
+- 对 `ISdkEventListener` 而言，SDK 会先读取 `resultJson` 里的 `data.eventType`，再分发到对应的同名广告方法
+- 例如 `data.eventType = "onAdOpen"` 时，会触发 `onAdOpen(resultJson)`
 
 ---