Agora Android Compose API Examples

English | 中文

A Jetpack Compose Android sample app that demonstrates common Agora RTC use cases with small, focused screens. The project is useful when you want to see how individual Agora APIs fit into a modern Compose application.

Screenshot Checklist

Use this table as the screenshot inventory for the README, docs, or release assets. Add new images under art/screenshots/ and replace Coming soon with an image preview.

Group	App Label	Screenshot
Basic	Join Video Channel (With Token)	Coming soon
Basic	Join Video Channel
Basic	Join Audio Channel	Coming soon
Advance	Live Streaming	Coming soon
Advance	RTMP Streaming	Coming soon
Advance	Media Metadata	Coming soon
Advance	Voice Effects	Coming soon
Advance	Origin Audio Data	Coming soon
Advance	Custom Audio Source	Coming soon
Advance	Custom Audio Render	Coming soon
Advance	Origin Video Data	Coming soon
Advance	Custom Video Source	Coming soon
Advance	Custom Video Render	Coming soon
Advance	Picture In Picture	Coming soon
Advance	Join Multi Channel	Coming soon
Advance	Channel Encryption	Coming soon
Advance	Play Audio Files	Coming soon
Advance	Pre Call Test	Coming soon
Advance	Media Recorder	Coming soon
Advance	Media Player	Coming soon
Advance	Screen Sharing	Coming soon
Advance	Video Process Extension	Coming soon
Advance	Rhythm Player	Coming soon
Advance	Local Video Transcoding	Coming soon
Advance	Send Data Stream	Coming soon
Advance	Host Across Channel	Coming soon
Advance	Spatial Sound	Coming soon
Chat	1:1 Chat	GIF image message demo
Chat	Group Chat	Coming soon
Chat	Typing Indicator	Coming soon
Chat	Presence	Coming soon
Chat	Message Reactions	Coming soon

What Is Included

• Basic audio and video channel joining examples.
• Token-based and App Certificate-based token generation flows.
• Live streaming, RTMP streaming, media metadata, channel encryption, media recording, media player, screen sharing, picture-in-picture, spatial audio, and data stream examples.
• Agora Chat SDK examples for 1:1 chat, group chat, GIF image messages, typing indicators, presence, and reactions.
• Custom audio/video source and render examples.
• Compose-first navigation, shared controls, and settings for video profile, frame rate, orientation, and Agora area code.

Chat SDK Features

The Chat section of the app demonstrates Agora Chat SDK flows in one shared Compose screen:

• 1:1 Chat: direct text messages, local conversation history, delivery callbacks, and read callbacks.
• Group Chat: create or join a Chat group, then send messages to the group conversation.
• GIF image messages: pick a .gif from the Android document picker, send it with ChatMessage.createGifImageMessage, and preview sent or received GIFs in the message bubble.
• Typing Indicator: lightweight command messages for "user is typing" UI.
• Presence: publish and subscribe to online presence state.
• Message Reactions: add native Chat SDK reactions to existing messages.

Chat users are separate from RTC UIDs. The Chat samples require AGORA_CHAT_APP_KEY and real Agora Chat users. Password login uses a Chat user password. Token login uses a Chat user token generated for the exact same Chat user ID; RTC tokens, App IDs, and App Certificates cannot be pasted into the Chat token field.

Documentation

Start here, then jump into the topic you need:

• Setup Guide: install requirements, configure Agora credentials, run builds, and use a local SDK.
• Architecture: project layout, navigation, sample registration, lifecycle, state, and shared utilities.
• Feature Guide: Agora vocabulary and plain-English explanations of every implemented sample.
• Sample Catalog: every included sample, where it lives, and what it demonstrates.
• Chat GIF Messages: how GIF image messages are picked, sent, received, downloaded, previewed, and tested.
• Join Channel Video: how the basic video-call sample joins, renders, tracks callbacks, and debugs media flow.
• Development Guide: commands, coding conventions, adding a new sample, testing, and release notes.
• Troubleshooting: common build, credential, permission, and runtime issues.

