Android demo guide and download

A runnable Android example app (Kotlin, plus one screen written in Java), downloaded together with the SDK source. It demonstrates sign-in and registration, conversations, all message types, friends, group chat, profiles and audio and video calls, and serves as a reference for your own integration.

Download Android SDK + Demo (2.0.1) · SHA256 checksum file

After unzipping, go into deeprespond-im-android-sdk-demo-2.0.1 and run sha256sum -c SHA256SUMS to verify the files; on Windows, check the ZIP's SHA256 with Get-FileHash.

Test status

All the demo's features are implemented, but the latest two-device automated run passed 42 of 51 steps; reaction sync, voice, the call entry and a few others still need retesting. See Verification status. Treat it as an integration example, not as proof that every feature has been verified.

Get it and set up

The download includes the SDK, the example app, the Gradle Wrapper, design docs and test data. It doesn't include an APK, prebuilt Maven packages, the IM server or local configuration. All commands below run in the sdk/android directory (the same directory in the full repository).

You'll need:

• JDK 17, Android SDK Platform 36 and the matching build tools;
• a device or emulator on Android 7.0 (API 24) or later;
• a reachable IM service, its AppKey, and two users in the same app (password sign-in and registration must be allowed by the app's policies).

The project uses Kotlin 2.4 and AGP 9.1, with Java and Kotlin targeting 11. The "compileSdk at least 35" in the overview is a requirement for apps that use the SDK, not for building this project.

Open sdk/android in Android Studio, set the Gradle JDK to 17 and set your Android SDK path. On the command line, set JAVA_HOME and ANDROID_HOME, and create your own local.properties if needed (sdk.dir=absolute path of your SDK). On Windows use gradlew.bat, and join multi-line commands into one line in PowerShell.

Build and install

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

• You can also pick the example module and a device in Android Studio and run it; with only one device connected, ./gradlew :example:installDebug works too.
• The application ID is com.deeprespond.im.example. The release build has R8 on but still uses the debug signature, for local testing only; your production app needs its own signing configuration.

Connecting to the service with two accounts

1. On the home screen, enter the service URL, AppKey, username and password, accept the privacy notice, then sign in or register. No Client Secret is needed.
2. Sign in as another user of the same app on a second device, add each other as friends, then test messages, read receipts and group chat.
3. The service URL, AppKey and sign-in state are restored after a restart. Sign out before switching accounts; clear the demo's data before switching apps (see Troubleshooting).

The default URL on the home screen, http://127.0.0.1:18480, refers to the device itself. To connect to a local IM service running on your development machine (see Local IM service), set up port forwarding for each USB or adb device:

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

Port	Purpose
18480	The IM service API
7885, 7886	Local LiveKit (audio and video)
9010	Object storage for attachments

Adjust the ports to your deployment. 18490 is the test service's control API; forward it only when automated tests on the device need it.

• With several devices connected, every adb command must name the device with -s.
• Real devices can also connect to a reachable HTTPS URL directly. Note that a reachable API doesn't mean the attachment and audio/video URLs are reachable too.
• The demo allows HTTP for local debugging; production apps should use TLS and their own network security configuration.

Local IM service

Running a local IM test service on your development machine needs the full IM repository (the download includes neither the server nor the infrastructure it depends on). From the repository root:

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:

• Make sure the ports are free first; if you change ports, update the demo's home screen URL and the port forwarding to match.
• The test service's control API GET /env returns the AppKey; the server credentials from GET /credentials stay on the backend and never go into the app.
• Don't let tests for several SDKs change registration, friend or audio/video policies of the same test app at the same time.

Features and structure

The files are in example/src/main/java/com/deeprespond/im/example/:

File	Responsibility
MainActivity.kt	Sign-in, the three tabs, conversations, contacts, profile and state subscriptions
ChatActivity.kt	Messages, voice recording, replies, reactions, forwarding, recall, read receipts and drafts
RequestsActivity.kt, FriendProfileActivity.kt	Friend requests and profiles
GroupSettingsActivity.kt, ChatSettingsActivity.kt	Group and conversation settings
CallActivity.kt, IncomingCallActivity.kt	Calls and the incoming-call screen
JavaFacadeActivity.java	A screen that calls the SDK through its Java API
Demo.kt, Ui.kt and others	Shared state and UI helpers

• This is an example app, not a chat UI component library. Your app handles privacy consent, media permissions, Firebase and vendor accounts, and notification and incoming-call configuration.
• vendor-stubs exist only so the project compiles; they're not a real push SDK.
• To test calls, turn on audio and video in the app's policies, and make sure both devices can reach LiveKit. Emulators without a display can't verify real call audio quality.
• Calls and standalone channels are tested separately; this demo doesn't mean every channel scenario has been tested on real devices.

Verification status

Test	Result
SDK (2026-10-08)	273 unit tests, 66 real-API tests and 26 device tests passed; Lint, ABI checks, R8, local Maven publishing and the consumer example build all passed
Example app (2026-10-19 to 20)	The final two-emulator automated run passed 42 of 51 steps; the 9 failed steps have step-by-step assertion logs and screenshots
Steps to retest	Reaction sync, voice and the steps that depend on it, the call entry and incoming calls, the clear-history assertion, the Java screen; some failures relate to emulator UI timing and need a rerun to confirm
Not yet tested	Real vendor push, real devices of each brand, battery saving, call quality, production release

The detailed report is Agent测试/AndroidSDK与Demo完善/测试报告.md in the full repository. Note that earlier SDK test passes don't mean every automated test of the new example app passed.

From the repository root you can run three kinds of tests, which don't replace each other: make sdk-android-test, make sdk-android-integration and make sdk-android-device-test; the last two need a real service and devices. The download can build with Gradle in sdk/android, but tests that need a server still need the test service from the full repository.

Troubleshooting

Symptom	Check
SDK / JDK not found	Gradle JDK 17, Platform 36, JAVA_HOME / ANDROID_HOME or your local.properties
Dependency resolution fails	That Google, Maven Central and JitPack are reachable, and the repositories in settings.gradle.kts
Install fails with several devices	Run adb devices -l and name the device serial explicitly
API works but images or calls fail	Attachment domain, object storage and LiveKit ports, policies and permissions
Sign-in or registration rejected	AppKey, username and password, app policies and which app the account belongs to
No real push	Firebase or vendor channels, console credential IDs, notification permission and system restrictions
Tests see old data	Sign out first; for the test demo only, run adb -s <device serial> shell pm clear com.deeprespond.im.example, which clears all of the demo's local data

For SDK, Java, push, call and channel usage, see the Android SDK docs.