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 文件。