Vonage Video API Reference App for Android

Welcome to Vonage

If you're new to Vonage, you can sign up for a Vonage API account and get some free credit to get you started.

What is it?

The Vonage Video API Reference App for Android is an open-source video conferencing reference application for the Vonage Video API using the Android SDK.

The Reference App demonstrates the best practices for integrating the Vonage Video API with your application for various use cases, from one-to-one and multi-participant video calling to foreground services integration and more.

Cross-Platform Support

Looking to build on other platforms? The Vonage Video API Reference App is also available for:

• Web (React): vonage-video-react-app
• iOS: vonage-video-ios-app

These reference apps share the same backend infrastructure and demonstrate consistent best practices across all platforms, making it easy to build unified video experiences for your users.

Why use it?

The Vonage Video API Reference App for Android provides developers an easy-to-setup way to get started with using our APIs with the Android SDK.

The application is open-source, so you can not only get started quickly, but easily extend it with features needed for your use case. Any features already implemented in the Reference App use best practices for scalability and security.

As a commercial open-source project, you can also count on a solid information security architecture. While no packaged solution can guarantee absolute security, the transparency that comes with open-source software, combined with the proactive and responsive open-source community and vendors, provides significant advantages in addressing information security challenges compared to closed-source alternatives.

This application provides features for common conferencing use cases, such as:

• A landing page for users to create and join meeting rooms.

  
• A waiting room for users to preview their audio and video device settings and set their name before entering a meeting room.

  
• A post-call page to navigate users to the landing page, re-enter the left room, and display archive(s), if any.

  

• A video conferencing "room" supporting up to 25 participants and the following features:

• Configurable features: adapt the app to your specific use cases and roles. Configuration is handled through JSON files in the config folder (app-config.json, theme.json). The custom Gradle plugin reads these configuration files and generates the necessary build configuration at compile time.
• Call participant list with audio on/off indicator.

  

• Screen sharing integration.

• Active speaker detection.

• Layout manager with options to display active speaker, or all participants in a grid view.

• The dynamic display adjusts to show new joiners, hide video tiles to conserve bandwidth, and show the "next" participant when someone previously speaking leaves.

• Foreground Service: Keeps the video call running in the background with proper Android notification handling.

Project Architecture

This reference app requires the user to deploy a backend and then use the backend API URL as the base URL in the app configuration. You can find backend code and deploying instructions in the vonage-video-react-app repository.

The backend communicates with the Vonage video platform using the Vonage Server SDK and is responsible for generating the session IDs and tokens used to connect to the video rooms by the Vonage Client SDK.

Module Overview

The Vonage Android reference app is built with a modular architecture. The app is organized into the following modules:

• app: Main application module and composition root
• vonage-video-core: Core video SDK wrapper providing the VonageVideoClient, Call abstraction, signaling, and domain models on top of the OpenTok Android SDK
• vonage-video-ui-compose: Jetpack Compose UI component library with a JSON-driven theme generator, reusable widgets, and permission handling
• vonage-video-shared: Shared utilities and common code used across all other modules
• vonage-feature-chat: In-call text chat using OpenTok signaling (optional feature module)
• vonage-feature-reactions: In-call emoji reactions (optional feature module)
• vonage-feature-captions: Live captions and subtitles (optional feature module)
• vonage-feature-archiving: Call recording and archive management (optional feature module)
• vonage-feature-screensharing: Screen sharing via MediaProjection and foreground service (optional feature module)
• vonage-feature-video-effects: Video effects such as background blur and replacement (optional feature module)
• vonage-audio-selector: Audio output device selector with support for Bluetooth, wired headset, earpiece, and speaker
• vonage-android-logger: Lightweight logging library with an interceptor pipeline and structured log events
• vonage-config-idea-plugin: Android Studio / IntelliJ plugin for managing configurable features
• build-tools: Custom Gradle plugins for JSON-to-Kotlin config generation, theme generation, Detekt, Kover, and SonarQube integration

Platforms supported

The current minimum deployment target for the reference app is Android 7.0 (API 24+). The app is optimized for phones and tablets and supports the following architectures: ARM64-v8a, ARMv7, x86, and x86_64.

Vonage Video SDK Compatibility

