Skip to main content

​
Prerequisites

Before setting up the Android app, ensure you have the following installed:
1

Install Java Development Kit (JDK)

Install JDK 11 or higher. You can verify your installation:
java -version
2

Install Android Studio

Download and install Android Studio with the following components:
  • Android SDK
  • Android SDK Platform
  • Android Virtual Device (AVD)
3

Configure Environment Variables

Add the following to your shell profile (~/.bashrc, ~/.zshrc, etc.):
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
4

Install Capacitor CLI

Install the Capacitor CLI globally:
npm install -g @capacitor/cli

​
Project Configuration

MediGuide uses Capacitor 8.1.0 to bridge the web application with native Android functionality.

​
Build Configuration

The Android project uses the following configuration:
android/variables.gradle
ext {
    minSdkVersion = 24
    compileSdkVersion = 36
    targetSdkVersion = 36
    androidxActivityVersion = '1.11.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.17.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.14.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '14.0.1'
}
MediGuide requires a minimum Android SDK version of 24 (Android 7.0 Nougat).

​
Installing Dependencies

1

Install Node Dependencies

First, install all Node.js dependencies:
npm install
This will install Capacitor and all required packages including:
  • @capacitor/android (^8.1.0)
  • @capacitor/cli (^8.1.0)
  • @capacitor/core (^8.1.0)
2

Build Web Assets

Build the web application that will be bundled into the Android app:
npm run build
This creates the production build in the dist directory.
3

Sync Capacitor

Sync your web app with the Android platform:
npx cap sync android
This command:
  • Copies web assets to the Android project
  • Updates native dependencies
  • Syncs Capacitor plugins

​
Building the Android App

​
Using Android Studio

1

Open Project in Android Studio

npx cap open android
This opens the Android project in Android Studio.
2

Sync Gradle

Android Studio will automatically sync Gradle files. Wait for this process to complete.
3

Build the APK

  • Select Build > Build Bundle(s) / APK(s) > Build APK(s)
  • Wait for the build to complete
  • The APK will be located in android/app/build/outputs/apk/

​
Using Command Line

You can also build the app using Gradle from the command line: 
cd android
./gradlew assembleDebug
Release builds require proper signing configuration. Ensure you have configured your keystore in android/app/build.gradle before creating release builds.

​
Running the App

​
On an Emulator

1

Create an AVD

In Android Studio:
  • Go to Tools > Device Manager
  • Click Create Device
  • Select a device definition (e.g., Pixel 5)
  • Download and select a system image (Android 7.0 or higher)
  • Finish setup
2

Run the App

npx cap run android
Or use Android Studio’s Run button (green triangle).

​
On a Physical Device

1

Enable Developer Options

On your Android device:
  • Go to Settings > About Phone
  • Tap Build Number 7 times
  • Navigate to Settings > Developer Options
  • Enable USB Debugging
2

Connect Device

Connect your device via USB and verify it’s recognized:
adb devices
You should see your device listed.
3

Run the App

npx cap run android --target YOUR_DEVICE_ID

​
Project Structure

The Android project structure follows the standard Capacitor layout: 
android/
├── app/
│   ├── src/
│   │   └── main/
│   │       ├── java/com/mediguide/app/
│   │       │   └── MainActivity.java
│   │       ├── res/
│   │       └── AndroidManifest.xml
│   ├── build.gradle
│   └── capacitor.build.gradle
├── gradle/
├── build.gradle
├── gradle.properties
├── settings.gradle
└── variables.gradle

​
MainActivity

The main entry point for the Android app extends Capacitor’s BridgeActivity:
android/app/src/main/java/com/mediguide/app/MainActivity.java
package com.mediguide.app;

import com.getcapacitor.BridgeActivity;

public class MainActivity extends BridgeActivity {}
Capacitor handles all the bridging between your web code and native Android functionality through BridgeActivity.

​
Common Issues

​
Gradle Build Failures

If you encounter Gradle build errors:
  1. Clean the project: 
    cd android
./gradlew clean
  2. Invalidate caches in Android Studio:
    • File > Invalidate Caches > Invalidate and Restart

​
App Not Syncing

If changes aren’t appearing in the app: 
npm run build
npx cap sync android

​
ADB Connection Issues

If your device isn’t recognized: 
adb kill-server
adb start-server
adb devices

​
Live Reload

For faster development, you can use live reload:
1

Start Dev Server

npm run dev
Note the URL (e.g., http://localhost:5173)
2

Configure Server URL

Update capacitor.config.json temporarily:
{
  "server": {
    "url": "http://YOUR_COMPUTER_IP:5173",
    "cleartext": true
  }
}
3

Sync and Run

npx cap sync android
npx cap run android
Remember to remove the server configuration before building for production.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us