trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity
Files
c38f23564734b9448bf58852e87983bd779608d5
daily-notification-plugin/docs/testing/PHYSICAL_DEVICE_GUIDE.md
Jose Olarte III 602eafc892 docs(testing): add PHYSICAL_DEVICE_GUIDE for Android hardware testing 
Covers USB debugging setup, battery optimization settings for major OEMs
(Samsung, Xiaomi, OnePlus, Huawei, Oppo), log monitoring, and
troubleshooting. Complements EMULATOR_GUIDE for real-device validation.
2026-02-12 17:19:45 +08:00

13 KiB
Raw Blame History

Running Android App on a Physical Device

Author: Matthew Raymer
Last Updated: 2026-02-12
Version: 1.0.0

Overview

This guide demonstrates how to run the DailyNotification plugin test app on a physical Android device. Physical device testing is essential for validating:

  • Real notification behavior — Emulators may not accurately simulate notification delivery timing
  • Battery optimization effects — OEM-specific power management that affects background tasks
  • Actual alarm scheduling — AlarmManager behavior varies between emulators and real hardware
  • Device reboot persistence — Boot receivers and alarm recovery

Prerequisites

Required Hardware

  • Android phone or tablet running Android 8.0 (API 26) or higher
  • USB cable (data-capable, not charge-only)
  • Development computer with USB port

Required Software

  • Android SDK with platform-tools (provides adb)
  • Gradle (via Gradle Wrapper)
  • Node.js and npm (for TypeScript compilation)

How to Check

Requirement How to check
Node.js node --version (v14+ recommended; test app may require 20+)
npm npm --version
Java java -version (Java 11+)
ANDROID_HOME echo $ANDROID_HOME (must be set to your Android SDK root)
adb adb version (must be on PATH)

Project script: From the repo root:

node scripts/check-environment.js

Step 1: Enable Developer Options on Your Phone

Developer Options are hidden by default. To enable them:

Android 8.0 - 14 (Most Devices)

  1. Open Settings
  2. Scroll down to About phone (or About device)
  3. Find Build number
  4. Tap Build number 7 times rapidly
  5. You'll see "You are now a developer!" toast message

Samsung Devices

  1. Settings → About phone → Software information
  2. Tap Build number 7 times

Xiaomi/MIUI Devices

  1. Settings → About phone
  2. Tap MIUI version 7 times

OnePlus Devices

  1. Settings → About phone
  2. Tap Build number 7 times

Step 2: Enable USB Debugging

After enabling Developer Options:

  1. Go to Settings → System → Developer options
    • On some phones: Settings → Developer options directly
  2. Scroll to find USB debugging
  3. Toggle USB debugging ON
  4. Confirm when prompted

Optional but Recommended Settings

While in Developer Options, also enable:

  • Stay awake — Screen stays on while charging (useful during development)
  • Allow mock locations — If testing location features

Step 3: Connect and Authorize Your Device

Physical Connection

  1. Connect your phone to your computer via USB
  2. On your phone, change USB mode:
    • Pull down notification shade
    • Tap the USB notification ("Charging this device via USB")
    • Select File transfer / Android Auto or PTP (not "Charge only")

Authorize Computer

  1. On your phone, you'll see a dialog: "Allow USB debugging?"
  2. Check "Always allow from this computer" (recommended)
  3. Tap Allow

Verify Connection

# List connected devices
adb devices

# Expected output:
# List of devices attached
# ABC123DEF456    device

Troubleshooting connection states:

State Meaning Solution
device Connected and authorized Ready to use
unauthorized USB debugging not authorized Check phone for auth dialog
offline Connection issues Unplug, replug, restart adb
(empty) Device not detected Check USB cable, USB mode

Step 4: Build and Install the App

Option A: Using Build Script (Recommended)

From the test-apps/daily-notification-test directory:

# Build and run on connected device
./scripts/build.sh --run-android

Option B: Manual Build

# 1. Navigate to test app directory
cd test-apps/daily-notification-test

# 2. Build web assets
npm run build

# 3. Sync with Capacitor
npm run cap:sync:android

# 4. Build APK
cd android
./gradlew :app:assembleDebug

# 5. Install on device
adb install -r app/build/outputs/apk/debug/app-debug.apk

# 6. Launch app
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity

Option C: Using Capacitor CLI

# Build, install, and launch in one command
npx cap run android --target <device-id>

