docs: zysdk文档更新

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

+# Game Center SDK 接入说明
+# Game Center SDK 接入说明
+
+本文档面向 **准备接入本聚合 SDK 的 Android 客户端开发人员**，说明当前 SDK 的对外接口、传参字段和回调方法。
+
+## 目录
+
+- [一、SDK概述](#overview)
+  - [1. 主要功能](#overview-features)
+  - [2. 更新内容](#overview-changelog)
+  - [3. 接入准备](#overview-prereq)
+- [二、快速接入](#quickstart)
+  - [1. 添加 Maven 仓库](#quickstart-maven)
+  - [2. 添加 Gradle 依赖](#quickstart-deps)
+  - [3. 接入要求](#quickstart-resources)
+  - [4. SDK 初始化](#quickstart-init)
+  - [5. SDK 登录](#quickstart-login)
+  - [6. 角色信息上报](#quickstart-role)
+  - [7. 行为上报](#quickstart-behavior)
+  - [8. SDK 支付](#quickstart-pay)
+  - [9. 激励广告](#quickstart-ad)
+  - [10. 退出引导](#quickstart-exit)
+  - [11. 检查升级](#quickstart-update)
+  - [12. 显示/隐藏浮窗](#quickstart-float)
+  - [13. 全局事件监听](#quickstart-listener)
+
+---
+
+<a name="overview"></a>
+## 一、SDK概述
+
+<a name="overview-features"></a>
+### 1. 主要功能
+
+- SDK 初始化
+- SDK 登录
+- SDK 角色信息上报
+- SDK 行为上报
+- SDK 支付
+- SDK 激励广告
+- SDK 退出引导
+- SDK 全局事件监听
+- 统一方法入口接入
+
+---
+
+<a name="overview-changelog"></a>
+### 2. 更新内容
+
+- `1.2.0.4`
+- 对外接入方式统一收口到 `ZySdk.callSdkMethod(...)`
+- `sdkInit`、`sdkLogin`、`sdkPay` 等 `sdkXxx` 方式继续兼容保留
+- 文档统一按 Android 对接口径描述
+- 完善 `ISdkEventListener` 全局事件与广告事件说明
+
+---
+
+<a name="overview-prereq"></a>
+### 3. 接入准备
+
+正式接入前请务必阅读掌玩 SDK 接入流程介绍。对接时由平台方提供当前 SDK 所需参数，请严格以平台对接人员提供的参数文档为准。
+
+| 名称 | 说明 |
+|-------------|---------------------------|
+| `zyou_app_secret` | 游戏在平台的唯一标识（原 `game_id` 加密） |
+| `app_id` | 游戏在平台 / 渠道侧的应用标识 |
+| `app_status` | 用户在平台登录的投放媒体标识 |
+
+---
+
+<a name="quickstart"></a>
+## 二、快速接入
+
+<a name="quickstart-maven"></a>
+### 1. 添加 Maven 仓库
+
+#### Kotlin 项目
+
+在 `settings.gradle.kts` 或 `settings.gradle` 中添加如下仓库配置：
+
+```kotlin
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+        maven("https://developer.huawei.com/repo/")
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+
+    repositories {
+        google()
+        mavenCentral()
+        maven("https://jitpack.io")
+        maven("https://developer.huawei.com/repo/")
+
+        maven {
+            url = uri("http://nexus.zwwlkj01.top/repository/android-advertisement")
+            isAllowInsecureProtocol = true
+            credentials {
+                username = "admin"
+                password = "zwwl2021"
+            }
+        }
+
+        maven {
+            url = uri("http://nexus.zwwlkj01.top/repository/TencentAdq")
+            isAllowInsecureProtocol = true
+            credentials {
+                username = "admin"
+                password = "zwwl2021"
+            }
+        }
+
+        maven {
+            url = uri("http://nexus.zwwlkj01.top/repository/AdGameSdk")
+            isAllowInsecureProtocol = true
+            credentials {
+                username = "admin"
+                password = "zwwl2021"
+            }
+        }
+
+        maven {
+            url = uri("https://repos.xiaomi.com/maven")
+            credentials {
+                username = "mi-gamesdk"
+                password = "AKCp8mYeLuhuaGj6bK1XK7t2w4CsPuGwg6GpQdZ9cat7K59y5sD7Tx3dHjJcFrBGj3TQ4vi7g"
+            }
+        }
+
+        maven("https://artifact.bytedance.com/repository/Volcengine/")
+        maven("https://jfrog.takuad.com/artifactory/china_sdk")
+    }
+}
+```
+
+> 若只接广告能力，也请至少保留广告相关仓库与公司私服配置。若打华为包，还需保留华为 Maven 仓库。
+
+同时请在工程根目录 `gradle.properties` 中确认已开启：
+
+```properties
+android.useAndroidX=true
+android.enableJetifier=true
+```
+
+---
+
+<a name="quickstart-deps"></a>
+### 2. 添加 Gradle 依赖
+
+在 app 模块的 `build.gradle.kts` 或 `build.gradle` 的 `dependencies` 中增加：
+
+```kotlin
+implementation("com.zw.game.center:gameCenter:版本号")
+```
+
+> 版本号请以后续交付为准。
+
+#### 华为渠道（可选）
+
+若打华为包体并需 HMS / AGC 能力，可参考下面配置添加 `com.huawei.agconnect` 插件，并按华为应用联运 / 游戏服务文档配置 `agconnect-services.json` 等。
+
+工程级 `build.gradle.kts` 中加入：
+
+```kotlin
+buildscript {
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.13.2")
+        classpath("com.huawei.agconnect:agcp:1.9.5.302")
+    }
+}
+```
+
+app 模块添加插件：
+
+```kotlin
+plugins {
+    id("com.huawei.agconnect")
+}
+```
+
+> 非华为包可不启用。
+
+---
+
+<a name="quickstart-resources"></a>
+### 3. 接入要求
+
+当前 SDK 接入时，宿主只需要关注以下要求：
+
+- 所有正式 API 调用都要传入当前前台 `Activity`
+- `sdkInit()` 必须在用户同意隐私协议后调用
+- 当前 SDK 不要求宿主额外做资源代理
+- 新接入统一推荐走 `ZySdk.callSdkMethod(activity, methodName, paramJson, callback)`
+- 现有 `sdkInit`、`sdkLogin`、`sdkPay` 等 `sdkXxx` 方式继续兼容保留，但仅建议用于存量工程平滑迁移
+
+若宿主应用的 `AndroidManifest.xml` 中已显式声明 `android:allowBackup`，Manifest 合并时如与 SDK 配置冲突，可在宿主 `application` 节点补充。
+
+若宿主需要接入激励广告，建议同时在 `application` 或承载广告的 `Activity` 上开启硬件加速；如果统一在 `application` 节点配置，可参考下面写法：
+
+```xml
+<manifest
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <application
+        android:allowBackup="true"
+        android:hardwareAccelerated="true"
+        tools:replace="android:allowBackup"
+        ...>
+
+    </application>
+
+</manifest>
+```
+
+**统一调用入口**
+
+| 字段 | 类型 | 说明 |
+|:----------:|:--------:|:-------------------:|
+| `activity` | Activity | 当前前台 Activity |
+| `methodName` | String | 目标方法名 |
+| `paramJson` | String | 业务参数 JSON 字符串；无参数时可传 `null` |
+| `callback` | ZySdkCallback | 通用字符串回调，可传 `null` |
+
+**当前支持的 `methodName`**
+
+| methodName | 说明 |
+|---|---|
+| `sdkInit` | SDK 初始化 |
+| `sdkLogin` | SDK 登录 |
+| `sdkPay` | 常规支付 |
+| `sdkSinglePay` | OPPO 单机支付 |
+| `sdkReportRole` | 角色上报 |
+| `sdkBehaviorReport` | 行为上报 |
+| `showAd` | 激励广告 |
+| `sdkExit` | 退出游戏 |
+| `sdkUpdate` | 检查升级 |
+| `showFloatingBall` | 显示主悬浮球 |
+| `hideFloatingBall` | 隐藏主悬浮球 |
+| `showHuaweiFloat` | 显示华为浮标 |
+| `hideHuaweiFloat` | 隐藏华为浮标 |
+| `setDebug` | 设置调试开关 |
+| `clearCache` | 清空本地缓存 |
+| `getSdkUserInfo` | 获取当前用户信息 |
+| `hasPrivacyConsentAccepted` | 查询隐私同意状态 |
+
+**通用业务回调**
+
+| 项 | 说明 |
+|---|---|
+| 回调接口 | `ZySdkCallback` |
+| 接口定义 | `fun onResult(result: String)` |
+| 返回值 | `result` 为 SDK 统一 JSON 字符串 |
+
+---
+
+<a name="quickstart-init"></a>
+### 4. SDK 初始化
+
+在 Activity 进行初始化，且只初始化一次。必须在用户同意隐私协议后调用。
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "sdkInit", paramJson, callback)` |
+| `paramJson` | `{"showLoginBackgroundImage":false}` |
+| 回调 | `ZySdkCallback` |
+| 兼容方式 | `sdkInit(activity, showLoginBackgroundImage, callback)` |
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:----------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `showLoginBackgroundImage` | Boolean | 是否展示 SDK 登录背景图 |
+| `callback` | ZySdkCallback | 初始化结果回调 |
+
+**`paramJson` 示例**
+
+```kotlin
+val paramJson = JSONObject().apply {
+    put("showLoginBackgroundImage", false)
+}.toString()
+
+ZySdk.callSdkMethod(
+    this,
+    "sdkInit",
+    paramJson,
+    object : ZySdkCallback {
+        override fun onResult(result: String) {
+            Log.d("ZySdk", "sdkInit result=$result")
+        }
+    }
+)
+```
+
+**统一回参结构**
+
+所有 SDK 业务接口的回调结果都遵循同一根结构，根层不新增自定义字段。
+
+| 字段 | 类型 | 是否必传 | 含义 |
+|:-----------:|:----------:|:----------:|:--------:|
+| `success` | Boolean | 是 | 接口调用是否成功 |
+| `msg` | String | 是 | 状态说明；成功时如未显式返回，SDK 默认补 `SUCCESS` |
+| `errorCode` | String | 是 | SDK 对外统一错误码；成功固定为 `1` |
+| `channelCode` | String | 否 | 当前渠道编码，多渠道场景下用于标识当前渠道 |
+| `ext` | JsonObject | 否 | 扩展字段，非核心信息统一放在该对象内 |
+| `data` | JsonObject | 是 | 核心业务数据；无业务数据时固定返回 `{}` |
+
+**错误码说明**
+
+- 对外文档仅说明 SDK 统一错误码体系
+- 渠道原始错误码由 SDK 内部完成映射和兼容处理，不对接入方透出
+- 具体错误码取值与场景定义以平台侧提供的统一错误码规范为准
+
+---
+
+<a name="quickstart-login"></a>
+### 5. SDK 登录
+
+用于拉起渠道账号体系或聚合登录流程，成功返回参数请传给游戏服完成鉴权与建号。
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "sdkLogin", null, callback)` |
+| `paramJson` | 无，传 `null` 即可 |
+| 回调 | `ZySdkCallback` |
+| 兼容方式 | `sdkLogin(activity, callback)` |
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:---------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `callback` | ZySdkCallback | 登录结果回调 |
+
+**通用回参**
+
+| 字段 | 类型 | 含义 |
+|-----------------------------------|:----------:|:----------------------:|
+| `success` | Boolean | 是否成功 |
+| `msg` | String | 状态信息，必传 |
+| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `channelCode` | String | 当前渠道编码 |
+| `ext` | JsonObject | 扩展字段 |
+| `data` | JsonObject | 登录核心数据；无数据时返回 `{}` |
+| &emsp;&emsp;member_id | String | 用户 ID |
+| &emsp;&emsp;player_id | String | 玩家 ID |
+| &emsp;&emsp;username | String | 用户名 |
+| &emsp;&emsp;user_token | String | token，`#` 后为游戏 ID |
+| &emsp;&emsp;avatar | String | 头像 |
+| &emsp;&emsp;mobile | String | 手机号 |
+| &emsp;&emsp;has_identify | Boolean | 是否实名 |
+| &emsp;&emsp;need_identification | Int | `1` 强制实名，`2` 需要实名但不强制，`3` 不需要实名 |
+| &emsp;&emsp;has_mobile | Boolean | 是否绑定手机号 |
+| &emsp;&emsp;sdk_open_id | String | 抖音 `sdk_open_id` |
+
+> 登录失败时返回的 `errorCode` 为 SDK 统一错误码；渠道侧原始错误信息由 SDK 内部消化处理，不作为对外协议字段。
+
+---
+
+<a name="quickstart-role"></a>
+### 6. 角色信息上报
+
+在登录成功、切换角色等操作后需进行角色信息上报。
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "sdkReportRole", roleJson, callback)` |
+| `paramJson` | 直接传角色上报 JSON 字符串 |
+| 回调 | `ZySdkCallback` |
+| 兼容方式 | `sdkReportRole(activity, roleJson, callback)` |
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:-------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `roleJson` | String | 角色信息 JSON 字符串 |
+| `callback` | ZySdkCallback | 结果回调 |
+
+**`roleJson` 参数如下**
+
+| 字段名 | 类型 | 是否必填 | 字段说明 |
+|-----------------|:-------------------:|:----:|:-----------------------------------------------------------------------------------:|
+| `event` | String | 是 | 事件类型，`online/create/level_up/offline/other/delete` |
+| `server_id` | String | 是 | 服务器 ID |
+| `server_name` | String | 是 | 服务器名称 |
+| `cp_role_id` | String | 是 | 角色 ID |
+| `role_name` | String | 是 | 角色昵称 |
+| `role_level` | Int | 是 | 角色等级 |
+| `role_vip` | Int | 是 | 角色 VIP 等级 |
+| `combat_num` | String | 否 | 角色战力 |
+| `online_time` | String | 否 | 本次在线时长 |
+| `attack` | String | 否 | 攻击力 |
+| `profession` | String | 否 | 职业 |
+| `gang_name` | String | 否 | 帮会（行会）名称 |
+| `trans_level` | String | 否 | 转生等级 |
+| `sponsor_level` | String | 否 | 赞助等级 / 会员等级 |
+| `reiki_num` | String | 否 | 灵符值，默认 `0` |
+| `chapter_index` | String | 否 | 关卡章节 |
+| `ext` | Map<String, Number> | 否 | 扩展字段，字段个数不超过 10 个，字段名长度不超过 18 个字节，字段值必须为数字类型 |
+| `playerId` | String | 否 | 华为玩家 `playerId` |
+
+**`roleJson` 示例**
+
+```kotlin
+val roleJson = JSONObject().apply {
+    put("event", "other")
+    put("server_id", "12345678")
+    put("server_name", "server_demo")
+    put("cp_role_id", "demo_role_1")
+    put("role_name", "role_demo")
+    put("role_level", "83")
+    put("role_vip", "0")
+    put("combat_num", "25564")
+    put("online_time", "15426")
+    put("attack", "1024")
+    put("profession", "mage")
+    put("gang_name", "guild_demo")
+    put("trans_level", "5")
+    put("sponsor_level", "12")
+    put("reiki_num", "0")
+    put("chapter_index", "1")
+}.toString()
+
+ZySdk.callSdkMethod(
+    this,
+    "sdkReportRole",
+    roleJson,
+    object : ZySdkCallback {
+        override fun onResult(result: String) {
+            Log.d("ZySdk", "sdkReportRole result=$result")
+        }
+    }
+)
+```
+
+**回参**
+
+| 字段 | 类型 | 含义 |
+|:-----------:|:-------:|:--------:|
+| `success` | Boolean | 是否成功 |
+| `msg` | String | 返回说明，必传 |
+| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `channelCode` | String | 当前渠道编码 |
+| `ext` | JsonObject | 扩展字段 |
+| `data` | JsonObject | 角色上报结果数据；无数据时返回 `{}` |
+
+---
+
+<a name="quickstart-behavior"></a>
+### 7. 行为上报
+
+`sdkBehaviorReport(...)` 用于角色行为埋点或道具行为上报。
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "sdkBehaviorReport", behaviorJson, callback)` |
+| `paramJson` | 直接传行为上报 JSON 字符串 |
+| 回调 | `ZySdkCallback` |
+| 兼容方式 | `sdkBehaviorReport(activity, behaviorJson, callback)` |
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:-------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `behaviorJson` | String | 行为上报 JSON 字符串 |
+| `callback` | ZySdkCallback | 结果回调 |
+
+**`behaviorJson` 常用参数如下**
+
+| 字段名 | 类型 | 是否必填 | 字段说明 |
+|-----------------|:-------------------:|:----:|:------------------------------------------:|
+| `event` | String | 是 | 行为事件类型，例如 `item_cost`、`item_gain` |
+| `cp_role_id` | String | 是 | 游戏角色 ID |
+| `role_name` | String | 否 | 角色名 |
+| `querys` | JSONArray | 否 | 行为扩展字段数组 |
+
+**`behaviorJson` 示例**
+
+```kotlin
+val behaviorJson = JSONObject().apply {
+    put("event", "item_gain")
+    put("cp_role_id", "demo_role_1")
+    put("role_name", "role_demo")
+    put(
+        "querys",
+        JSONArray().apply {
+            put(JSONObject().apply {
+                put("name", "货币id")
+                put("value", "123")
+            })
+            put(JSONObject().apply {
+                put("name", "货币产出途径")
+                put("value", "掉落")
+            })
+            put(JSONObject().apply {
+                put("name", "变动前数量")
+                put("value", "59")
+            })
+            put(JSONObject().apply {
+                put("name", "变动数量")
+                put("value", "32")
+            })
+            put(JSONObject().apply {
+                put("name", "变动后数量")
+                put("value", "91")
+            })
+        }.toString()
+    )
+}.toString()
+
+ZySdk.callSdkMethod(
+    this,
+    "sdkBehaviorReport",
+    behaviorJson,
+    object : ZySdkCallback {
+        override fun onResult(result: String) {
+            Log.d("ZySdk", "sdkBehaviorReport result=$result")
+        }
+    }
+)
+```
+
+**回参**
+
+| 字段 | 类型 | 含义 |
+|:-----------:|:-------:|:--------:|
+| `success` | Boolean | 是否成功 |
+| `msg` | String | 返回说明，必传 |
+| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `channelCode` | String | 当前渠道编码 |
+| `ext` | JsonObject | 扩展字段 |
+| `data` | JsonObject | 行为上报结果数据；无数据时返回 `{}` |
+
+---
+
+<a name="quickstart-pay"></a>
+### 8. SDK 支付
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "sdkPay", payJson, callback)` |
+| `paramJson` | 直接传支付 JSON 字符串 |
+| 回调 | `ZySdkCallback` |
+| 兼容方式 | `sdkPay(activity, payJson, isSingle, callback)` |
+
+**兼容说明**
+
+- `sdkSinglePay` 为 OPPO 单机支付兼容方法
+- 若需走 OPPO 单机支付，统一入口请使用 `methodName = "sdkSinglePay"`
+- `sdkPay(...)` / `sdkSinglePay(...)` 旧方式继续保留，但新接入建议优先走统一入口
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:-------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `payJson` | String | 支付信息 JSON 字符串 |
+| `isSingle` | Boolean | 是否单机支付，仅 OPPO 兼容方式下使用 |
+| `callback` | ZySdkCallback | 结果回调 |
+
+**`payJson` 参数如下**
+
+| 字段名 | 类型 | 是否必填 | 字段说明 |
+|-----------------------------|:------:|:----:|:-----------------------:|
+| `order` | String | 是 | 订单信息 JSON |
+| &emsp;&emsp;cp_order_id | String | 是 | 游戏订单号，务必保证唯一 |
+| &emsp;&emsp;amount | Int | 是 | 消费总金额，单位为分（1 元 = 100） |
+| &emsp;&emsp;product_price | Int | 是 | 商品价格，单位为分 |
+| &emsp;&emsp;product_id | String | 是 | 商品 ID |
+| &emsp;&emsp;product_cnt | Int | 是 | 商品数量 |
+| &emsp;&emsp;product_name | String | 是 | 商品名，不能含 `+` 等特殊符号 |
+| &emsp;&emsp;product_desc | String | 是 | 商品描述，不能含 `+` 等特殊符号 |
+| &emsp;&emsp;ext | String | 否 | 订单额外信息 JSON 字符串 |
+| `role` | String | 是 | 角色信息 JSON |
+| &emsp;&emsp;event | String | 是 | 支付事件类型 |
+| &emsp;&emsp;server_id | String | 是 | 服务器 ID |
+| &emsp;&emsp;server_name | String | 是 | 服务器名称 |
+| &emsp;&emsp;cp_role_id | String | 是 | 角色 ID |
+| &emsp;&emsp;role_name | String | 是 | 角色昵称 |
+| &emsp;&emsp;role_level | String | 是 | 角色等级 |
+| &emsp;&emsp;role_vip | String | 是 | 角色 VIP 等级 |
+| &emsp;&emsp;role_id | String | 是 | 角色 ID |
+| `attach` | String | 否 | 自定义回调字段 |
+| `callbackUrl` | String | 否 | 游戏服务端回调地址 |
+| `priceType` | Int | 否 | 商品类型：`0` 消耗型，`1` 非消耗型，`2` 订阅型 |
+
+**`payJson` 示例**
+
+```kotlin
+val payJson = JSONObject().apply {
+    put("order", JSONObject().apply {
+        put("amount", "600")
+        put("cp_order_id", "no_channel_order_1001")
+        put("ext", "no_channel_ext")
+        put("product_cnt", "1")
+        put("product_desc", "无渠道支付验证")
+        put("product_id", "1")
+        put("product_name", "无渠道充值6元")
+        put("product_price", "600")
+        put("real_amount", "600")
+    })
+    put("role", JSONObject().apply {
+        put("cp_role_id", "no_channel_role_1")
+        put("event", "recharge")
+        put("role_level", "6")
+        put("role_name", "无渠道角色")
+        put("role_vip", "0")
+        put("server_id", "1")
+        put("server_name", "S.1")
+    })
+}.toString()
+
+ZySdk.callSdkMethod(
+    this,
+    "sdkPay",
+    payJson,
+    object : ZySdkCallback {
+        override fun onResult(result: String) {
+            Log.d("ZySdk", "sdkPay result=$result")
+        }
+    }
+)
+```
+
+**回参**
+
+| 字段 | 类型 | 含义 |
+|:-----------:|:-------:|:--------:|
+| `success` | Boolean | 是否成功 |
+| `msg` | String | 返回说明，必传 |
+| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `channelCode` | String | 当前渠道编码 |
+| `ext` | JsonObject | 扩展字段 |
+| `data` | JsonObject | 支付结果核心数据；无数据时返回 `{}` |
+
+`data` 中可能包含订单标识、签名串、回传透传字段等支付结果信息，具体以平台侧对接文档和服务端约定为准；渠道原始字段名和原始状态码不作为对外长期协议。
+
+---
+
+<a name="quickstart-ad"></a>
+### 9. 激励广告
+
+当前对外广告能力统一走 `showAd`。
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "showAd", paramJson, null)` |
+| `paramJson` | `{"sceneId":"场景ID"}` |
+| 事件接收 | 统一入口场景下，广告事件通过 `ISdkEventListener` 接收 |
+| 兼容方式 | `showAd(activity, sceneId, callback)` |
+
+**说明**
+
+- SDK 内部会在初始化后处理广告配置拉取、广告 SDK 初始化和预加载
+- 接入方只需要传入要播放的 `sceneId`
+- 单次广告回调走 `ZyAdCallback`
+- 全局广告事件会同步分发给 `ISdkEventListener`
+- 激励广告播放页面需开启硬件加速，建议宿主在 `application` 或承载广告的 `Activity` 上显式配置 `android:hardwareAccelerated="true"`
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:-------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `sceneId` | String | 广告场景 ID |
+| `callback` | ZyAdCallback | 单次广告事件回调 |
+
+**`paramJson` 示例**
+
+```kotlin
+val paramJson = JSONObject().apply {
+    put("sceneId", "b1s8")
+}.toString()
+
+ZySdk.callSdkMethod(
+    this,
+    "showAd",
+    paramJson,
+    null,
+)
+```
+
+**`ZyAdCallback` 支持的方法**
+
+| 方法名 | 说明 |
+|---|---|
+| `onAdSubscribeFail(resultJson)` | 广告订阅 / 请求 / 初始化失败 |
+| `onAdPlayFailed(resultJson)` | 广告播放失败 |
+| `onAdPlayReward(resultJson)` | 广告激励发放成功 |
+| `onAdOpen(resultJson)` | 广告打开 |
+| `onAdClick(resultJson)` | 广告点击 |
+| `onAdImpression(resultJson)` | 广告曝光 |
+| `onAdClose(resultJson)` | 广告关闭 |
+| `onAdPlayBegin(resultJson)` | 广告播放开始 |
+| `onAdPlayEnd(resultJson)` | 广告播放结束 |
+| `onAdDataEmpty(resultJson)` | 广告数据为空 |
+| `onAdPreloadReady(resultJson)` | 广告预加载成功 |
+| `onAdReportFail(resultJson)` | 广告收益上报失败 |
+
+**广告回调 `resultJson` 中常见字段**
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `success` | Boolean | 是否成功 |
+| `msg` | String | 返回说明，必传 |
+| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `channelCode` | String | 当前渠道编码 |
+| `ext` | JsonObject | 广告扩展字段 |
+| &emsp;&emsp;eventType | String | 广告事件类型 |
+| &emsp;&emsp;sceneId | String | 广告场景 ID |
+| &emsp;&emsp;placementId | String | 广告位 ID |
+| `data` | JsonObject | 广告结果核心数据；无数据时返回 `{}` |
+
+> 广告失败场景的渠道原始错误原因由 SDK 内部兼容处理，对外统一按 SDK 错误码体系返回。
+
+---
+
+<a name="quickstart-exit"></a>
+### 10. 退出引导
+
+在用户点击“退出游戏”等入口时调用。
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "sdkExit", null, null)` |
+| `paramJson` | 无，传 `null` 即可 |
+| 回调 | 无需依赖回调 |
+| 兼容方式 | `sdkExit(activity)` / `sdkExit(activity, callback)` |
+
+当前逻辑中：
+
+- 回调签名仅为兼容保留
+- 实际退出结果不再回调宿主
+- SDK 内部会统一处理退出弹窗、渠道退出与广告资源释放
+
+---
+
+<a name="quickstart-update"></a>
+### 11. 检查升级
+
+只需调用，若有更新，会弹出各渠道 SDK 自带的更新弹窗。
+
+**推荐调用方式**
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "sdkUpdate", null, callback)` |
+| `paramJson` | 无，传 `null` 即可 |
+| 回调 | `ZySdkCallback` |
+| 兼容方式 | `sdkUpdate(activity, callback)` |
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:-------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `callback` | ZySdkCallback | 结果回调 |
+
+**回参**
+
+| 字段 | 类型 | 含义 |
+|:-----------:|:-------:|:--------:|
+| `success` | Boolean | 是否成功 |
+| `msg` | String | 返回说明，必传 |
+| `errorCode` | String | SDK 对外统一错误码，成功固定为 `1` |
+| `channelCode` | String | 当前渠道编码 |
+| `ext` | JsonObject | 扩展字段 |
+| `data` | JsonObject | 检查升级结果数据；无数据时返回 `{}` |
+
+---
+
+<a name="quickstart-float"></a>
+### 12. 显示/隐藏浮窗
+
+#### 显示主悬浮球
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "showFloatingBall", null, callback)` |
+| `paramJson` | 无，传 `null` 即可 |
+| 回调 | `ZySdkCallback` |
+| 兼容方式 | `showFloatingBall(activity, callback)` |
+
+#### 隐藏主悬浮球
+
+| 项 | 说明 |
+|---|---|
+| 统一入口 | `callSdkMethod(activity, "hideFloatingBall", null, null)` |
+| `paramJson` | 无，传 `null` 即可 |
+| 回调 | 无 |
+| 兼容方式 | `hideFloatingBall()` |
+
+#### 华为渠道浮标
+
+| 方法 | 推荐调用方式 | 兼容方式 |
+|---|---|---|
+| 显示浮标 | `callSdkMethod(activity, "showHuaweiFloat", null, null)` | `showHuaweiFloat(activity)` |
+| 隐藏浮标 | `callSdkMethod(activity, "hideHuaweiFloat", null, null)` | `hideHuaweiFloat(activity)` |
+
+**参数**
+
+| 字段 | 类型 | 含义 |
+|:----------:|:--------:|:-------------------:|
+| `activity` | Activity | 当前 Activity 上下文 |
+| `callback` | ZySdkCallback | 结果回调，可选 |
+
+---
+
+### 12.1 获取渠道编码
+
+如果接入方需要判断当前渠道，推荐直接调用 `ZySdk.getChannelCode()`。
+
+说明：
+
+- `getChannelCode()` 返回的是 SDK 内部统一归一化后的渠道编码
+- 适合接入方做渠道判断、日志打印和分支处理
+- `ZySdk.getConfig("channel_code")` 仍然保留，但它读取的是打包脚本写入 `channel.properties` 的原始值
+- 若原始值带有后缀或扩展标识，建议优先使用 `getChannelCode()`
+
+<a name="quickstart-listener"></a>
+### 13. 全局事件监听
+
+`ISdkEventListener` 为 SDK 全局事件监听接口，继承 `IAdEventCallback`，除登录、隐私等全局业务事件外，也包含完整广告事件回调。
+
+**监听管理方法**
+
+| 方法 | 说明 |
+|---|---|
+| `ZySdk.setSdkEventListener(listener)` | 设置全局事件监听 |
+| `ZySdk.clearSdkEventListener()` | 清除全局事件监听 |
+
+**业务事件**
+
+| 方法名 | 说明 |
+|---|---|
+| `onLogin(userInfoJson)` | 登录成功回调 |
+| `onLogout()` | 登出 / Token 失效回调 |
+| `onSwitchAccount(userInfoJson)` | 切换账号成功回调 |
+| `onPasswordChanged()` | 修改密码成功回调 |
+| `onInitGameInfoReady(success)` | 游戏详情初始化完成回调 |
+| `onPrivacyConsentAccepted()` | 隐私弹窗点击同意 |
+| `onPrivacyConsentRejected()` | 隐私弹窗点击拒绝 |
+
+**广告事件**
+
+| 方法名 | 说明 |
+|---|---|
+| `onAdSubscribeFail(resultJson)` | 广告订阅 / 请求 / 初始化失败 |
+| `onAdPlayFailed(resultJson)` | 广告播放失败 |
+| `onAdPlayReward(resultJson)` | 广告激励发放成功 |
+| `onAdOpen(resultJson)` | 广告打开 |
+| `onAdClick(resultJson)` | 广告点击 |
+| `onAdImpression(resultJson)` | 广告曝光 |
+| `onAdClose(resultJson)` | 广告关闭 |
+| `onAdPlayBegin(resultJson)` | 广告播放开始 |
+| `onAdPlayEnd(resultJson)` | 广告播放结束 |
+| `onAdDataEmpty(resultJson)` | 广告数据为空 |
+| `onAdPreloadReady(resultJson)` | 广告预加载成功 |
+| `onAdReportFail(resultJson)` | 广告收益上报失败 |
+
+**补充说明**
+
+- `ZySdkCallback` 仍作为统一业务回调接口使用，接口定义为 `fun onResult(result: String)`
+- `ZyAdCallback` 仍作为单次 `showAd(...)` 的广告回调接口使用
+- `resultJson` 与 `result` 均为 SDK 统一 JSON 字符串结构
+
+---

聚合SDK/接入文档.md

-# Game Center SDK 接入说明
-# Game Center SDK 接入说明
-
-本文档面向 **准备接入本聚合 SDK 的 Android 客户端开发人员**，说明当前 SDK 的对外接口、传参字段和回调方法。
-
-## 目录
-
-- [一、SDK概述](#overview)
-  - [1. 主要功能](#overview-features)
-  - [2. 更新内容](#overview-changelog)
-  - [3. 接入准备](#overview-prereq)
-- [二、快速接入](#quickstart)
-  - [1. 添加 Maven 仓库](#quickstart-maven)
-  - [2. 添加 Gradle 依赖](#quickstart-deps)
-  - [3. 接入要求](#quickstart-resources)
-  - [4. SDK 初始化](#quickstart-init)
-  - [5. SDK 登录](#quickstart-login)
-  - [6. 角色信息上报](#quickstart-role)
-  - [7. 行为上报](#quickstart-behavior)
-  - [8. SDK 支付](#quickstart-pay)
-  - [9. 激励广告](#quickstart-ad)
-  - [10. 退出引导](#quickstart-exit)
-  - [11. 检查升级](#quickstart-update)
-  - [12. 显示/隐藏浮窗](#quickstart-float)
-  - [13. 对外回调接口](#quickstart-listener)
-  - [14. Unity 接入](#quickstart-unity)
-- [三、示例代码位置](#samples)
-
----
-
-<a name="overview"></a>
-## 一、SDK概述
-
-<a name="overview-features"></a>
-### 1. 主要功能
-    
-* SDK初始化
-* SDK登录
-* SDK角色信息上报
-* SDK行为上报
-* SDK支付
-* SDK激励广告
-* SDK退出引导
-* Unity 统一反射接入
-
----
-   
-<a name="overview-changelog"></a>
-### 2. 更新内容
-    
-* 版本更新至 `1.1.1.2`
-* 新增 `sdkBehaviorReport(...)`
-* 新增 `showAd(activity, sceneId, callback)`
-* 新增 `ZyAdCallback` 广告单次事件回调
-* 新增 `ISdkEventListener` 广告相关全局回调
-* 新增 `ZyUnitySupport` 统一 Unity 反射入口
-* 新增 `ZyUnitySupport.setSdkEventListener(...)`
-* 新增 `ZyUnitySupport.clearSdkEventListener()`
-* 悬浮球优化状态栏、导航栏、刘海区域避让，避免被系统栏遮挡
-* 新增广告上报埋点
-
----
-   
-<a name="overview-prereq"></a>
-### 3. 接入准备
-
-正式接入前请务必阅读掌玩SDK接入流程的介绍。对接时由平台方提供当前 SDK 所需参数，请严格以平台对接人员提供的参数文档为准。
-
-| 名称          | 说明                        |
-|-------------|---------------------------|
-| zyou_app_secret     | 游戏在平台的唯一标识（原 game_id 加密）。 |
-| app_id      | 游戏在平台/渠道侧的应用标识。           |
-| app_status  | 用户在平台登录的投放媒体标识。           |
-
----
-
-<a name="quickstart"></a>
-## 二、快速接入
-
-<a name="quickstart-maven"></a>
-### 1. 添加 Maven 仓库
-
-#### Kotlin项目
-
-在 **`settings.gradle.kts`** （Kotlin项目）或 **`settings.gradle`** （Java项目）中添加如下代码：
-
-```kotlin
-pluginManagement {
-    repositories {
-        google()
-        mavenCentral()
-        gradlePluginPortal()
-        maven("https://developer.huawei.com/repo/")
-    }
-}
-
-dependencyResolutionManagement {
-    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
-
-    repositories {
-        google()
-        mavenCentral()
-        maven("https://jitpack.io")
-        maven("https://developer.huawei.com/repo/")
-
-        maven {
-            url = uri("http://nexus.zwwlkj01.top/repository/android-advertisement")
-            isAllowInsecureProtocol = true
-            credentials {
-                username = "admin"
-                password = "zwwl2021"
-            }
-        }
-
-        maven {
-            url = uri("http://nexus.zwwlkj01.top/repository/TencentAdq")
-            isAllowInsecureProtocol = true
-            credentials {
-                username = "admin"
-                password = "zwwl2021"
-            }
-        }
-
-        maven {
-            url = uri("http://nexus.zwwlkj01.top/repository/AdGameSdk")
-            isAllowInsecureProtocol = true
-            credentials {
-                username = "admin"
-                password = "zwwl2021"
-            }
-        }
-
-        maven {
-            url = uri("https://repos.xiaomi.com/maven")
-            credentials {
-                username = "mi-gamesdk"
-                password = "AKCp8mYeLuhuaGj6bK1XK7t2w4CsPuGwg6GpQdZ9cat7K59y5sD7Tx3dHjJcFrBGj3TQ4vi7g"
-            }
-        }
-
-        maven("https://artifact.bytedance.com/repository/Volcengine/")
-        maven("https://jfrog.takuad.com/artifactory/china_sdk")
-    }
-}
-```
-
-> 以上为当前 SDK 工程使用的主要仓库；若只接广告能力，也请至少保留上面的广告相关仓库与公司私服配置。
->
-> 若打 **华为** 包，则需加入华为 Maven 库，以便下载华为插件。
-
-同时请在工程根目录 **`gradle.properties`** 中确认已开启：
-
-```properties
-android.useAndroidX=true
-android.enableJetifier=true
-```
-
----
-
-<a name="quickstart-deps"></a>
-### 2. 添加 Gradle 依赖
-
-在 **app 模块** `build.gradle.kts` 或 `build.gradle` 的 `dependencies` 中增加：
-
-```kotlin
-implementation("com.zw.game.center:gameCenter:版本号")
-```
-
-> 版本号请以后续交付为准。
-
-#### 华为渠道（可选）
-
-若打 **华为** 包体并需 HMS/AGC 能力，可参考下面代码添加 `com.huawei.agconnect` 插件，并按 **华为应用联运 / 游戏服务** 文档配置 `agconnect-services.json` 等。
-
-工程级 **`build.gradle.kts`** 中，加入
-```kotlin
-buildscript {
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.13.2")
-        classpath("com.huawei.agconnect:agcp:1.9.5.302")
-    }
-}
-```
-
-app 模块下添加 agc 插件
-```kotlin
-plugins {
-    id("com.huawei.agconnect")
-}
-```
-
-> 非华为包可不启用。
-
----
-
-<a name="quickstart-resources"></a>
-### 3. 接入要求
-
-当前 SDK 接入时，宿主只需要关注以下要求：
-
-- 所有正式 API 调用都要传入当前前台 `Activity`
-- `sdkInit()` 必须在用户同意隐私协议后调用
-- 当前 SDK 不要求宿主额外做资源代理
-- 登录、支付、广告、退出等能力统一通过 `ZySdk` 调用
-
-若宿主应用的 **`AndroidManifest.xml`** 中已显式声明 `android:allowBackup`，Manifest 合并时如与 SDK 配置冲突，可在宿主 `application` 节点补充：
-
-```xml
-<manifest
-    xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:tools="http://schemas.android.com/tools">
-
-    <application
-        android:allowBackup="true"
-        tools:replace="android:allowBackup"
-        ...>
-
-    </application>
-
-</manifest>
-```
-
----
-
-<a name="quickstart-init"></a>
-### 4. SDK初始化
-
-在 Activity 进行初始化，且只初始化一次。**必须在用户同意隐私协议后调用。**
-
-```kotlin
-ZySdk.sdkInit(
-    activity = this,
-    showLoginBackgroundImage = false,
-    callback = object : ZySdkCallback {
-        override fun onResult(result: String) {
-            Log.i(TAG, "init result=$result")
-        }
-    }
-)
-```
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:----------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `showLoginBackgroundImage` | Boolean | 是否展示 SDK 登录背景图 |
-| `result` | String | 初始化结果回调（JsonObject字符串） |
-
-**通用回参**
-
-| 字段 | 类型 | 含义 |
-|:-----------:|:-------:|:--------:|
-| `success` | Boolean | 是否成功 |
-| `msg` | String | 返回说明 |
-| `errorCode` | Int | 错误码 |
-| `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
-
-**华为渠道错误码如下：**
-
-| 错误码 | 错误信息 | 原因与处理建议 |
-|:---------:|:-------------:|:------------------------------------------:|
-| 7401 | 用户未同意华为联运隐私协议 | 禁止玩家进入游戏 |
-| 7002 | 网络异常 | 可提示玩家检查网络，请不要重复调用 init 接口，否则断网情况下可能会造成手机高耗电。 |
-| 907135003 | 组件升级取消 | 玩家取消 HMS Core 升级或组件升级 |
-| -1 | 防沉迷提示：游戏时间已结束 | 可在此处实现游戏防沉迷功能 |
-
----
-
-<a name="quickstart-login"></a>
-### 5. SDK登录
-
-用于拉起渠道账号体系或聚合登录流程，成功返回参数请传给游戏服完成鉴权与建号。
-
-```kotlin
-ZySdk.sdkLogin(
-    this,
-    object : ZySdkCallback {
-        override fun onResult(result: String) {
-            Log.i(TAG, "login result=$result")
-        }
-    }
-)
-```
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:---------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `result` | String | 登录结果回调（JsonObject字符串） |
-
-**通用回参**
-
-| 字段 | 类型 | 含义 |
-|-----------------------------------|:----------:|:----------------------:|
-| `success` | Boolean | 是否成功 |
-| `msg` | String | 状态信息 |
-| `errorCode` | Int | 错误码 |
-| `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
-| `data` | JsonObject | 登录数据，各渠道字段可能不同 |
-| &emsp;&emsp;`member_id` | String | 用户Id |
-| &emsp;&emsp;`player_id` | String | 玩家Id |
-| &emsp;&emsp;`username` | String | 用户名 |
-| &emsp;&emsp;`user_token` | String | token（`#` 后为游戏ID） |
-| &emsp;&emsp;`avatar` | String | 头像 |
-| &emsp;&emsp;`mobile` | String | 手机号 |
-| &emsp;&emsp;`has_identify` | boolean | 是否实名 |
-| &emsp;&emsp;`need_identification` | int | `1` 强制实名，`2` 需要实名但不强制，`3` 不需要实名 |
-| &emsp;&emsp;`has_mobile` | boolean | 是否绑定手机号 |
-| &emsp;&emsp;`sdk_open_id` | String | 抖音 `sdk_open_id` |
-
-**OPPO 错误码如下：**
-
-登录错误码
-
-| 错误码 | 错误信息 | 原因与处理建议 |
-|:--------:|:--------:|:------------------------------------------:|
-| 1004 | 登录失败 | 登录环节触发 OPPO 账号登录流程被用户取消，建议根据用户交互再次调用登录接口。 |
-| 1010 | 登录失败 | 联运账号登录流程异常，建议提示用户重新登录或尝试重启游戏。 |
-| 3000xxxx | 登录失败 | 游戏联运服务繁忙，建议提示用户稍后重试。 |
-| -1 | SDK 未初始化 | SDK 未初始化 |
-
-获取用户信息错误码
-
-| 错误码 | 错误信息 | 原因与处理建议 |
-|:----:|:--------:|:---------------------:|
-| 1010 | 用户还未登录 | 确认在登录成功后再调用该接口。 |
-| -1 | 解析登录信息失败 | 解析登录信息失败 |
-| -1 | SDK 未初始化 | SDK 未初始化 |
-
-**华为渠道错误码如下：**
-
-登录错误码
-
-| 错误码 | 错误信息 | 原因与处理建议 |
-|:---:|:-----------------------------------------:|:-----------:|
-| -1 | SDK 未初始化 | SDK 未初始化 |
-| -1 | data is null | 回调数据为空 |
-| -1 | SignIn result is empty | 结果数据为空 |
-| -1 | Failed to convert json from signInResult. | 数据转换出错 |
-| 1 | 授权成功，请重新登录 | 授权成功，重新调用登录 |
-
-获取用户信息错误码
-
-| 错误码 | 错误信息 | 原因与处理建议 |
-|:----:|:---------:|:----------:|
-| 7400 | 用户未签署联运协议 | 继续调用 init 接口 |
-| 7018 | 初始化失败 | 继续调用 init 接口 |
-| -1 | SDK 未初始化 | SDK 未初始化 |
-
-> 华为登录阶段已补兜底 `msg`，失败时不再只有裸 `errorCode`。
-
----
-
-<a name="quickstart-role"></a>
-### 6. 角色信息上报
-
-在登录成功、切换角色等操作后需进行角色信息上报。
-
-```kotlin
-ZySdk.sdkReportRole(
-    activity = this,
-    roleJson = roleJson,
-    callback = object : ZySdkCallback {
-        override fun onResult(result: String) {
-            Log.i(TAG, "role result=$result")
-        }
-    }
-)
-```
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:-------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `roleJson` | String | 角色信息 Json 字符串 |
-| `result` | String | 结果回调（JsonObject字符串） |
-
-**roleJson 参数如下：**
-
-| 字段名 | 类型 | 是否必填 | 字段说明 |
-|-----------------|:-------------------:|:----:|:-----------------------------------------------------------------------------------:|
-| `event` | String | 是 | 事件类型，`online/create/level_up/offline/other/delete` |
-| `server_id` | String | 是 | 服务器 ID |
-| `server_name` | String | 是 | 服务器名称 |
-| `cp_role_id` | String | 是 | 角色 id |
-| `role_name` | String | 是 | 角色昵称 |
-| `role_level` | int | 是 | 角色等级 |
-| `role_vip` | int | 是 | 角色 VIP 等级 |
-| `combat_num` | String | 否 | 角色战力 |
-| `online_time` | String | 否 | 本次在线时长 |
-| `attack` | String | 否 | 攻击力 |
-| `profession` | String | 否 | 职业 |
-| `gang_name` | String | 否 | 帮会(行会)名称 |
-| `trans_level` | String | 否 | 转生等级 |
-| `sponsor_level` | String | 否 | 赞助等级/会员等级 |
-| `reiki_num` | String | 否 | 灵符值 默认0 |
-| `chapter_index` | String | 否 | 关卡章节 |
-| `ext` | Map<String, Number> | 否 | 扩展字段，字段个数不超过 10 个，名称长度不超过 18 个字节，字段值必须是数字类型 |
-| `playerId` | String | 否 | 华为玩家 `playerId` |
-
-**回参**
-
-| 字段 | 类型 | 含义 |
-|:-----------:|:-------:|:--------:|
-| `success` | Boolean | 是否成功 |
-| `msg` | String | 返回说明 |
-| `errorCode` | Int | 错误码 |
-| `channelCode` | String | 当前渠道编码 |
-
-**错误码如下：**
-
-| 错误码 | 错误信息 | 原因与处理建议 |
-|:----:|:-----------:|:-----------------------------:|
-| 1010 | 您还未登入 | 校验账号未登录，确认在登录成功后再调用该接口。 |
-| 1010 | 账号已过期,请重新登录 | 账号校验失败，请确保登录成功后尽快上传游戏角色信息。 |
-| 1010 | 参数不合规范，上传失败 | 传参有缺失，按接口定义文档修改接口传参。 |
-| 1010 | 参数异常 | 调用接口时未传入参数，按接口定义文档修改接口传参。 |
-| -1 | SDK 未初始化 | SDK 未初始化 |
-
----
-
-<a name="quickstart-behavior"></a>
-### 7. 行为上报
-
-`sdkBehaviorReport(...)` 用于角色行为埋点或道具行为上报。
-
-```kotlin
-ZySdk.sdkBehaviorReport(
-    activity = this,
-    behaviorJson = behaviorJson,
-    callback = object : ZySdkCallback {
-        override fun onResult(result: String) {
-            Log.i(TAG, "behavior result=$result")
-        }
-    }
-)
-```
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:-------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `behaviorJson` | String | 行为上报 Json 字符串 |
-| `result` | String | 结果回调（JsonObject字符串） |
-
-**behaviorJson 常用参数如下：**
-
-| 字段名 | 类型 | 是否必填 | 字段说明 |
-|-----------------|:-------------------:|:----:|:------------------------------------------:|
-| `event` | String | 是 | 行为事件类型，例如 `item_cost`、`item_gain` |
-| `cp_role_id` | String | 是 | 游戏角色 ID |
-| `role_name` | String | 否 | 角色名 |
-| `querys` | JSONArray | 否 | 行为扩展字段数组 |
-
-**回参**
-
-| 字段 | 类型 | 含义 |
-|:-----------:|:-------:|:--------:|
-| `success` | Boolean | 是否成功 |
-| `msg` | String | 返回说明 |
-| `errorCode` | Int | 错误码 |
-| `channelCode` | String | 当前渠道编码 |
-
----
-
-<a name="quickstart-pay"></a>
-### 8. SDK支付
-
-```kotlin
-ZySdk.sdkPay(
-    activity = this,
-    payJson = payJson,
-    isSingle = false,
-    callback = object : ZySdkCallback {
-        override fun onResult(result: String) {
-            Log.i(TAG, "pay result=$result")
-        }
-    }
-)
-```
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:-------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `payJson` | String | 支付信息 Json 字符串 |
-| `isSingle` | Boolean | 是否单机支付，仅 OPPO 支持 |
-| `result` | String | 结果回调（JsonObject字符串） |
-
-**payJson 参数如下：**
-
-| 字段名 | 类型 | 是否必填 | 字段说明 |
-|-----------------------------|:------:|:----:|:-----------------------:|
-| `order` | String | 是 | 订单信息 Json |
-| &emsp;&emsp;`cp_order_id` | String | 是 | 游戏订单号，务必保证唯一 |
-| &emsp;&emsp;`amount` | int | 是 | 消费总金额，单位为分（1元->100） |
-| &emsp;&emsp;`product_price` | int | 是 | 商品价格（单价，单位：分） |
-| &emsp;&emsp;`product_id` | String | 是 | 商品Id |
-| &emsp;&emsp;`product_cnt` | int | 是 | 商品数量 |
-| &emsp;&emsp;`product_name` | String | 是 | 商品名（不能含有 `+` 号等特殊符号） |
-| &emsp;&emsp;`product_desc` | String | 是 | 商品描述（不能含有 `+` 号等特殊符号） |
-| &emsp;&emsp;`ext` | String | 否 | 订单额外信息用（json） |
-| `role` | String | 是 | 角色信息 Json |
-| &emsp;&emsp;`event` | String | 是 | 支付事件类型 |
-| &emsp;&emsp;`server_id` | String | 是 | 服务器 ID |
-| &emsp;&emsp;`server_name` | String | 是 | 服务器名称 |
-| &emsp;&emsp;`cp_role_id` | String | 是 | 角色 id |
-| &emsp;&emsp;`role_name` | String | 是 | 角色昵称 |
-| &emsp;&emsp;`role_level` | String | 是 | 角色等级 |
-| &emsp;&emsp;`role_vip` | String | 是 | 角色 VIP 等级 |
-| `role_id` | String | 是 | 角色 id |
-| `attach` | String | 否 | 自定义回调字段 |
-| `callbackUrl` | String | 否 | 游戏服务端回调地址 |
-| `priceType` | Int | 否 | 商品类型：`0` 消耗型；`1` 非消耗型；`2` 订阅型 |
-
-**回参**
-
-| 字段 | 类型 | 含义 |
-|:-----------:|:-------:|:--------:|
-| `success` | Boolean | 是否成功 |
-| `msg` | String | 返回说明 |
-| `errorCode` | Int | 错误码 |
-| `channelCode` | String | 当前渠道编码 |
-| `ext` | JsonObject | 扩展字段 |
-| - | - | 各渠道返回参数 |
-
-**OPPO 渠道错误码如下：**
-
-| 错误码 | 错误信息 | 原因与处理建议 |
-|:----:|:--------------------:|:------------------------------------------:|
-| 1004 | 支付取消 | 用户取消支付。 |
-| 1010 | 支付失败 | OPPO 支付处理异常，可能导致发货延迟，建议提示用户稍后查看到账情况。 |
-| 1010 | 您还未登录，请先登录 | 校验用户账号失败，用户还未登录。 |
-| 1010 | 未实名无法支付 | 用户未完成实名认证，无法成功支付。 |
-| 1010 | 共享游戏 ID 充值限制 | 登录被分享的游戏账号，不能进行支付。 |
-| -1 | SDK 未初始化 | SDK 未初始化 |
-| -1 | 单机支付请调用 doSinglePay 接口 | 支付和单机支付方法选择错误 |
-
-**vivo 渠道返回参数如下：**
-
-| 字段名 | 类型 | 字段说明 |
-|:-----------:|:-------:|:------------------------------:|
-| `transNo` | String | vivo 订单号，发货完成后用于 `reportOrder` |
-
-**华为渠道返回参数如下：**
-
-| 字段名 | 类型 | 字段说明 |
-|:-----------------------:|:-------:|:--------------------------:|
-| `success` | Boolean | 是否成功 |
-| `purchaseData` | String | 订单中的 `inAppPurchaseData` 字符串 |
-| `purchaseDataSignature` | String | 用于验签的签名数据 |
-| `msg` | String | 错误提示或状态说明 |
-| `errorCode` | Int | 华为订单状态码 |
-
----
-
-<a name="quickstart-ad"></a>
-### 9. 激励广告
-
-当前对外广告接口统一为：
-
-```kotlin
-ZySdk.showAd(activity, sceneId, callback)
-```
-
-说明：
-
-- SDK 内部会在初始化后处理广告配置拉取、广告 SDK 初始化和预加载
-- 接入方只需要传入要播放的 `sceneId`
-- 单次广告回调走 `ZyAdCallback`
-- 全局广告事件也会同步分发给 `ISdkEventListener`
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:-------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `sceneId` | String | 广告场景 ID |
-| `callback` | ZyAdCallback | 单次广告事件回调 |
-
-**示例**
-
-```kotlin
-ZySdk.showAd(
-    activity = this,
-    sceneId = "b1s8",
-    callback = object : ZyAdCallback {
-        override fun onAdOpen(resultJson: String) {
-            Log.d("Ad", "onAdOpen=$resultJson")
-        }
-
-        override fun onAdPlayReward(resultJson: String) {
-            Log.d("Ad", "onAdPlayReward=$resultJson")
-        }
-
-        override fun onAdClose(resultJson: String) {
-            Log.d("Ad", "onAdClose=$resultJson")
-        }
-
-        override fun onAdPlayFailed(resultJson: String) {
-            Log.d("Ad", "onAdPlayFailed=$resultJson")
-        }
-    }
-)
-```
-
-**`ZyAdCallback` 支持的方法**
-
-| 方法名 | 说明 |
-|---|---|
-| `onAdSubscribeFail(resultJson)` | 广告订阅/请求/初始化失败 |
-| `onAdPlayFailed(resultJson)` | 广告播放失败 |
-| `onAdPlayReward(resultJson)` | 广告激励发放成功 |
-| `onAdOpen(resultJson)` | 广告打开 |
-| `onAdClick(resultJson)` | 广告点击 |
-| `onAdClose(resultJson)` | 广告关闭 |
-| `onAdPlayBegin(resultJson)` | 广告播放开始 |
-| `onAdPlayEnd(resultJson)` | 广告播放结束 |
-| `onAdDataEmpty(resultJson)` | 广告数据为空 |
-| `onAdPreloadReady(resultJson)` | 广告预加载成功 |
-| `onAdReportFail(resultJson)` | 广告收益上报失败 |
-
-广告回调 `resultJson` 中常见字段：
-
-| 字段 | 类型 | 含义 |
-|---|---|---|
-| `success` | Boolean | 是否成功 |
-| `msg` | String | 返回说明 |
-| `errorCode` | Int | 错误码 |
-| `channelCode` | String | 当前渠道编码 |
-| `ext.eventType` | String | 广告事件类型 |
-| `ext.sceneId` | String | 广告场景 ID |
-| `ext.placementId` | String | 广告位 ID |
-
----
-
-<a name="quickstart-exit"></a>
-### 10. 退出引导
-
-在用户点击「退出游戏」等入口时调用：
-
-```kotlin
-ZySdk.sdkExit(this)
-```
-
-当前接口签名仍为：
-
-```kotlin
-ZySdk.sdkExit(activity, callback)
-```
-
-当前逻辑中：
-
-- 回调签名仅为兼容保留
-- 实际退出结果 **不再回调宿主**
-- SDK 内部会统一处理退出弹窗、渠道退出与广告资源释放
-
----
-
-<a name="quickstart-update"></a>
-### 11. 检查更新
-
-只需调用，若有更新，会弹出各渠道 SDK 自带的更新弹窗。
-
-```kotlin
-ZySdk.sdkUpdate(
-    this,
-    object : ZySdkCallback {
-        override fun onResult(result: String) {
-            Log.d(TAG, "sdkUpdate: $result")
-        }
-    }
-)
-```
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:-------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `result` | String | 结果回调（JsonObject字符串） |
-
-**回参**
-
-| 字段 | 类型 | 含义 |
-|:-----------:|:-------:|:--------:|
-| `success` | Boolean | 是否成功 |
-| `msg` | String | 返回说明 |
-| `errorCode` | Int | 错误码 |
-| `channelCode` | String | 当前渠道编码 |
-
----
-
-<a name="quickstart-float"></a>
-### 12. 显示/隐藏浮窗
-
-#### 显示主悬浮球
-```kotlin
-ZySdk.showFloatingBall(
-    this,
-    object : ZySdkCallback {
-        override fun onResult(result: String) {
-            Log.d(TAG, "showFloatingBall: $result")
-        }
-    }
-)
-```
-
-#### 隐藏主悬浮球
-```kotlin
-ZySdk.hideFloatingBall()
-```
-
-#### 华为渠道浮标
-```kotlin
-ZySdk.showHuaweiFloat(this)
-ZySdk.hideHuaweiFloat(this)
-```
-
-**入参**
-
-| 字段 | 类型 | 含义 |
-|:----------:|:--------:|:-------------------:|
-| `activity` | Activity | 当前 Activity 上下文 |
-| `result` | String | 结果回调（JsonObject字符串） |
- 
----
-
-<a name="quickstart-listener"></a>
-### 13. 对外回调接口
-
-#### 13.1 `ZySdkCallback`
-
-通用业务回调接口，初始化、登录、支付、角色上报、行为上报、更新等接口统一使用。
-
-```kotlin
-interface ZySdkCallback {
-    fun onResult(result: String)
-}
-```
-
-| 方法名 | 说明 |
-|---|---|
-| `onResult(result)` | 通用字符串回调，`result` 为 JSON 字符串 |
-
-#### 13.2 `ZyAdCallback`
-
-广告单次回调接口，`showAd(...)` 调用时使用。
-
-```kotlin
-interface ZyAdCallback : IAdEventCallback
-```
-
-**支持的方法**
-
-| 方法名 | 说明 |
-|---|---|
-| `onAdSubscribeFail(resultJson)` | 广告订阅/请求/初始化失败 |
-| `onAdPlayFailed(resultJson)` | 广告播放失败 |
-| `onAdPlayReward(resultJson)` | 广告激励发放成功 |
-| `onAdOpen(resultJson)` | 广告打开 |
-| `onAdClick(resultJson)` | 广告点击 |
-| `onAdClose(resultJson)` | 广告关闭 |
-| `onAdPlayBegin(resultJson)` | 广告播放开始 |
-| `onAdPlayEnd(resultJson)` | 广告播放结束 |
-| `onAdDataEmpty(resultJson)` | 广告数据为空 |
-| `onAdPreloadReady(resultJson)` | 广告预加载成功 |
-| `onAdReportFail(resultJson)` | 广告收益上报失败 |
-
-#### 13.3 `ISdkEventListener`
-
-全局 SDK 事件监听接口。
-
-SDK 提供监听设置接口：
-
-```kotlin
-ZySdk.setSdkEventListener(listener)
-ZySdk.clearSdkEventListener()
-```
-
-**示例**
-
-```kotlin
-ZySdk.setSdkEventListener(object : ISdkEventListener {
-    override fun onLogin(userInfoJson: String) {
-        Log.d("SdkEvent", "onLogin=$userInfoJson")
-    }
-
-    override fun onLogout() {
-        Log.d("SdkEvent", "onLogout")
-    }
-
-    override fun onPrivacyConsentAccepted() {
-        Log.d("SdkEvent", "onPrivacyConsentAccepted")
-    }
-
-    override fun onAdPlayReward(resultJson: String) {
-        Log.d("SdkEvent", "onAdPlayReward=$resultJson")
-    }
-})
-```
-
-`ISdkEventListener` 继承 `IAdEventCallback`，因此除全局登录/隐私事件外，也包含完整广告事件回调。
-
-**支持的方法**
-
-| 方法名 | 说明 |
-|---|---|
-| `onLogin(userInfoJson)` | 登录成功回调 |
-| `onLogout()` | 登出/Token 失效回调 |
-| `onSwitchAccount(userInfoJson)` | 切换账号成功回调 |
-| `onPasswordChanged()` | 修改密码成功回调 |
-| `onInitGameInfoReady(success)` | 游戏详情初始化完成回调 |
-| `onPrivacyConsentAccepted()` | 隐私弹窗点击同意 |
-| `onPrivacyConsentRejected()` | 隐私弹窗点击拒绝 |
-| `onAdSubscribeFail(resultJson)` | 广告订阅失败 |
-| `onAdPlayFailed(resultJson)` | 广告播放失败 |
-| `onAdPlayReward(resultJson)` | 广告奖励发放 |
-| `onAdOpen(resultJson)` | 广告打开 |
-| `onAdClick(resultJson)` | 广告点击 |
-| `onAdClose(resultJson)` | 广告关闭 |
-| `onAdPlayBegin(resultJson)` | 广告播放开始 |
-| `onAdPlayEnd(resultJson)` | 广告播放结束 |
-| `onAdDataEmpty(resultJson)` | 广告数据为空 |
-| `onAdPreloadReady(resultJson)` | 广告预加载成功 |
-| `onAdReportFail(resultJson)` | 广告收益上报失败 |
-
-#### 13.4 `ZyReflectCallback`
-
-Unity/反射接入专用回调接口。
-
-```kotlin
-interface ZyReflectCallback {
-    fun onResult(methodName: String, result: String)
-}
-```
-
-| 方法名 | 说明 |
-|---|---|
-| `onResult(methodName, result)` | 反射调用结果回调，`methodName` 为调用的方法名，`result` 为 JSON 字符串 |
-
----
-
-<a name="quickstart-unity"></a>
-### 14. Unity 接入
-
-当接入方是 Unity 宿主时，推荐统一通过 `ZyUnitySupport` 反射调用 SDK。
-
-#### 统一反射入口
-
-```kotlin
-ZyUnitySupport.invokeMethod(activity, methodName, paramJson, callback)
-```
-
-#### 回调接口
-
-```kotlin
-interface ZyReflectCallback {
-    fun onResult(methodName: String, result: String)
-}
-```
-
-#### 当前支持的 `methodName`
-
-| methodName | 说明 |
-|---|---|
-| `sdkInit` | SDK 初始化 |
-| `sdkLogin` | SDK 登录 |
-| `sdkPay` | 常规支付 |
-| `sdkSinglePay` | OPPO 单机支付 |
-| `sdkReportRole` | 角色上报 |
-| `sdkBehaviorReport` | 行为上报 |
-| `showAd` | 激励广告 |
-| `sdkExit` | 退出游戏 |
-| `sdkUpdate` | 检查更新 |
-| `showFloatingBall` | 显示主悬浮球 |
-| `hideFloatingBall` | 隐藏主悬浮球 |
-| `showHuaweiFloat` | 显示华为浮标 |
-| `hideHuaweiFloat` | 隐藏华为浮标 |
-| `setDebug` | 设置调试开关 |
-| `clearCache` | 清空本地缓存 |
-| `getSdkUserInfo` | 获取当前用户信息 |
-| `hasPrivacyConsentAccepted` | 查询隐私同意状态 |
-
-#### 常用 `paramJson` 示例
-
-| methodName | paramJson 示例 |
-|---|---|
-| `sdkInit` | `{"showLoginBackgroundImage":true}` |
-| `sdkPay` / `sdkSinglePay` | 直接传支付 Json 字符串 |
-| `sdkReportRole` | 直接传角色上报 Json 字符串 |
-| `sdkBehaviorReport` | 直接传行为上报 Json 字符串 |
-| `showAd` | `{"sceneId":"b1s8"}` |
-| `setDebug` | `{"enabled":true}` |
-
-#### Unity 全局监听
-
-Unity 中全局监听统一走：
-
-```kotlin
-ZyUnitySupport.setSdkEventListener(activity, listener)
-ZyUnitySupport.clearSdkEventListener()
-```
-
-其中 `listener` 为 `ISdkEventListener` 实现。
-
----
-
-<a name="samples"></a>
-## 三、示例代码位置
-
-| 能力 | 代码位置 |
-|----------------------------------|--------------------------------------------------------------------|
-| 初始化 / 登录 / 支付 / 角色上报 / 行为上报 / 广告 / 退出 / 悬浮球 | `appbase/src/main/java/com/zwwl/appbase/MainActivity.kt` |
-| Unity 反射验证 | `appbase/src/main/java/com/zwwl/appbase/UnityDemoActivity.kt` |
-| 华为 Unity 验证 | `basehuawei/src/main/java/com/xmdzzandroid/huawei/UnityDemoActivity.kt` |
-| 依赖与签名 | `app/build.gradle.kts` |
-| 仓库 | `settings.gradle.kts` |
-
----
+++ /dev/null