Android 应用
Android 开发者指南
本文档介绍 LeadHub 原生 Android 应用——使用 Kotlin 编写——通过 REST API 连接到您的 LeadHub 实例。本指南面向需要构建、定制或部署该应用的开发者。
环境要求
开始之前，请确保已具备：
| 要求 | 详情 |
|---|---|
| Android Studio | Hedgehog（2023.1.1）或更高版本 |
| JDK | 17 或以上 |
| 最低 API 级别 | 26（Android 8.0） |
| LeadHub 实例 | 需通过 HTTPS 访问且拥有有效的 SSL 证书 |
| API 密钥 | 在用户面板中生成 |
项目设置
1. 打开项目
在 Android Studio 中打开 android/ 文件夹，Gradle 将自动同步依赖项。
2. 配置基础 URL
打开 app/src/main/assets/config.xml，设置您实例的 URL：
<config>
<base_url>https://yourdomain.com</base_url>
</config>
3. 同步并构建
执行 Build → Make Project，确认一切可以正确编译。
架构
该应用采用标准的 Android MVVM 模式：
| 层级 | 技术 |
|---|---|
| 网络 | Retrofit + OkHttp |
| UI 状态 | ViewModel + LiveData |
| 本地存储 | Room（SQLite 数据库） |
| 推送通知 | Firebase Cloud Messaging（FCM） |
| 凭据存储 | EncryptedSharedPreferences |
认证流程
- 用户在登录界面输入实例 URL 和 API 密钥。
- 应用调用
GET /api/health验证实例是否可访问。 - 应用以 API 密钥作为 Bearer token 调用
GET /api/users/me。 - 成功后，API 密钥保存至 EncryptedSharedPreferences，用户即视为已认证。
推送通知
该应用使用 Firebase Cloud Messaging 推送新线索通知。
- 在 Firebase Console 创建项目。
- 以您应用的包名添加 Android 应用。
- 下载
google-services.json并放置到app/目录。 - 将 FCM 服务器密钥（
FCM_SERVER_KEY）添加到 LeadHub 服务器配置中，以便后端发送通知。
构建发布版本
1. 生成 Keystore
keytool -genkey -v -keystore leadhub.keystore -alias leadhub -keyalg RSA -keysize 2048 -validity 10000
2. 配置签名
在应用的 build.gradle 中的 signingConfigs 部分添加 keystore 信息。
3. 构建发布版 APK / AAB
使用 Android Studio 的 Build → Generate Signed Bundle / APK，或执行：
./gradlew bundleRelease
输出的 AAB 文件位于 app/build/outputs/bundle/release/。
4. 上传至 Google Play
在 Google Play Console 的 正式版 → 创建新版本 中上传 AAB 文件。
使用的 API 端点
| 端点 | 用途 |
|---|---|
GET /api/health | 验证实例可访问性 |
GET /api/users/me | 验证 API 密钥并 获取用户信息 |
GET /api/leads | 获取线索列表 |
GET /api/leads/{id} | 获取线索详情 |
PUT /api/leads/{id} | 更新线索 |
GET /api/pipelines | 获取管道及阶段 |
所需最低 API 密钥权限
| 权限 | 原因 |
|---|---|
read:leads | 查看线索 |
write:leads | 从应用更新线索 |
read:pipelines | 显示管道阶段 |