# Get device ID from:
adb devices

Step 5: Configure Battery Optimization (Critical!)

This is the most important step for notification testing. Android OEMs aggressively kill background apps to save battery. Without proper configuration, your alarms and notifications may not fire.

Disable Battery Optimization for Test App

  1. Settings → Apps → DailyNotification Test (or your app name)
  2. Battery → Unrestricted or Don't optimize

Manufacturer-Specific Settings

Samsung (One UI)

  1. Settings → Battery → Background usage limits
  2. Remove app from "Sleeping apps" and "Deep sleeping apps"
  3. Add app to "Never sleeping apps"

Xiaomi (MIUI)

  1. Settings → Apps → Manage apps → Select app
  2. Enable Autostart
  3. Battery saver → No restrictions
  4. Security app → Permissions → Autostart → Enable for app

OnePlus (OxygenOS)

  1. Settings → Battery → Battery optimization
  2. Select app → Don't optimize
  3. Settings → Apps → Select app → Advanced → Optimize battery usage → Off

Huawei/Honor (EMUI)

  1. Settings → Battery → App launch
  2. Disable automatic management for the app
  3. Enable all three toggles: Auto-launch, Secondary launch, Run in background

Oppo/Realme (ColorOS)

  1. Settings → Battery → More battery settings
  2. Optimize battery use → Select app → Don't optimize
  3. Enable Allow auto-start and Allow background activity

Verify Battery Settings

# Check if app is whitelisted from battery optimization
adb shell dumpsys deviceidle whitelist

# Should include your package name

Step 6: Monitor Logs

Real-time Log Streaming

# All logs from the app
adb logcat | grep -E "DailyNotification|Capacitor|Console"

# Specific tags only
adb logcat -s "DailyNotification" "Capacitor" "Console"

# Clear logs and start fresh
adb logcat -c && adb logcat -s "DailyNotification"

Filter by Log Level

# Errors only
adb logcat *:E | grep DailyNotification

# Warnings and above
adb logcat *:W | grep DailyNotification

# Verbose (all levels)
adb logcat *:V | grep DailyNotification

Save Logs to File

# Stream logs to file
adb logcat -s "DailyNotification" > device_logs.txt

# Press Ctrl+C to stop

Check Alarm Scheduling

# View scheduled alarms (requires root or debuggable build)
adb shell dumpsys alarm | grep -A 5 "com.timesafari"

# View alarm statistics
adb shell dumpsys alarm | grep -i "daily"

Step 7: Testing Notification Features

Test Immediate Notification

  1. Open the app
  2. Navigate to notification testing section
  3. Trigger an immediate notification
  4. Verify it appears in the notification tray

Test Scheduled Notification

  1. Schedule a notification for 1-2 minutes in the future
  2. Lock the phone or put app in background
  3. Wait for notification to fire
  4. Check logs if notification doesn't appear

Test Alarm Persistence

  1. Schedule a notification
  2. Reboot the device: 
    adb reboot
  3. After reboot, check if alarm was restored: 
    adb shell dumpsys alarm | grep -A 5 "com.timesafari"

Test Force Stop Recovery

  1. Schedule a notification
  2. Force stop the app: 
    adb shell am force-stop com.timesafari.dailynotification.test
  3. Check if alarms are recovered (implementation dependent)

Complete Command Sequence

Quick Start (Copy-Paste Ready)

# 1. Verify device connection
adb devices

# 2. Navigate to test app
cd test-apps/daily-notification-test

# 3. Build everything
npm run build
npm run cap:sync:android

# 4. Build and install APK
cd android
./gradlew :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

# 5. Launch app
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity

# 6. Monitor logs (in separate terminal)
adb logcat -s "DailyNotification" "Capacitor" "Console"

Troubleshooting

Device Not Detected

# Restart ADB server
adb kill-server
adb start-server
adb devices

# Check USB connection
# - Try different USB cable (use data cable, not charge-only)
# - Try different USB port
# - Check USB mode on phone (should be File transfer, not Charge only)

"Unauthorized" Device

# Revoke USB debugging authorizations on phone:
# Settings → Developer options → Revoke USB debugging authorizations

# Then reconnect and re-authorize
adb kill-server
adb start-server
# Accept authorization dialog on phone

APK Installation Fails

