164 行
5.8 KiB
Markdown
164 行
5.8 KiB
Markdown
# XuqmGroup-AndroidSDK — Claude 项目上下文
|
||
|
||
## 项目定位
|
||
|
||
XuqmGroup Android SDK，Gradle multi-module 项目。为集成宿主 App（如 YwxMobileApp）提供：初始化、用户认证、OTA 更新、WebView、IM、推送、证书、Bug 采集。
|
||
|
||
- Git 远端：`https://xuqinmin.com/xuqmGroup/XuqmGroup-AndroidSDK.git`
|
||
- Nexus Maven 发布：`https://nexus.xuqinmin.com/repository/android-hosted/`
|
||
- groupId：`com.xuqm`
|
||
- 技术栈：Kotlin 2.3.10，AGP 9.1.0，minSdk 24，compileSdk 36，Java 21
|
||
|
||
## 模块结构
|
||
|
||
| 模块 | artifactId | 状态 |
|
||
|------|-----------|------|
|
||
| sdk-core | `sdk-core` | 活跃开发 |
|
||
| sdk-update | `sdk-update` | 活跃开发 |
|
||
| sdk-webview | `sdk-webview` | 活跃开发 |
|
||
| sdk-bugcollect | `sdk-bugcollect`（新） | 新建中 |
|
||
| sdk-push | `sdk-push` | 代码冻结（仅文档） |
|
||
| sdk-im | `sdk-im` | 代码冻结（仅文档） |
|
||
| sample-app | — | 演示 App |
|
||
|
||
**非当前范围模块（sdk-push/sdk-im）：除修复构建阻塞外不扩展功能。**
|
||
|
||
## 核心 API（sdk-core）
|
||
|
||
### 初始化（两种方式，均不得修改签名）
|
||
|
||
**方式 A — ContentProvider 自动初始化（推荐）**
|
||
将 `config.xuqm` 放入 `src/main/assets/xuqm/`，App 无需调用任何初始化代码。
|
||
`XuqmInitializerProvider` 在 App 启动时自动触发。
|
||
|
||
**方式 B — 手动初始化**
|
||
```kotlin
|
||
// Application.onCreate() 中：
|
||
XuqmSDK.initialize(context, appKey = "xxx") // 公有平台
|
||
XuqmSDK.initialize(context, appKey = "xxx", platformUrl = "https://xxx") // 私有化平台
|
||
|
||
// 等待平台配置（在 coroutine 中）：
|
||
XuqmSDK.awaitInitialization()
|
||
```
|
||
|
||
**两种平台互相独立，不允许自动降级到默认公有平台（`DEFAULT_PLATFORM_URL`）。**
|
||
|
||
### 用户信息
|
||
|
||
```kotlin
|
||
XuqmSDK.setUserInfo(XuqmUserInfo(
|
||
userId = "u001",
|
||
userSig = "sig", // IM 登录凭证（仅 IM 强制，其它 SDK 均可不传）
|
||
name = "张三", // 可选
|
||
))
|
||
XuqmSDK.setUserInfo(null) // 登出，触发所有子 SDK 登出
|
||
```
|
||
|
||
**`userSig` 设计规则（必须遵守）：**
|
||
|
||
| SDK | userSig 要求 |
|
||
|-----|------------|
|
||
| sdk-im | **强制** — 没有 userSig 不能登录 IM |
|
||
| sdk-push | **可选** — 只有 userId 也可完成 push 设备注册 |
|
||
| sdk-update | **可选** — 只有 userId 即可使用 |
|
||
| sdk-bugcollect | **可选** — 只有 userId 即可使用 |
|
||
| sdk-webview | **可选** — 只有 userId 即可使用 |
|
||
|
||
- 外部用户（无 userSig）：只需 `userId`，可使用除 IM 外的所有 SDK 功能
|
||
- 平台托管用户（有 userSig）：完整功能，包含 IM
|
||
- **禁止在 push / update / bugcollect 等 SDK 内部校验 userSig 是否存在**
|
||
|
||
**注意：** push 设备注册依赖请求签名（`signingKey` in config.xuqm），与 userSig 无关。`signingKey` 未配置时，设备注册请求会被服务端拒绝（HTTP 401）。需在平台后台为该 appKey 生成 signingKey 并重新下载 config.xuqm。
|
||
|
||
### 平台配置读取（init 完成后）
|
||
```kotlin
|
||
XuqmSDK.platformConfig?.bugCollectApiUrl // Bug 采集服务地址
|
||
XuqmSDK.bugCollectEnabled // 是否开启 Bug 采集
|
||
XuqmSDK.appKey // 当前 appKey
|
||
```
|
||
|
||
## Bug 采集 SDK（sdk-bugcollect）
|
||
|
||
```kotlin
|
||
// Application.onCreate() 中（XuqmSDK.initialize 之后）：
|
||
BugCollect.setLogLevel(LogLevel.INFO)
|
||
BugCollect.setEnvironment("production")
|
||
BugCollect.startCrashCapture() // 开启 UncaughtExceptionHandler
|
||
|
||
// 埋点
|
||
BugCollect.event("page_view", mapOf("page" to "home"))
|
||
|
||
// 错误上报
|
||
BugCollect.captureError(exception)
|
||
|
||
// 漏斗定义
|
||
BugCollect.defineFunnel("checkout", listOf("cart_view", "checkout_start", "payment_done"))
|
||
```
|
||
|
||
`bugCollectApiUrl` 由 SDK 在 init 后从平台配置自动获取，无需 App 传入。
|
||
|
||
## 向下兼容约束
|
||
|
||
- `XuqmSDK.initialize()` 现有参数不得删除或修改类型
|
||
- `XuqmSDK.setUserInfo()` 现有 `XuqmUserInfo` 字段不得删除
|
||
- `SdkPlatformConfig` 新增字段一律为可选（`val xxx: Type? = null`）
|
||
- 旧服务端不返回新字段时，客户端使用合理默认值
|
||
|
||
## 集成验证项目
|
||
|
||
YwxMobileApp：`/Users/xuqinmin/Projects/TrustProjects/Pad/YwxMobileApp`
|
||
使用 Nexus Maven 引入 SDK，开发阶段可改为 `project()` 本地引用。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
./gradlew :sdk-bugcollect:assembleDebug
|
||
./gradlew :sdk-core:assembleDebug
|
||
./gradlew :sample-app:installDebug
|
||
./gradlew publish # 发布所有模块到 Nexus
|
||
|
||
# 发布单个模块
|
||
./gradlew :sdk-core:publish -PSDK_CORE_VERSION=1.0.0
|
||
```
|
||
|
||
## 发版配置
|
||
|
||
在 `gradle.properties` 中配置：
|
||
```properties
|
||
NEXUS_USER=your_username
|
||
NEXUS_PASSWORD=your_password
|
||
```
|
||
|
||
发布至 `https://nexus.xuqinmin.com/repository/android-hosted/`，版本号在各模块 `build.gradle.kts` 中维护。
|
||
|
||
## 版本号与发布规则（严禁违反）
|
||
|
||
### 核心原则
|
||
|
||
1. **开发阶段只允许发布 SNAPSHOT**：所有 `gradle.properties` 中的 `SDK_*_VERSION` 必须以 `-SNAPSHOT` 结尾。
|
||
2. **禁止手动修改版本号为正式版本**：不得手动将 `1.x.x-SNAPSHOT` 改为 `1.x.x`（去掉 `-SNAPSHOT`）。
|
||
3. **所有正式发版必须走 Jenkins**：Jenkins 自动完成版本号提升、去掉 `-SNAPSHOT`、发布到 Nexus、打 Git tag 等操作。
|
||
|
||
### 违禁示例
|
||
|
||
```properties
|
||
# ❌ 禁止在代码中手动修改为正式版本
|
||
SDK_PUSH_VERSION=1.1.4 # 错误：手动去掉了 -SNAPSHOT
|
||
SDK_CORE_VERSION=1.1.6 # 错误
|
||
|
||
# ✅ 正确：开发阶段保持 SNAPSHOT
|
||
SDK_PUSH_VERSION=1.1.4-SNAPSHOT
|
||
SDK_CORE_VERSION=1.1.6-SNAPSHOT
|
||
```
|
||
|
||
### 允许的手动操作
|
||
|
||
- 新功能开发需要升版本号时：可以将 `1.x.x-SNAPSHOT` 改为 `1.x+1.0-SNAPSHOT`（只提升次版本，保留 `-SNAPSHOT`）
|
||
- 发布 SNAPSHOT 到 Nexus 用于集成测试：`./gradlew :sdk-xxx:publish`
|
||
|
||
### Jenkins 负责的操作（禁止手动代替）
|
||
|
||
- 去掉 `-SNAPSHOT` 发布正式版
|
||
- 打 Git release tag
|
||
- 更新下一个开发周期的 SNAPSHOT 版本号
|
