Android App Installation

EmbyTok can be built as a native Android application using Capacitor, which wraps the web app in a native container with access to device features.

Prerequisites

Before building the Android app, ensure you have:

Node.js

Version 14 or higher (v20 recommended)

Android Studio

Latest stable version with Android SDK

Java JDK

JDK 17 or higher

Android SDK

API Level 22+ (Android 5.1+)

Installation Steps

Clone and install dependencies

If you haven’t already, clone the repository and install dependencies:

git clone https://github.com/your-username/embytok.git
cd embytok
npm install

Add Android platform (first time only)

Add the Android platform to your project:

npm run cap:add
# or use Capacitor CLI directly
npx cap add android

This creates the android/ directory with a native Android project.

Build the web app

Build the optimized web assets:

npm run build

This compiles TypeScript and creates production bundles in dist/.

Sync web assets to Android

Copy the built web files to the Android project:

npm run cap:sync
# or use Capacitor CLI directly
npx cap sync android

This command:

Copies dist/ to android/app/src/main/assets/public/
Updates native dependencies
Syncs Capacitor configuration

You can combine steps 3 and 4 with the convenience command:

npm run build:android

This runs tsc && vite build && cap sync android in one command.

Capacitor Configuration

The app is configured in capacitor.config.ts:

capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.embytok.app',
  appName: 'EmbyTok',
  webDir: 'dist',
  server: {
    androidScheme: 'https'
  },
  plugins: {
    CapacitorHttp: {
      enabled: true,
    },
  },
};

export default config;

Key settings:

appId: com.embytok.app - Unique Android package identifier
appName: EmbyTok - Display name on device
webDir: dist - Built web assets directory
androidScheme: https - Uses HTTPS scheme for web content
CapacitorHttp: Enabled for native HTTP requests

If you fork the project, change appId to a unique identifier (e.g., com.yourname.embytok) to avoid conflicts.

Building APK with Android Studio

Open project in Android Studio

Launch Android Studio and open the Android project:

npx cap open android

Or manually open the android/ directory in Android Studio.

Configure build variant

In Android Studio:

Select Build > Select Build Variant
Choose release for production builds or debug for testing

Generate APK

Build the APK:

Select Build > Build Bundle(s) / APK(s) > Build APK(s)
Wait for the build to complete
Click locate in the notification to find the APK

The APK will be in:

android/app/build/outputs/apk/release/app-release.apk

Sign the APK (release builds)

For production release:

Select Build > Generate Signed Bundle / APK
Choose APK and click Next
Create or select a keystore
Enter keystore password and key alias
Select release build variant
Choose signature versions (V1 and V2)
Click Finish

Building from Command Line

You can also build APK without Android Studio:

Debug APK

cd android
./gradlew assembleDebug

Output: android/app/build/outputs/apk/debug/app-debug.apk

Release APK (unsigned)

cd android
./gradlew assembleRelease

Output: android/app/build/outputs/apk/release/app-release-unsigned.apk

Sign APK Manually

Sign the release APK using apksigner:

# Align the APK
zipalign -v -p 4 app-release-unsigned.apk app-release-aligned.apk

# Sign with your keystore
apksigner sign --ks my-release-key.jks \
  --out app-release-signed.apk \
  app-release-aligned.apk

# Verify signature
apksigner verify app-release-signed.apk

Installing on Device

Via USB (Development)

Enable developer options

On your Android device:

Go to Settings > About phone
Tap Build number 7 times
Enable Developer options
Enable USB debugging

Connect device

Connect your Android device via USB and authorize the computer.Verify connection:

adb devices

Run from Android Studio

In Android Studio:

Select your device from the device dropdown
Click the Run button (green play icon)

Or use command line:

cd android
./gradlew installDebug

Via APK File

Transfer the APK to your device
Open the APK file on your device
Allow installation from unknown sources if prompted
Tap Install

Installing APKs from unknown sources requires enabling “Install unknown apps” permission for your file manager.

Live Reload Development

For faster development, use live reload:

