iOS 应用
本指南面向构建或定制 LeadHub iOS 伴侣应用的开发者。应用源代码使用 Swift 编写，支持 iPhone 和 iPad。
环境要求
- Xcode 15 或更高版本（仅限 macOS）
- Swift 5.9 或更高版本
- iOS 部署目标：最低 iOS 15.0
- Apple Developer 账户（TestFlight 和 App Store 分发所必需）
- 拥有有效 HTTPS URL 和活跃 API 密钥的 LeadHub 实例
项目设置
- 在 Xcode 中打开 LeadHub 购买包中的
ios/文件夹。 - 如果存在 CocoaPods 或 Swift Package Manager 依赖，请打开
.xcworkspace文件（而非.xcodeproj）。 - 在项目的 Signing & Capabilities 设置中选择您的开发团队。
- 在模拟器或设备上构建并运行。
架构
该应用采用标准 iOS 架构：
- URLSession 配合自定义 API 客户端，用于向 LeadHub REST API 发起 HTTP 请求
- Combine 或 async/await 处理异步操作
- SwiftUI 构建用户界面
- CoreData 在会话之间本地缓存线索
- Apple Push Notification Service（APNs） 处理推送通知
API 密钥使用 Security 框架存储在 iOS Keychain 中。
认证流程
- 用户在引导页面输入 LeadHub 实例 URL 和 API 密钥。
- 应用发送
GET /api/v1/health请求，验证实例是否可通过 HTTPS 访问。 - 通过发送经认证的测试请求来验证 API 密钥的有效性。
- URL 和 API 密钥存储在 Keychain 中。
推送通知
推送通知使用 Apple Push Notification Service（APNs）。
- 在 Apple Developer 账户中，在 Certificates, Identifiers & Profiles → Keys 下创建 APNs 密钥（.p8 文件）。
- 记录 Key ID 和 Team ID。
- 在 LeadHub 后端配置中设置
APNS_KEY、APNS_KEY_ID、APNS_TEAM_ID和APNS_BUNDLE_ID。 - 在 Xcode 的 Signing & Capabilities 下启用 Push Notifications 功能。
应用在首次启动时注册推送通知，并通过 API 将设备令牌发送到 LeadHub 后端。
构建发布版本
- 在 Xcode 中通过 Product → Archive 打包应用。
- 在 Organizer 窗口中点击 Distribute App。
- 选择 App Store Connect 进行 App Store 发布，或选择 TestFlight 进行 Beta 测试。
- 按照 Xcode 提示完成上传。
使用的 API 端点
| 端点 | 用途 |
|---|---|
GET /api/v1/health | 验证实例连通性 |
GET /api/v1/leads | 加载线索列表 |
GET /api/v1/leads/{id} | 加载线索详情 |
PATCH /api/v1/leads/{id} | 更新线索状态或阶段 |
POST /api/v1/leads/{id}/tags | 为线索添加标签 |
GET /api/v1/pipelines | 加载管道列表用于阶段选择器 |
所需最低 API 密钥权限
| 权限 | 原因 |
|---|---|
read:leads | 查看线索 |
write:leads | 更新线索状态、阶段和标签 |
read:pipelines | 填充管道阶段选择器 |
App Store 隐私披露
提交至 App Store 时，在 App Privacy 部分声明以下数据用途：
- 联系信息（电子邮件、电话）— 从线索收集，而非用户
- 标识符（API 密钥）— 与用户关联，用于身份验证
- 使用数据 — 不收集