daily-notification-plugin/test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md

DailyNotification Plugin Detection Guide

Author: Matthew Raymer
Date: October 17, 2025
Version: 1.0.0

Overview

This guide documents the plugin detection system for the DailyNotification Capacitor plugin, including troubleshooting steps and build process requirements.

Table of Contents

1. Plugin Detection Architecture
2. Build Process Requirements
3. Troubleshooting Guide
4. Development Workflow
5. Common Issues and Solutions

Plugin Detection Architecture

Native Side (Android)

The DailyNotification plugin is registered on the native Android side through:

1. Automatic Discovery: Using Capacitor's annotation processor
2. Manual Registration: Fallback in MainActivity.onCreate()
3. Plugin Class: com.timesafari.dailynotification.DailyNotificationPlugin

JavaScript Side (WebView)

The JavaScript layer detects plugins through:

1. capacitor.plugins.json: Bridge file that lists available plugins
2. Capacitor.Plugins Object: Runtime plugin registry
3. Plugin Detection Logic: Checks both sources for availability

Key Files

android/
├── app/src/main/assets/capacitor.plugins.json  # Plugin registry
├── app/src/main/java/.../MainActivity.java     # Plugin registration
└── dailynotification/build.gradle              # Annotation processor

src/
├── views/HomeView.vue                          # Plugin detection UI
└── components/cards/ActionCard.vue             # Interactive components

Build Process Requirements

Prerequisites

1. Annotation Processor: Must be configured in both app and plugin modules
2. Post-Sync Script: Required to maintain capacitor.plugins.json
3. Proper Dependencies: Capacitor Android and plugin modules

Required Build Steps

# 1. Build web assets
npm run build

# 2. Sync with native projects
npx cap sync android

# 3. Fix plugin registry (CRITICAL)
node scripts/fix-capacitor-plugins.js

# 4. Build and deploy Android app
cd android
./gradlew :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity

Why the Fix Script is Required

Problem: npx cap sync android overwrites capacitor.plugins.json and doesn't include custom plugins.

Solution: Post-sync script automatically restores the DailyNotification plugin entry.

File: scripts/fix-capacitor-plugins.js

const PLUGIN_ENTRY = {
  name: "DailyNotification",
  classpath: "com.timesafari.dailynotification.DailyNotificationPlugin"
};

Troubleshooting Guide

Issue: "Plugin: Not Available" in System Status

Symptoms:

• System Status card shows red "Not Available" indicator
• Plugin Diagnostics shows "Plugin Available: No"

Diagnosis Steps:

1. Check capacitor.plugins.json content
2. Verify native plugin registration logs
3. Test JavaScript detection logic

Solutions:

# Check plugin registry
cat android/app/src/main/assets/capacitor.plugins.json

# Should contain:
[
  {
    "name": "DailyNotification",
    "classpath": "com.timesafari.dailynotification.DailyNotificationPlugin"
  }
]

# If empty or missing, run fix script
node scripts/fix-capacitor-plugins.js

Issue: Click Events Not Working

Symptoms:

• ActionCard buttons don't respond to clicks
• No console logs from click handlers

Common Causes:

1. Wrong View Component: Router pointing to simplified view
2. Vue 3 Compatibility: Using deprecated @click.native
3. Component Registration: Missing component imports

Solutions:

<!-- ❌ Wrong: Vue 3 doesn't support .native -->
<ActionCard @click.native="handler" />

<!-- ✅ Correct: Standard event binding -->
<ActionCard @click="handler" />

Issue: Empty capacitor.plugins.json After Build

Symptoms:

• File contains only []
• Plugin detection fails
• "Simplified dialog" appears

Root Cause: npx cap sync overwrites the file

Solution: Always run fix script after sync

npx cap sync android && node scripts/fix-capacitor-plugins.js

Development Workflow

Daily Development Cycle

