Android 环境要求与 SDK 引入
SDK Version: 1.0.0
Platform: Android
1. 构建基线
| 项目 | 要求 |
|---|---|
| Android | minSdk 26 或更高 |
| 编译参考 | compileSdk 36 |
| Java/Kotlin | JDK 17，Kotlin JVM target 17 |
| 设备 | 支持 BLE 的 Android 真机，系统蓝牙已开启 |
2. 获取 Release 产物
客户通过约定交付渠道取得 SDK 1.0.0 的正式 Release AAR、依赖清单、校验值和混淆规则。文档 ZIP 不包含 AAR；不要把测试产物用于上架版本。
按业务选择交付物，不要求每个 App 全部引入：
| SDK 产品 | 交付模块名 | 主要入口 |
|---|---|---|
| BLE | ble-sdk | XTalkBleClient |
| Channel Presence | channel-presence-sdk | ChannelPresenceScanSdk |
| Device Auth | device-auth-sdk | DeviceAuthenticator |
| Device Init | device-init-sdk | DeviceInitializer |
| Mesh | mesh-sdk | MeshSdk |
| Low Latency PTT | low-latency-ptt-sdk | LowLatencyPttSdk |
| OTA | ota-sdk | XTalkTurMassOtaManager / XTalkBluetoothFotaManager |
| Radio Transport | radio-transport-sdk | RadioTransport |
| STT | stt-sdk | XTalkStt |
| UART | uart-sdk | XTalkUartClient / UartRadioTransport |
把全部交付 AAR 放入 App 模块的 libs：
dependencies {
implementation(fileTree("libs") { include("*.aar") })
}
Groovy：
dependencies {
implementation fileTree(dir: "libs", include: ["*.aar"])
}
AAR 不会自动内嵌所有外部依赖。必须逐项加入交付清单列出的依赖，且各 AAR 保持同一 SDK 版本。核心 SDK 默认按正式 AAR 交付；若交付清单提供客户专用 Maven 仓库，则以清单中的仓库地址、凭据和坐标为准，本文不提供公共仓库地址。
例如 Mesh 走 BLE 时，至少需要 Mesh、BLE 和它们交付清单中的传递依赖；Low Latency PTT 还需要客户实现或接入其 transport 与音频编解码链。不要通过复制 SDK 源码接入。
3. Manifest 与运行时权限
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- 只有使用采集语音时才需要 -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
- Android 12/API 31 以上：动态申请
BLUETOOTH_SCAN与BLUETOOTH_CONNECT。 - Android 11/API 30 以下：扫描需要
ACCESS_FINE_LOCATION。 RECORD_AUDIO只用于 PTT/实时语音采集；普通 BLE、AT、RF、文本和文件不需要它。POST_NOTIFICATIONS只在客户 App 实际发送通知且系统要求时申请。
SDK 权限辅助函数：
val blePermissions = requiredBluetoothPermissions()
val bleGranted = hasBluetoothPermissions(context)
// 包含 BLE、录音，并在需要时包含通知权限；适合启用全部能力的 App。
val allStartupPermissions = requiredStartupPermissions()
val allGranted = hasStartupPermissions(context)
辅助函数只计算/检查权限，不弹系统授权框。Activity 或 Fragment 仍需使用 Activity Result API 请求权限，并在拒绝时停止扫描或录音。
4. 初始化与结果处理
在 Application.onCreate() 或 BLE 功能首次进入时调用：
XTalkBleClient.setApplicationContext(applicationContext)
val result = XTalkBleClient.ensureInitialized()
check(result == InitResult.INIT_OK) { "xTalk initialization failed: $result" }
setApplicationContext 会保存 Application Context，不会持有 Activity。ensureInitialized 可重复调用；非 INIT_OK 时不要继续扫描。
5. Release/R8 检查
- 使用交付清单中的 consumer/ProGuard 规则，不自行猜测类名。
- 确认所有 AAR、外部依赖和 ABI 文件齐全。
- 在启用
minifyEnabled的 Release 变体上执行扫描、连接、Auth、Init 和收发冒烟测试。 - 若仅 Release 失败，保留完整异常堆栈、设备型号和系统版本，交给 xTalk 支持；不要通过整体关闭混淆掩盖问题。