This reference app has been tested with Vonage Video SDK 2.32 and 2.33. We strongly recommend using the latest available SDK version to take advantage of the newest features and avoid potential issues with older releases.

The SDK version is declared in the version catalog file (gradle/libs.versions.toml) and can be adjusted there if needed.

Requirements

• Android Studio: Ladybug (2024.2.1) or newer
• JDK: Version 17 or higher
• Gradle: 8.13.0+ (via wrapper)

Running Locally

First follow the steps to create the Vonage account, application and backend set up and deployment at the vonage-video-react-app URL.

Clone the repository:

git clone https://github.com/Vonage/vonage-video-android-app.git
cd vonage-video-android-app

Configure the application by editing the JSON files in the config folder:

• app-config.json: Feature flags and application settings
• theme.json: UI theme configuration

Modify the base URL constant in your configuration to point to your deployed backend.

You could create local.properties in the project root (good for local development):

BASE_API_URL=https://your-backend-url.com

or create a environment variable named BASE_API_URL (good for CI/CD pipelines):

export BASE_API_URL=https://your-backend-url.com

or even modify app-config.json replacing the current placeholder with your URL.

Then regenerate the configuration:

./gradlew generateVonageConfig

Open the project in Android Studio and let Gradle sync complete.

Build and run the app:

./gradlew installDebug

Or use Android Studio's run button (▶️) to build and deploy to a connected device or emulator.

Note: If you need to run the app in an emulator consuming a local backend, you could set BASE_API_URL to the special alias 10.0.2.2

Feature configuration

You can fork the repository and start modifying it for your needs. Or you can modify the configuration files in the config folder:

• app-config.json: Configure feature flags like chat, captions, screen sharing, background blur, etc.
• The custom Gradle plugin (JsonConfigPlugin) reads these configuration files at build time
• Features can be enabled/disabled without code changes
• Some features use product flavors (e.g., chat module with enabled/disabled variants)

See docs/CONFIG-SYSTEM.md for detailed configuration documentation.

Theme customization

You can customize the app colors by editing the config/theme.json file with your desired color scheme values. The ThemeGeneratorPlugin Gradle plugin will generate the necessary theme resources in the compose module at build time.

Multi-Language Support

The app is fully prepared for internationalization using Android's string resources (strings.xml). All user-facing strings are localized through stringResource() in Jetpack Compose, making it straightforward to add support for new languages.

Testing

This project uses a combination of frameworks for comprehensive test coverage:

• Unit tests: JUnit 4/5, MockK, Turbine (Flow testing), Kotlinx Coroutines Test, and AndroidX Core Testing
• UI / Instrumented tests: Compose UI Test, Espresso, Hilt Testing, and AndroidX Test Runner/Rules
• Coverage: Kover for code coverage reports, integrated with SonarQube

Unit tests are spread across multiple modules (app, vonage-video-core, vonage-audio-selector, vonage-video-shared, vonage-android-logger, vonage-feature-chat, and vonage-config-idea-plugin). Instrumented tests live in the app module and follow a Page Object / Screen Object pattern with a custom HiltTestRunner for dependency injection support.

Run tests from the command line:

# Run all unit tests
./gradlew test

# Run tests for a specific module
./gradlew :vonage-video-core:test

# Run instrumented tests (requires connected device/emulator)
./gradlew connectedAndroidTest

# Run instrumented tests on Gradle Managed Devices (no physical device needed)
./gradlew pixelDebugAndroidTest

# Generate code coverage report
./gradlew koverHtmlReport

Or run tests in Android Studio by right-clicking on test files or packages and selecting "Run Tests".

Code style

We use Detekt for static analysis and Spotless for code formatting. Check and fix code style by running:

# Check code style
./gradlew detekt

# Run all quality checks
./gradlew check

Code of Conduct

Please read our Code of Conduct.

Getting Involved

If you wish to contribute to this project, read how in Contributing.

Known Issues

We track known issues in Known Issues. Please refer to it for details.

Report Issues

If you have any issues, feel free to open an issue or reach out to support via support@api.vonage.com.

Getting Help

We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either:

• Open an issue on this repository
• Tweet at us! We're @VonageDev on Twitter
• Or join the Vonage Developer Community Slack

Further Reading

• Check out the Developer Documentation at https://developer.vonage.com/