通用 Unity Android 渠道 SDK 接入

概述

将第三方渠道游戏/广告/支付 SDK 集成到 Unity Android 项目。与具体的项目结构解耦，通过三个维度的选择匹配不同场景。

三维度模型：

接收到 SDK 接入需求
  │
  ├─ 你的 SDK 是什么格式？   → 维度 A: 来源 (本地AAR / 远端Maven / Git子模块)
  ├─ 你的项目是什么架构？    → 维度 B: 架构 (单体 / 母包子包 / Flavor)
  └─ 你需要哪些功能？        → 维度 C: 契约 (登录 / 支付 / 广告 / 云存档)

每个维度的选择决定后续的实施方案。本项目技能不假设你使用什么路径、什么宏、什么构建系统——所有项目特有细节在分析过程中逐步确定。

第零步：项目评估

参照 references/project-assessment.md 的清单确认三个维度，输出一张决策表。这是所有后续步骤的基础。

第一步：SDK 分析

根据维度 A（SDK 来源）选择分析方式：

本地 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// 目录
• 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
• 是 manifest 根级元素，不是 子元素

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。

核心验证路径——无论哪种架构，以下场景必须通过：

快速冒烟（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 / Git
• references/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 配置模板