Android Demo 运行指南与下载

一个可以直接运行的 Android 示例 App（Kotlin，另有一个用 Java 写的页面），和 SDK 源码一起下载。它演示登录注册、会话、各种消息、好友、群聊、资料和音视频通话，可以作为接入的参考。

下载 Android SDK + Demo（2.0.1） · SHA256 校验文件

解压后进入 deeprespond-im-android-sdk-demo-2.0.1，先运行 sha256sum -c SHA256SUMS 核对文件；Windows 用 Get-FileHash 核对 ZIP 的 SHA256。

测试状态

示例的功能都已实现，但最近一轮双设备自动测试为 51 步中通过 42 步，表情回应同步、语音、通话入口等还要复测，见验证边界。请把它当作接入示例，不要当作所有功能都已验证的证明。

获取与环境

下载包包含 SDK、示例 App、Gradle Wrapper、设计文档和测试数据，不包含 APK、编译好的 Maven 包、IM 服务端和本机配置。下文的命令都在 sdk/android 目录中执行（完整仓库中也是这个目录）。

需要准备：

• JDK 17、Android SDK Platform 36 和对应的构建工具；
• Android 7.0（API 24）以上的设备或模拟器；
• 一个能访问的 IM 服务、它的 AppKey，以及同一应用下的两个用户（密码登录和注册要应用策略允许）。

工程使用 Kotlin 2.4、AGP 9.1，Java 和 Kotlin 编译目标为 11。概述中“compileSdk 至少 35”是对接入 SDK 的 App 的要求，不是本工程的编译要求。

用 Android Studio 打开 sdk/android，把 Gradle JDK 设为 17，并设置本机的 Android SDK 路径。用命令行时设置 JAVA_HOME、ANDROID_HOME，需要时自己创建 local.properties（sdk.dir=本机 SDK 的绝对路径）。Windows 用 gradlew.bat，在 PowerShell 中把多行命令合成一行。

构建与安装

cd sdk/android
./gradlew --console=plain :example:assembleDebug
adb devices -l
adb -s <设备序列号> install -r example/build/outputs/apk/debug/example-debug.apk
adb -s <设备序列号> shell am start -n com.deeprespond.im.example/.MainActivity

• 也可以在 Android Studio 中选择 example 模块和设备运行；只连了一台设备时可以用 ./gradlew :example:installDebug。
• 应用 ID 为 com.deeprespond.im.example。Release 版开启了 R8，但仍用调试签名，只用于本地验证；你的正式 App 要配置自己的签名。

服务连接与双账号

1. 在首页填写服务地址、AppKey、用户名和密码，同意隐私说明后登录或注册。不需要填写 Client Secret。
2. 在另一台设备上登录同一应用的另一个用户，互加好友，再测试消息、已读和群聊。
3. 服务地址、AppKey 和登录状态在重启后恢复。换账号前先退出；换应用前先清除示例的数据（见排查）。

首页默认的地址 http://127.0.0.1:18480 指的是设备自己。要连接开发机上运行的本地 IM 服务（见本机 IM 服务），对每台 USB 或 adb 设备分别做端口转发：

adb -s <设备序列号> reverse tcp:18480 tcp:18480
adb -s <设备序列号> reverse tcp:7885 tcp:7885
adb -s <设备序列号> reverse tcp:7886 tcp:7886
adb -s <设备序列号> reverse tcp:9010 tcp:9010

端口	用途
18480	IM 服务的接口
7885、7886	本机的 LiveKit（音视频）
9010	存放附件的对象存储

按实际部署调整端口。18490 是测试服务的控制接口，只在设备上的自动测试需要访问它时才转发。

• 连了多台设备时，adb 命令必须用 -s 指定设备。
• 真机也可以直接连接能访问的 HTTPS 地址。注意接口能访问，不代表附件和音视频的地址也能访问。
• 示例允许在本机调试时使用 HTTP；正式 App 请使用 TLS 和自己的网络安全配置。

