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!** 🎉