|
| 1 | +# AtomicXCore API 示例 Demo — Android |
| 2 | + |
| 3 | +[English](./README_EN.md) | 中文 |
| 4 | + |
| 5 | +## 项目简介 |
| 6 | + |
| 7 | +本项目是 **AtomicXCore SDK** 的 Android 端 API 示例 Demo，通过四个渐进式阶段完整展示了从基础推拉流到复杂互动直播的全部核心功能。项目采用 Kotlin 语言开发，使用传统 View 体系 + ViewBinding 构建 UI，适合开发人员快速了解和集成 AtomicXCore SDK。 |
| 8 | + |
| 9 | +## 功能概览 |
| 10 | + |
| 11 | +| 阶段 | 功能模块 | 说明 | |
| 12 | +|:---:|:---|:---| |
| 13 | +| 1 | **BasicStreaming** 基础推拉流 | 直播创建/加入、摄像头/麦克风管理、视频渲染 | |
| 14 | +| 2 | **Interactive** 实时互动 | 弹幕消息、礼物系统（含 SVGA 动画）、点赞、美颜、音效 | |
| 15 | +| 3 | **MultiConnect** 观众连线 | 观众申请上麦、主播邀请连线、麦位管理、多人视频 | |
| 16 | +| 4 | **LivePK** 直播 PK 对战 | 跨房连线、PK 对战、实时积分、战斗结果展示 | |
| 17 | + |
| 18 | +> 四个阶段层层递进，每个后续阶段都包含前一阶段的全部功能并增加新能力。 |
| 19 | +
|
| 20 | +## 技术栈 |
| 21 | + |
| 22 | +| 类别 | 技术 | 版本 | |
| 23 | +|:---:|:---|:---| |
| 24 | +| 语言 | Kotlin | 2.0.21 | |
| 25 | +| 构建工具 | Android Gradle Plugin | 8.5.2 | |
| 26 | +| UI 框架 | Android View + ViewBinding | — | |
| 27 | +| 核心 SDK | AtomicXCore (`io.trtc.uikit:atomicx-core`) | latest.release | |
| 28 | +| IM SDK | 腾讯云 IM (`com.tencent.imsdk:imsdk-plus`) | 8.7.7201 | |
| 29 | +| 设计系统 | Material Design 3 | 1.12.0 | |
| 30 | +| 图片加载 | Coil | 2.7.0 | |
| 31 | +| 动画引擎 | SVGAPlayer | 2.6.1 | |
| 32 | +| 最低版本 | Android 8.0 (API 26) | — | |
| 33 | +| 目标版本 | Android 15 (API 35) | — | |
| 34 | + |
| 35 | +## 项目架构 |
| 36 | + |
| 37 | +### 架构模式 |
| 38 | + |
| 39 | +项目采用 **MVC + Store** 模式： |
| 40 | + |
| 41 | +- **Store 模式**：AtomicXCore SDK 通过各种 Store 单例对象（如 `LoginStore`、`DeviceStore`、`BarrageStore` 等）暴露状态（`StateFlow`）和操作方法 |
| 42 | +- **Activity 层**：直接与 Store 交互，通过 `lifecycleScope` + `collectLatest` 订阅状态变化并更新 UI |
| 43 | +- **组件化复用**：`components/` 目录下的可复用 UI 组件被多个 Activity 共享 |
| 44 | + |
| 45 | +### 目录结构 |
| 46 | + |
| 47 | +``` |
| 48 | +android/app/src/main/java/com/example/atomicxcore/ |
| 49 | +├── App.kt # Application 入口 |
| 50 | +├── SplashActivity.kt # 启动页 |
| 51 | +├── MainActivity.kt # 备用主 Activity |
| 52 | +├── debug/ |
| 53 | +│ └── GenerateTestUserSig.kt # 调试用 UserSig 本地生成工具 |
| 54 | +├── components/ # 可复用 UI 组件 |
| 55 | +│ ├── AudioEffectSettingView.kt # 音效设置面板（变声/混响/耳返） |
| 56 | +│ ├── BarrageView.kt # 弹幕消息列表 + 输入框 |
| 57 | +│ ├── BeautySettingView.kt # 美颜设置面板（磨皮/美白/红润） |
| 58 | +│ ├── CoHostUserListView.kt # 可连线主播列表 |
| 59 | +│ ├── DeviceSettingView.kt # 设备管理面板（摄像头/麦克风/镜像/清晰度） |
| 60 | +│ ├── GiftAnimationView.kt # 礼物动画展示（SVGA 全屏 + 弹幕滑动） |
| 61 | +│ ├── GiftPanelView.kt # 礼物选择面板（网格展示 + 发送） |
| 62 | +│ ├── LikeButton.kt # 点赞按钮（爱心粒子动效） |
| 63 | +│ ├── LocalizedManager.kt # 本地化管理器（中英文切换） |
| 64 | +│ ├── Role.kt # 角色枚举（ANCHOR/AUDIENCE） |
| 65 | +│ ├── SettingPanelController.kt # 通用 BottomSheet 面板容器 |
| 66 | +│ └── TabbedSettingView.kt # Tab 切换容器（设备/美颜/音效） |
| 67 | +├── utils/ # 工具类 |
| 68 | +│ ├── CompletionHandlers.kt # SDK CompletionHandler 的 Lambda 包装器 |
| 69 | +│ ├── PermissionHelper.kt # 统一权限管理（相机/麦克风/蓝牙） |
| 70 | +│ └── ViewExtensions.kt # View 扩展函数（状态栏适配） |
| 71 | +└── scenes/ # 业务场景页面 |
| 72 | + ├── login/ |
| 73 | + │ ├── LoginActivity.kt # 用户登录页 |
| 74 | + │ └── ProfileSetupActivity.kt # 资料完善页（昵称 + 头像） |
| 75 | + ├── featurelist/ |
| 76 | + │ └── FeatureListActivity.kt # 功能列表首页（4 个功能卡片） |
| 77 | + ├── basicstreaming/ |
| 78 | + │ └── BasicStreamingActivity.kt # 阶段 1: 基础推拉流 |
| 79 | + ├── interactive/ |
| 80 | + │ └── InteractiveActivity.kt # 阶段 2: 实时互动 |
| 81 | + ├── multiconnect/ |
| 82 | + │ └── MultiConnectActivity.kt # 阶段 3: 观众连线 |
| 83 | + └── livepk/ |
| 84 | + └── LivePKActivity.kt # 阶段 4: 直播 PK 对战 |
| 85 | +``` |
| 86 | + |
| 87 | +### 应用流程 |
| 88 | + |
| 89 | +``` |
| 90 | +SplashActivity (启动页，1 秒展示 Logo) |
| 91 | + │ |
| 92 | + ▼ |
| 93 | +LoginActivity (输入 UserID → SDK 登录) |
| 94 | + │ |
| 95 | + ├─ 昵称为空 ──→ ProfileSetupActivity (设置昵称 + 头像) |
| 96 | + │ │ |
| 97 | + │ ▼ |
| 98 | + └─ 昵称已设置 ──→ FeatureListActivity (4 个功能卡片) |
| 99 | + │ |
| 100 | + ├─ 选择角色（主播 / 观众）+ 房间 ID |
| 101 | + │ |
| 102 | + ├──→ BasicStreamingActivity (阶段 1) |
| 103 | + ├──→ InteractiveActivity (阶段 2) |
| 104 | + ├──→ MultiConnectActivity (阶段 3) |
| 105 | + └──→ LivePKActivity (阶段 4) |
| 106 | +``` |
| 107 | + |
| 108 | +## AtomicXCore SDK API 使用说明 |
| 109 | + |
| 110 | +### 阶段 1：BasicStreaming — 基础推拉流 |
| 111 | + |
| 112 | +| Store | 关键 API | 功能 | |
| 113 | +|:---|:---|:---| |
| 114 | +| `LoginStore` | `login()`, `setSelfInfo()`, `loginState` | 用户登录与状态管理 | |
| 115 | +| `LiveListStore` | `createLive()`, `joinLive()`, `endLive()`, `leaveLive()` | 直播房间生命周期管理 | |
| 116 | +| `DeviceStore` | `openLocalCamera()`, `openLocalMicrophone()`, `switchCamera()` | 本地设备控制 | |
| 117 | +| `LiveCoreView` | `PUSH_VIEW` / `PLAY_VIEW` 模式 | 视频渲染组件 | |
| 118 | + |
| 119 | +### 阶段 2：Interactive — 实时互动 |
| 120 | + |
| 121 | +| Store | 关键 API | 功能 | |
| 122 | +|:---|:---|:---| |
| 123 | +| `BarrageStore` | `sendTextMessage()`, `barrageState.messageList` | 弹幕消息收发 | |
| 124 | +| `GiftStore` | `sendGift()`, `refreshUsableGifts()` | 礼物系统 | |
| 125 | +| `LikeStore` | `sendLike()`, `addLikeListener()` | 点赞互动 | |
| 126 | +| `BaseBeautyStore` | `setSmoothLevel()`, `setWhitenessLevel()`, `setRuddyLevel()` | 美颜调节 | |
| 127 | +| `AudioEffectStore` | `setAudioChangerType()`, `setAudioReverbType()` | 音效控制 | |
| 128 | + |
| 129 | +### 阶段 3：MultiConnect — 观众连线 |
| 130 | + |
| 131 | +| Store | 关键 API | 功能 | |
| 132 | +|:---|:---|:---| |
| 133 | +| `CoGuestStore` | `applyForSeat()`, `inviteToSeat()`, `acceptApplication()` | 连线请求管理 | |
| 134 | +| `LiveSeatStore` | `openRemoteCamera()`, `kickUserOutOfSeat()` | 麦位与远端设备管理 | |
| 135 | +| `LiveAudienceStore` | `fetchAudienceList()` | 观众列表 | |
| 136 | +| `VideoViewAdapter` | `createCoGuestView()` | 视频覆盖层代理 | |
| 137 | + |
| 138 | +### 阶段 4：LivePK — 直播 PK 对战 |
| 139 | + |
| 140 | +| Store | 关键 API | 功能 | |
| 141 | +|:---|:---|:---| |
| 142 | +| `CoHostStore` | `requestHostConnection()`, `acceptHostConnection()`, `exitHostConnection()` | 跨房连线管理 | |
| 143 | +| `BattleStore` | `requestBattle()`, `acceptBattle()`, `exitBattle()`, `battleState` | PK 对战管理与实时积分 | |
| 144 | + |
| 145 | +## 环境要求 |
| 146 | + |
| 147 | +- **Android Studio**: Ladybug 或更高版本 |
| 148 | +- **JDK**: 17 |
| 149 | +- **Gradle**: 8.x |
| 150 | +- **最低系统版本**: Android 8.0 (API 26) |
| 151 | +- **目标系统版本**: Android 15 (API 35) |
| 152 | + |
| 153 | +## 快速开始 |
| 154 | + |
| 155 | +### 1. 克隆项目 |
| 156 | + |
| 157 | +```bash |
| 158 | +git clone <repository-url> |
| 159 | +cd atomic-api-example/android |
| 160 | +``` |
| 161 | + |
| 162 | +### 2. 配置 SDK 凭证 |
| 163 | + |
| 164 | +编辑 `app/src/main/java/com/example/atomicxcore/debug/GenerateTestUserSig.kt`，填入你的腾讯云应用凭证： |
| 165 | + |
| 166 | +```kotlin |
| 167 | +const val SDKAPPID: Long = 0 // 替换为你的 SDKAPPID |
| 168 | +const val SECRETKEY = "" // 替换为你的 SECRETKEY |
| 169 | +``` |
| 170 | + |
| 171 | +> ⚠️ **安全提示**: `SECRETKEY` 仅用于本地调试。生产环境中，UserSig 必须由后端服务生成，切勿将 SECRETKEY 嵌入客户端发布包中。 |
| 172 | +
|
| 173 | +### 3. 构建运行 |
| 174 | + |
| 175 | +使用 Android Studio 打开 `android/` 目录，同步 Gradle 后即可编译运行。 |
| 176 | + |
| 177 | +## 权限说明 |
| 178 | + |
| 179 | +应用运行需要以下权限： |
| 180 | + |
| 181 | +| 权限 | 用途 | |
| 182 | +|:---|:---| |
| 183 | +| `INTERNET` | 网络通信 | |
| 184 | +| `CAMERA` | 摄像头采集 | |
| 185 | +| `RECORD_AUDIO` | 麦克风采集 | |
| 186 | +| `BLUETOOTH` / `BLUETOOTH_CONNECT` | 蓝牙耳机连接 | |
| 187 | +| `FOREGROUND_SERVICE` | 后台保活 | |
| 188 | + |
| 189 | +## 本地化支持 |
| 190 | + |
| 191 | +项目支持中英文双语切换，可在功能列表页面的设置菜单中切换语言： |
| 192 | + |
| 193 | +- `res/values/strings.xml` — 英文（默认） |
| 194 | +- `res/values-zh-rCN/strings.xml` — 简体中文 |
0 commit comments