# Error: INSTALL_FAILED_UPDATE_INCOMPATIBLE
# Solution: Uninstall existing app first
adb uninstall com.timesafari.dailynotification.test
adb install app/build/outputs/apk/debug/app-debug.apk

# Error: INSTALL_FAILED_USER_RESTRICTED
# Solution: Enable "Install via USB" in Developer options

Notifications Not Appearing

  1. Check notification permissions:

    adb shell dumpsys notification | grep -A 10 "com.timesafari"

  2. Check battery optimization:

    • Ensure app is set to "Unrestricted" or "Don't optimize"
    • Check manufacturer-specific settings (see Step 5)

  3. Check Do Not Disturb:

    • Ensure DND is off, or app is allowed through DND

  4. Check notification channel:

    adb shell dumpsys notification | grep -B 5 -A 10 "channel"

Alarms Not Firing

  1. Check if alarms are scheduled:

    adb shell dumpsys alarm | grep -A 10 "com.timesafari"

  2. Check Doze mode:

    # Check current Doze state
adb shell dumpsys deviceidle

# Force device out of Doze for testing
adb shell dumpsys deviceidle unforce

  3. Check exact alarm permission (Android 12+):

    adb shell appops get com.timesafari.dailynotification.test SCHEDULE_EXACT_ALARM

Build Failures

# Clean build
cd android
./gradlew clean
./gradlew :app:assembleDebug

# If still failing, clean Gradle cache
rm -rf ~/.gradle/caches
./gradlew :app:assembleDebug

Benefits of Physical Device Testing

Advantages Over Emulator

  • ✅ Accurate notification timing — Real hardware scheduler behavior
  • ✅ Real battery optimization — Test against actual OEM restrictions
  • ✅ True Doze mode — Emulators simulate but don't fully replicate
  • ✅ Boot receiver testing — Actual device reboot behavior
  • ✅ Performance metrics — Real CPU/memory usage
  • ✅ User experience — How notifications actually feel

When to Use Physical Device

  • Final validation — Before release
  • Notification timing tests — Alarm accuracy verification
  • Battery impact testing — Real power consumption
  • Reboot persistence tests — Boot receiver validation
  • OEM-specific testing — Samsung, Xiaomi, etc. quirks

When Emulator is Sufficient

  • Basic functionality — Core feature development
  • UI testing — Layout and interaction testing
  • Quick iteration — Fast build-test cycles
  • CI/CD pipelines — Automated testing

Multiple Device Management

List All Connected Devices

adb devices -l

# Example output:
# ABC123DEF456    device usb:1-1 product:walleye model:Pixel_2 device:walleye
# XYZ789GHI012    device usb:1-2 product:star2lte model:SM_G965F device:star2lte

Target Specific Device

# Install on specific device
adb -s ABC123DEF456 install -r app/build/outputs/apk/debug/app-debug.apk

# View logs from specific device
adb -s ABC123DEF456 logcat -s "DailyNotification"

# Launch app on specific device
adb -s ABC123DEF456 shell am start -n com.timesafari.dailynotification.test/.MainActivity

Wireless ADB (Optional)

For cable-free development after initial setup:

# 1. Connect device via USB first
# 2. Enable TCP/IP mode on port 5555
adb tcpip 5555

# 3. Find device IP (Settings → About phone → Status → IP address)
# Or:
adb shell ip addr show wlan0 | grep inet

# 4. Disconnect USB and connect wirelessly
adb connect 192.168.1.100:5555

# 5. Verify connection
adb devices
# Should show: 192.168.1.100:5555    device

Note: Wireless ADB is slower than USB and may disconnect. Use USB for large APK transfers.

Next Steps

Testing Workflow

  1. Build → Make changes, rebuild APK
  2. Install → Push to device with adb install -r
  3. Test → Exercise notification features
  4. Monitor → Watch logs for issues
  5. Iterate → Fix and repeat

Recommended Test Sequence

  1. ✅ Immediate notification display
  2. ✅ Scheduled notification (1-2 min delay)
  3. ✅ App backgrounded notification
  4. ✅ Screen off notification
  5. ✅ Device reboot alarm persistence
  6. ✅ Force stop recovery (if implemented)
  7. ✅ Battery optimization scenarios

Physical device testing is essential for production-quality notification behavior. While emulators are great for development, only real hardware reveals the true behavior of Android's notification and alarm systems. 📱

Reference in New Issue View Git Blame Copy Permalink