Quick Start

1. Clone the repository and open it in Android Studio.

2. Sign in or create an Agora account at Agora signup/login, then create or select a project and copy its App ID and optional App Certificate.

3. Create or edit local.properties in the project root:

   sdk.dir=/path/to/Android/Sdk
   AGORA_APP_ID=your_agora_app_id
   AGORA_APP_CERT=your_agora_app_certificate_optional
   AGORA_TOKEN_SERVER_URL=https://your-token-server.example.com/token
   AGORA_CHAT_APP_KEY=your_agora_chat_app_key

4. Build and install:

   ./gradlew assembleDebug
   ./gradlew installDebug

5. Launch APIExample-Compose on a physical Android device or emulator.

AGORA_APP_ID is required for RTC samples. AGORA_CHAT_APP_KEY is required for Chat SDK samples and must be the Agora Chat app key, usually in org#app format. RTC App ID and Chat app key are not interchangeable. AGORA_TOKEN_SERVER_URL is recommended for token-secured RTC samples. For an emulator talking to a token server on your Mac, use http://10.0.2.2:<port>/....

AGORA_APP_CERT is optional and should only be used for local demos without a token server. Production apps must generate tokens on a trusted backend rather than shipping an App Certificate in the client.

For Chat projects where client-side user registration is disabled, generate local test users and Chat user tokens from your workstation:

npm install
npm run chat:test-tokens

Paste the printed user token into the Chat sample with auth mode set to Token. The helper is only for local testing and reads credentials from local.properties; production apps should use a trusted backend.

Quick Chat Test

Use two devices, two emulators, or one physical device plus one emulator:

1. Device A: open Chat > 1:1 Chat, set User ID to a1, and set Target User ID to a2.
2. Device B: open Chat > 1:1 Chat, set User ID to a2, and set Target User ID to a1.
3. If password registration is enabled for your Chat project, tap Register demo user once for each user and log in with the same password.
4. If registration is disabled, run npm run chat:test-tokens, switch auth mode to Token, and paste the token printed for the matching user ID.
5. Send text both ways, then tap the GIF button in the composer and choose a .gif file. The sender should show GIF sent; the receiver should show a GIF preview after the attachment downloads.

If login fails with user does not exist, create the Chat user in the same Chat project as AGORA_CHAT_APP_KEY or use npm run chat:test-tokens. If login fails with auth errors, check that the token is a Chat user token for that exact user ID and has not expired.

Requirements

• Android Studio with JDK 17.
• Android SDK matching compileSdk = 37.
• Android device or emulator running API 24 or later.
• Agora project App ID from Agora signup/login or the Agora Console.

See the Setup Guide for full details.

Build Commands

./gradlew assembleDebug          # Build debug APK
./gradlew installDebug           # Install debug APK on a connected device
./gradlew test                   # Run local unit tests
./gradlew connectedAndroidTest   # Run instrumented tests on a device

Project Snapshot

app/src/main/java/io/agora/api/example/compose/
├── APIExampleApp.kt             # Compose app entry
├── MainActivity.kt              # Android activity host
├── NavGraph.kt                  # Navigation graph
├── data/                        # In-memory settings
├── model/                       # Example registration
├── samples/                     # Agora API demo screens
├── ui/                          # Shared Compose UI
└── utils/                       # Token, media, file, and render helpers

The app registers examples manually in Examples.kt. The home screen groups them into Basic, Advance, and Chat sections.

Security Notes

• Do not commit local.properties.
• Do not commit keystores, signing passwords, App Certificates, generated tokens, APKs, or AABs.
• .gitignore excludes local Android/Gradle files, build output, and common secret file types.
• The sample token helper is for demos. Production token generation belongs on a trusted backend.

Support

• Agora documentation: docs.agora.io
• Agora samples: github.com/AgoraIO
• Issues for Agora API examples: AgoraIO/API-Examples issues
• Community questions: Stack Overflow agora.io tag

License

This project is released under the MIT License. See LICENSE.