本机 IM 服务

在开发机上运行一个本地的 IM 测试服务，需要完整的 IM 仓库（下载包中不包含服务端和它依赖的基础设施）。在仓库根目录执行：

make infra-up
go build -o /tmp/android-demo-harness ./sdk/conformance/harness
/tmp/android-demo-harness -env .env -addr 127.0.0.1:18480 -control 127.0.0.1:18490 \
  -db im_android_demo -redis-prefix android-demo:

• 先确认端口没有被占用；换了端口时，同步修改示例首页的地址和端口转发。
• 测试服务的控制接口 GET /env 返回 AppKey；GET /credentials 返回的服务端凭据只留在后端，不要放进 App。
• 多个 SDK 的测试不要同时修改同一个测试应用的注册、好友或音视频策略。

功能与结构

文件位于 example/src/main/java/com/deeprespond/im/example/：

文件	职责
MainActivity.kt	登录、三页签、会话、联系人、资料和状态订阅
ChatActivity.kt	消息、录音、回复、回应、转发、撤回、已读和草稿
RequestsActivity.kt、FriendProfileActivity.kt	好友申请和资料
GroupSettingsActivity.kt、ChatSettingsActivity.kt	群和会话设置
CallActivity.kt、IncomingCallActivity.kt	通话和来电入口
JavaFacadeActivity.java	用 Java 接口调用 SDK 的页面
Demo.kt、Ui.kt 等	共享状态与 UI 辅助

• 这是示例 App，不是聊天界面组件库。隐私同意、媒体权限、Firebase 和厂商账号、通知和来电的配置都要由你的 App 处理。
• vendor-stubs 只用于通过编译，不能当作正式的推送 SDK。
• 测试通话要在应用策略中开启音视频，两台设备都要能访问 LiveKit。没有界面的模拟器无法检验真实的通话音质。
• 通话和独立频道是分开测试的；这个示例不代表频道的所有场景都已在真机上测试过。

验证边界

测试	结果
SDK（2026-10-08）	273 项单元测试、66 项真实接口测试、26 项设备测试通过；Lint、ABI 检查、R8、本地 Maven 发布和接入示例工程的构建都通过
示例 App（2026-10-19～20）	双模拟器自动测试的最后一轮，51 步中通过 42 步；未通过的 9 步留有逐步的断言记录和截图
还要复测的步骤	表情回应同步、语音及依赖它的步骤、通话入口和来电、清空记录的断言、Java 页面；部分失败与模拟器界面的时序有关，需要重新运行确认
还没有测试	真实的厂商推送、各品牌真机、省电策略、通话质量、正式发布

详细报告在完整仓库的 Agent测试/AndroidSDK与Demo完善/测试报告.md。注意：早期的 SDK 测试通过，不代表新版示例 App 的全部自动测试都通过了。

在仓库根目录可以运行三类测试，它们互不替代：make sdk-android-test、make sdk-android-integration、make sdk-android-device-test，后两项需要真实的服务和设备。下载包可以在 sdk/android 中用 Gradle 构建，但需要服务端的测试仍要完整仓库中的测试服务。

排查

现象	检查
找不到 SDK / JDK	Gradle JDK 17、Platform 36、JAVA_HOME / ANDROID_HOME 或本机 local.properties
依赖解析失败	Google、Maven Central、JitPack 可达及 settings.gradle.kts 仓库配置
多设备安装失败	adb devices -l 后显式指定序列号
API 正常但图片/通话失败	附件域名、对象存储/LiveKit 端口、策略及权限
登录/注册被拒绝	AppKey、账号密码、应用策略及账号归属
没有真实推送	Firebase/厂商通道、控制台凭据编号、通知权限和系统限制
测试读到旧数据	先退出；仅对测试 Demo 执行 adb -s <设备序列号> shell pm clear com.deeprespond.im.example，会清除示例全部本地数据

SDK、Java、推送、通话和频道的用法见 Android SDK 文档。