Start dev server with LAN access

npm run dev:lan

Note the local network IP (e.g., http://192.168.1.100:5173)

Update capacitor.config.ts

Add server configuration:

server: {
  url: 'http://192.168.1.100:5173',
  cleartext: true
}

Sync and run

npx cap sync android
npx cap run android

The app will load content from your dev server with hot reload.

Remember to remove the server.url configuration before building production APK.

Customization

App Name and Icon

Modify Android app metadata:

App name: Edit android/app/src/main/res/values/strings.xml
Package name: Change appId in capacitor.config.ts, then sync
App icon: Replace icons in android/app/src/main/res/mipmap-*/

Permissions

EmbyTok requires these permissions (automatically added by Capacitor):

android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Add additional permissions if needed for future features.

Supported Android Versions

Minimum SDK: API 22 (Android 5.1 Lollipop)
Target SDK: API 34 (Android 14)
Compile SDK: API 34

Modify in android/app/build.gradle if needed.

Troubleshooting

Build fails with 'capacitor' not found

Solution: Ensure Capacitor is installed:

npm install @capacitor/core @capacitor/cli @capacitor/android

Gradle build fails

Common fixes:

Update Gradle wrapper:

cd android
./gradlew wrapper --gradle-version=8.0

Clean build:

./gradlew clean
./gradlew assembleDebug

Invalidate caches in Android Studio: File > Invalidate Caches / Restart

App shows blank screen

Solution: Verify web assets were synced:

npm run build
npx cap sync android

Check that android/app/src/main/assets/public/ contains your built files.

adb devices shows no devices

Solution:

Enable USB debugging on device
Try different USB cable
Restart adb server:
```
adb kill-server
adb start-server
```

Network requests fail in app

Solution: Check network security configuration. For HTTP (non-HTTPS) servers, add to android/app/src/main/res/xml/network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">your-server-ip</domain>
    </domain-config>
</network-security-config>

Publishing to Google Play

To publish EmbyTok to Google Play Store:

Create signed release APK or AAB (Android App Bundle recommended)
Create Google Play Developer account ($25 one-time fee)
Create app listing with screenshots and descriptions
Upload APK/AAB for internal testing, then production
Submit for review

See Android Developer documentation for detailed publishing guide.

Next Steps

iOS App

Build native iOS app with UIKit

Configuration

Configure Emby/Plex servers

Capacitor Plugins

Add native device features

Mobile Guide

Using EmbyTok on mobile devices

Get Started

Installation

Core Features

Configuration

Guides

Android App Installation

Prerequisites

Node.js

Android Studio

Java JDK

Android SDK

Installation Steps

Capacitor Configuration

Building APK with Android Studio

Building from Command Line

Debug APK

Release APK (unsigned)

Sign APK Manually

Installing on Device

Via USB (Development)

Via APK File

Live Reload Development

Customization

App Name and Icon

Permissions

Supported Android Versions

Troubleshooting

Publishing to Google Play

Next Steps

iOS App

Configuration

Capacitor Plugins

Mobile Guide

Build docs developers (and LLMs) love

Get Started

Installation

Core Features

Configuration

Guides

​Prerequisites

Node.js

Android Studio

Java JDK

Android SDK

​Installation Steps

​Capacitor Configuration

​Building APK with Android Studio

​Building from Command Line

​Debug APK

​Release APK (unsigned)

​Sign APK Manually

​Installing on Device

​Via USB (Development)

​Via APK File

​Live Reload Development

​Customization

​App Name and Icon

​Permissions

​Supported Android Versions

​Troubleshooting

​Publishing to Google Play

​Next Steps

iOS App

Configuration

Capacitor Plugins

Mobile Guide

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Capacitor Configuration

Building APK with Android Studio

Building from Command Line

Debug APK

Release APK (unsigned)

Sign APK Manually

Installing on Device

Via USB (Development)

Via APK File

Live Reload Development

Customization

App Name and Icon

Permissions

Supported Android Versions

Troubleshooting

Publishing to Google Play

Next Steps