docs: add comprehensive standalone emulator guide

- Document complete process for running Android app without Android Studio - Include step-by-step commands and troubleshooting - Cover emulator startup, app building, installation, and launching - Add performance optimization tips and alternative methods - Provide copy-paste ready command sequences - Include expected results and success indicators This enables development and testing without Android Studio IDE.
1 week ago · 4304addde1
1 changed files with 365 additions and 0 deletions
--- a/docs/standalone-emulator-guide.md
+++ b/docs/standalone-emulator-guide.md
@ -0,0 +1,365 @@
+# Running Android App in Standalone Emulator (Without Android Studio)
+
+**Author**: Matthew Raymer  
+**Last Updated**: 2025-10-12 06:50:00 UTC  
+**Version**: 1.0.0
+
+## Overview
+
+This guide demonstrates how to run the DailyNotification plugin test app in a standalone Android emulator without using Android Studio. This method is useful for development, CI/CD pipelines, and resource-constrained environments.
+
+## Prerequisites
+
+### Required Software
+- **Android SDK** with command line tools
+- **Android Emulator** (`emulator` command)
+- **ADB** (Android Debug Bridge)
+- **Gradle** (via Gradle Wrapper)
+- **Node.js** and **npm** (for TypeScript compilation)
+
+### System Requirements
+- **RAM**: 4GB minimum, 8GB recommended
+- **Storage**: 2GB free space for emulator
+- **OS**: Linux, macOS, or Windows with WSL
+
+## Step-by-Step Process
+
+### 1. Check Available Emulators
+
+```bash
+# List available Android Virtual Devices (AVDs)
+emulator -list-avds
+
+# Example output:
+# Pixel8_API34
+```
+
+### 2. Start the Emulator
+
+```bash
+# Start emulator in background (recommended)
+emulator -avd Pixel8_API34 -no-snapshot-load &
+
+# Alternative: Start in foreground
+emulator -avd Pixel8_API34
+```
+
+**Flags Explained:**
+- `-avd Pixel8_API34` - Specifies the AVD to use
+- `-no-snapshot-load` - Forces fresh boot (recommended for testing)
+- `&` - Runs in background (optional)
+
+### 3. Wait for Emulator to Boot
+
+```bash
+# Wait for emulator to be ready
+adb wait-for-device
+
+# Verify emulator is running
+adb devices
+
+# Example output:
+# List of devices attached
+# emulator-5554   device
+```
+
+### 4. Build the Plugin and Test App
+
+```bash
+# Navigate to project directory
+cd /path/to/daily-notification-plugin
+
+# Build TypeScript and native code
+./scripts/build-native.sh --platform android
+```
+
+**What this does:**
+- Compiles TypeScript to JavaScript
+- Builds Android native code
+- Creates plugin AAR files
+- Builds test app APK
+
+### 5. Build Debug APK (Required for Installation)
+
+```bash
+# Navigate to Android directory
+cd android
+
+# Build debug version (includes debug signing)
+./gradlew :app:assembleDebug
+```
+
+**Why Debug APK:**
+- **Debug signing** - Automatically signed for installation
+- **No certificates needed** - Uses default debug keystore
+- **Faster builds** - No optimization, faster compilation
+
+### 6. Install APK on Emulator
+
+```bash
+# Install the debug APK
+adb install app/build/outputs/apk/debug/app-debug.apk
+
+# Alternative: Install with replacement
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
+
+**Installation Options:**
+- `adb install` - Install new app
+- `adb install -r` - Replace existing app
+- `adb install -t` - Allow test APKs
+
+### 7. Launch the App
+
+```bash
+# Launch the app
+adb shell am start -n com.timesafari.dailynotification/.MainActivity
+
+# Alternative: Launch with specific intent
+adb shell am start -a android.intent.action.MAIN -n com.timesafari.dailynotification/.MainActivity
+```
+
+### 8. Monitor App Logs
+
+```bash
+# View all logs
+adb logcat
+
+# Filter for specific tags
+adb logcat -s "Capacitor" "DailyNotification" "Console"
+
+# View logs for specific process
+adb logcat --pid=<PID>
+
+# Clear logs and view new ones
+adb logcat -c && adb logcat
+```
+
+## Complete Command Sequence
+
+### Quick Start (Copy-Paste Ready)
+
+```bash
+# 1. Start emulator
+emulator -avd Pixel8_API34 -no-snapshot-load &
+
+# 2. Wait for emulator
+adb wait-for-device
+
+# 3. Build everything
+./scripts/build-native.sh --platform android
+
+# 4. Build debug APK
+cd android && ./gradlew :app:assembleDebug
+
+# 5. Install APK
+adb install app/build/outputs/apk/debug/app-debug.apk
+
+# 6. Launch app
+adb shell am start -n com.timesafari.dailynotification/.MainActivity
+
+# 7. Monitor logs
+adb logcat -s "Capacitor" "DailyNotification" "Console"
+```
+
+## Alternative Methods
+
+### Method 1: Using Capacitor CLI
+
+```bash
+# Build and run in one command
+npx cap run android
+
+# This will:
+# - Build the plugin
+# - Sync web assets
+# - Build and install APK
+# - Launch the app
+```
+
+### Method 2: Direct Gradle Commands
+
+```bash
+# Build and install directly
+cd android
+./gradlew :app:assembleDebug
+adb install app/build/outputs/apk/debug/app-debug.apk
+adb shell am start -n com.timesafari.dailynotification/.MainActivity
+```
+
+### Method 3: Using Monkey (Alternative Launch)
+
+```bash
+# Install and launch with Monkey
+adb install app/build/outputs/apk/debug/app-debug.apk
+adb shell monkey -p com.timesafari.dailynotification -c android.intent.category.LAUNCHER 1
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Emulator Won't Start
+```bash
+# Check available AVDs
+emulator -list-avds
+
+# Check emulator process
+ps aux | grep emulator
+
+# Kill existing emulator
+pkill -f emulator
+
+# Start with verbose logging
+emulator -avd Pixel8_API34 -verbose
+```
+
+#### ADB Connection Issues
+```bash
+# Check ADB connection
+adb devices
+
+# Restart ADB server
+adb kill-server
+adb start-server
+
+# Check ADB version
+adb version
+```
+
+#### APK Installation Fails
+```bash
+# Check if app is already installed
+adb shell pm list packages | grep timesafari
+
+# Uninstall existing app
+adb uninstall com.timesafari.dailynotification
+
+# Install with force
+adb install -r -t app/build/outputs/apk/debug/app-debug.apk
+```
+
+#### Build Failures
+```bash
+# Clean build
+cd android && ./gradlew clean
+
+# Rebuild
+./gradlew :app:assembleDebug
+
+# Check Gradle daemon
+./gradlew --status
+```
+
+### Performance Optimization
+
+#### Emulator Performance
+```bash
+# Start with hardware acceleration
+emulator -avd Pixel8_API34 -accel on
+
+# Start with specific RAM allocation
+emulator -avd Pixel8_API34 -memory 2048
+
+# Start with GPU acceleration
+emulator -avd Pixel8_API34 -gpu host
+```
+
+#### Build Performance
+```bash
+# Enable Gradle daemon
+echo "org.gradle.daemon=true" >> ~/.gradle/gradle.properties
+
+# Increase memory
+echo "org.gradle.jvmargs=-Xmx4g" >> ~/.gradle/gradle.properties
+
+# Enable parallel builds
+echo "org.gradle.parallel=true" >> ~/.gradle/gradle.properties
+```
+
+## Expected Results
+
+### Successful App Launch
+When the app launches successfully, you should see:
+
+```bash
+# ADB output
+Starting: Intent { cmp=com.timesafari.dailynotification/.MainActivity }
+
+# Logcat output
+D Capacitor: Starting BridgeActivity
+D Capacitor: Registering plugin instance: CapacitorCookies
+D Capacitor: Registering plugin instance: WebView
+D Capacitor: Registering plugin instance: CapacitorHttp
+D Capacitor: Loading app at https://localhost
+D Capacitor: App started
+D Capacitor: App resumed
+I Capacitor/Console: Script loading...
+I Capacitor/Console: Creating mock DailyNotification plugin...
+I Capacitor/Console: Functions attached to window: [object Object]
+```
+
+### App Interface
+The app should display:
+- **Title**: "🔔 DailyNotification Plugin Test"
+- **Three buttons**: "Test Plugin", "Configure Plugin", "Check Status"
+- **Status area**: Shows test results and plugin status
+
+## Benefits of Standalone Approach
+
+### Advantages
+- ✅ **No Android Studio** - Pure command line workflow
+- ✅ **Faster startup** - No IDE overhead
+- ✅ **CI/CD friendly** - Works in automated environments
+- ✅ **Resource efficient** - Lower memory usage
+- ✅ **Scriptable** - Can be automated
+- ✅ **Remote development** - Works over SSH
+
+### Use Cases
+- **Development** - Quick testing and iteration
+- **CI/CD pipelines** - Automated testing
+- **Remote development** - SSH-based development
+- **Resource-constrained environments** - Low-spec machines
+- **Team environments** - Shared development servers
+
+## Integration with Development Workflow
+
+### Daily Development
+```bash
+# Quick test cycle
+./scripts/build-native.sh --platform android
+cd android && ./gradlew :app:assembleDebug
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+adb shell am start -n com.timesafari.dailynotification/.MainActivity
+```
+
+### Automated Testing
+```bash
+# CI/CD pipeline
+emulator -avd Pixel8_API34 -no-snapshot-load &
+adb wait-for-device
+./scripts/build-native.sh --platform android
+cd android && ./gradlew :app:assembleDebug
+adb install app/build/outputs/apk/debug/app-debug.apk
+adb shell am start -n com.timesafari.dailynotification/.MainActivity
+# Run tests...
+```
+
+## Next Steps
+
+### Testing the App
+1. **Click "Test Plugin"** - Tests the mock plugin implementation
+2. **Click "Configure Plugin"** - Tests plugin configuration
+3. **Click "Check Status"** - Tests plugin status retrieval
+4. **Monitor logs** - Check for any errors or issues
+
+### Development Workflow
+1. **Make changes** - Edit plugin code or test app
+2. **Rebuild** - Run the build commands
+3. **Reinstall** - Install updated APK
+4. **Test** - Launch and test functionality
+5. **Iterate** - Repeat as needed
+
+---
+
+**This method provides a complete standalone Android development environment without requiring Android Studio!** 🎉