通用 Unity Android 渠道 SDK 接入
概述
将第三方渠道游戏/广告/支付 SDK 集成到 Unity Android 项目。与具体的项目结构解耦，通过三个维度的选择匹配不同场景。
三维度模型：
接收到 SDK 接入需求
│
├─ 你的 SDK 是什么格式？ → 维度 A: 来源 (本地AAR / 远端Maven / Git子模块)
├─ 你的项目是什么架构？ → 维度 B: 架构 (单体 / 母包子包 / Flavor)
└─ 你需要哪些功能？ → 维度 C: 契约 (登录 / 支付 / 广告 / 云存档)
每个维度的选择决定后续的实施方案。本项目技能不假设你使用什么路径、什么宏、什么构建系统——所有项目特有细节在分析过程中逐步确定。
第零步：项目评估
参照 references/project-assessment.md 的清单确认三个维度，输出一张决策表。这是所有后续步骤的基础。
第一步：SDK 分析
根据维度 A（SDK 来源）选择分析方式：
| 来源 | 分析工具/方法 |
|---|---|
| 本地 AAR | python scripts/aar_analyzer.py analyze <dir> --all -o report.md |
| 远端 Maven 仓库 | 解析 pom.xml / build.gradle 依赖声明 → 提取 groupId:artifactId:version、仓库 URL |
| Git 子模块 | 检查子模块的 build.gradle 和 Demo 代码，同本地 AAR 分析 |
本地 AAR 分析报告内容
运行 --all 后的报告包含：
- Manifest 冲突：所有 AAR 之间的 provider/activity/service 冲突
- 公共 API 列表：对外暴露的类和方法签名（过滤内部类、混淆类）
- Class 重复检测：新 AAR 是否内置了已有 SDK
- 加固检测：是否经过 ijiami 等工具处理
- JNI 库列表：所有 .so 文件
远端 SDK 分析
远端 SDK 无需下载 AAR 即可分析：
# 1. 查看 Maven 仓库的 pom.xml
# 2. 提取依赖声明
# 3. 如有 Demo 工程，读取其 build.gradle 中的 implementation 声明
关键信息：groupId:artifactId:version、仓库 URL、传递依赖列表。
第二步：架构设计
根据维度 B（项目架构）选择实施方案：
模式 1：单体
所有渠道 SDK 在同一 Unity 工程中，通过条件编译或运行时选择渠道。
适用：渠道数 < 5、团队规模小、不需要独立发包。
实施要点：
- 渠道代码通过 C# JNI 桥接（AndroidJavaClass / AndroidJavaObject）
- 渠道互斥代码用 #if CHANNEL_A / #if !CHANNEL_A 守卫
- AAR 全部放入工程，构建时选择包含哪些
- 渠道特有 UI/Prefab 用资源覆盖机制
模式 2：母包 + 子包
母包不含渠道 SDK，渠道作为独立模块依赖母包，发包时合并。
适用：多渠道独立发包、不同团队维护不同渠道、渠道代码频繁变更。
实施要点：
- 母包定义 IChannelModule 接口
- 每个渠道子包独立 Gradle 项目，实现接口
- 母包通过反射/注册机制发现子包
- 子包在 Application.onCreate() 时注册自己
┌──────────────────┐
│ 母包 (Base APK) │
│ Unity 游戏 │
│ 不含渠道 SDK │
│ IChannelModule 接口│
└────────┬─────────┘
│ 依赖
┌──────┴──────┐
│ 渠道子包 │
│ 渠道 SDK │
│ 实现 IModule │
└─────────────┘
模式 3：Gradle Product Flavor
利用 Android Gradle 原生 flavor 机制区分渠道。
适用：熟悉 Android 原生开发、希望用 Gradle 管理渠道差异。
实施要点：
- 每个渠道一个 productFlavor
- 渠道特有代码在 src/<flavor>/ 目录
- build.gradle 中用 flavorDimensions 控制
- 渠道 AAR 用 flavorImplementation 依赖
第三步：渠道契约实现
不管选哪种架构，渠道模块都应实现统一的接口契约。具体语言和实现方式取决于架构选择。
参照 references/channel-contract.md，核心接口：
IChannelModule
├── Init → 初始化 SDK（含隐私同意）
├── Login → 登录 → (userId, token)
├── Pay → 支付
├── Exit → 退出
├── Compliance→ 实名认证检查
└── Lifecycle → onResume/onPause/onDestroy
单体：用 C# AndroidJavaProxy 实现 JNI 回调
母包子包：用 Java/Kotlin 接口 + Unity AndroidJavaObject.Call() 反射调用
Flavor：两者皆可
第四步：构建配置
Manifest 冲突
参照 references/manifest-conflict-patterns.md。通用原则：
- 先用 aar_analyzer.py --diff 检测冲突
- 在项目 AndroidManifest 的相同 XML 层级加 tools:replace
- <queries> 是 manifest 根级元素，不是 <application> 子元素
Gradle 依赖
参照 references/gradle-patterns.md：
本地 AAR：
// flatDir 方式
repositories { flatDir { dirs 'libs' } }
implementation(name: 'sdk', ext: 'aar')
// fileTree 方式
implementation fileTree(dir: 'libs', include: ['*.aar'])
远端 Maven：
repositories { maven { url 'https://sdk-repo.example.com/' } }
implementation 'com.example:sdk:1.0.0'
ProGuard
-keep class com.channel.sdk.** { *; }
-dontwarn com.channel.sdk.**
第五步：测试验证
参照 references/testing-strategy.md。
核心验证路径——无论哪种架构，以下场景必须通过：
| # | 场景 | 通过标准 |
|---|---|---|
| 1 | 启动 | SDK init 日志正常 |
| 2 | 登录 | 获取到 userId/token |
| 3 | 进关卡 | 游戏正常运行 |
| 4 | 关卡失败→重试→成功 | 游戏流程不中断 |
| 5 | 退出 | 无崩溃 |
快速冒烟（ADB）：
adb logcat -d | grep -E "SDK Init|Login|NullReferenceException|FATAL"
参考文件
references/project-assessment.md— 项目接入前评估清单references/channel-contract.md— 渠道模块接口契约 + 实现模板references/architecture-patterns.md— 三种架构模式详解references/sdk-source-patterns.md— SDK 来源处理：AAR / Maven / Gitreferences/manifest-conflict-patterns.md— 通用 Manifest 冲突处理references/gradle-patterns.md— 通用 Gradle 依赖管理references/testing-strategy.md— 测试策略 + 自动化方案
工具
scripts/aar_analyzer.py— AAR 全分析（Manifest / API / 重复 / 加固）assets/channel-contract.cs— IChannelModule C# 接口骨架assets/channel-module.java— 母包子包 Java 中间层骨架assets/build-flavor.txt— Product Flavor 配置模板