1. Make Changes: Edit Vue components, native code, or plugin logic
2. Build Web: npm run build
3. Sync Native: npx cap sync android
4. Fix Plugins: node scripts/fix-capacitor-plugins.js
5. Build Android: cd android && ./gradlew :app:assembleDebug
6. Deploy: adb install -r app/build/outputs/apk/debug/app-debug.apk
7. Test: Launch app and verify plugin detection

Automated Build Script

Create scripts/build-and-deploy.sh:

#!/bin/bash
set -e

echo "🔨 Building web assets..."
npm run build

echo "🔄 Syncing with native projects..."
npx cap sync android

echo "🔧 Fixing plugin registry..."
node scripts/fix-capacitor-plugins.js

echo "🏗️ Building Android app..."
cd android
./gradlew :app:assembleDebug

echo "📱 Installing and launching..."
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity

echo "✅ Build and deploy complete!"

Verification Checklist

After each build, verify:

• capacitor.plugins.json contains DailyNotification entry
• System Status shows "Plugin: Available" (green)
• Plugin Diagnostics shows all 4 plugins
• Click events work on ActionCard components
• No "simplified dialog" appears
• Console logs show plugin detection success

Common Issues and Solutions

Issue: Annotation Processor Not Working

Symptoms: Plugin not auto-discovered, manual registration required

Solution: Ensure annotation processor is configured in both modules

// app/build.gradle
dependencies {
    annotationProcessor project(':capacitor-android')
}

// dailynotification/build.gradle  
dependencies {
    annotationProcessor project(':capacitor-android')
}

Issue: Plugin Loads But Methods Fail

Symptoms: Plugin detected but checkStatus() throws errors

Diagnosis: Check native plugin implementation and permissions

Solution: Verify plugin class methods and Android permissions

Issue: Inconsistent Status Between Cards

Symptoms: System Status shows "Not Available" but Plugin Diagnostics shows "Available"

Root Cause: Different detection logic between functions

Solution: Use consistent detection method (see checkSystemStatus in HomeView.vue)

Issue: Build Failures After Changes

Symptoms: Gradle build errors, TypeScript compilation failures

Common Causes:

1. Missing imports after refactoring
2. TypeScript errors in Vue components
3. Gradle dependency conflicts

Solution: Check build logs and fix compilation errors

Debugging Tools

Console Logging

The app includes comprehensive logging for plugin detection:

// Plugin detection logs
console.log('🔍 Plugin detection debug:')
console.log('  - window.DailyNotification:', (window as any).DailyNotification)
console.log('  - Capacitor.Plugins:', (window as any).Capacitor?.Plugins)
console.log('  - Available plugins:', Object.keys((window as any).Capacitor?.Plugins || {}))

ADB Logging

Monitor native Android logs:

adb logcat | grep -i "dailynotification\|capacitor\|plugin\|error"

Plugin Diagnostics

Use the built-in Plugin Diagnostics feature to get comprehensive system information:

1. Click "Plugin Diagnostics" button
2. Review detailed plugin report
3. Check all available plugins list
4. Verify plugin status and capabilities

Best Practices

Development

1. Always run fix script after npx cap sync
2. Test plugin detection after each build
3. Use consistent detection logic across components
4. Monitor console logs for debugging information
5. Verify both native and JavaScript sides work correctly

Maintenance

1. Keep fix script updated if plugin classpath changes
2. Document any new plugin dependencies
3. Update this guide when architecture changes
4. Test on multiple devices and Android versions
5. Monitor Capacitor updates for breaking changes

Related Files

• scripts/fix-capacitor-plugins.js - Post-sync plugin registry fix
• src/views/HomeView.vue - Main plugin detection UI
• src/components/cards/ActionCard.vue - Interactive components
• android/app/src/main/assets/capacitor.plugins.json - Plugin registry
• android/app/src/main/java/.../MainActivity.java - Native registration

Support

For issues not covered in this guide:

1. Check Capacitor documentation
2. Review Android plugin development guides
3. Examine console logs and ADB output
4. Test with minimal reproduction case
5. Consult development team

---

Last Updated: October 17, 2025
Next Review: After major Capacitor updates or architecture changes