daily-notification-plugin/docs/integration/QUICK_START.md

Daily Notification Plugin - Quick Integration Guide

Author: Matthew Raymer
Version: 2.2.0
Last Updated: 2025-11-06

Overview

This guide provides a quick, step-by-step process for integrating the Daily Notification Plugin into any Capacitor application. For detailed documentation, see README.md and API.md.

For AI Agents: See AI_INTEGRATION_GUIDE.md for explicit, machine-readable integration instructions with verification steps and error handling.

Prerequisites

• Capacitor 6.0+ project
• Android Studio (for Android development)
• Xcode 14+ (for iOS development)
• Node.js 18+

Step 1: Install the Plugin

npm install @timesafari/daily-notification-plugin

Or install from Git:

npm install git+https://github.com/timesafari/daily-notification-plugin.git

Step 2: Sync Capacitor

npx cap sync android
npx cap sync ios

Step 3: Android Configuration

3.1 Update AndroidManifest.xml

⚠️ CRITICAL: You must add the NotifyReceiver registration to your app's AndroidManifest.xml. Without it, alarms will fire but notifications won't be displayed.

Add to android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- Required permissions -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
    <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <application>
        <!-- ... your existing application components ... -->

        <!-- Daily Notification Plugin Receivers -->
        <!-- REQUIRED: NotifyReceiver for AlarmManager-based notifications -->
        <receiver
            android:name="com.timesafari.dailynotification.NotifyReceiver"
            android:enabled="true"
            android:exported="false">
        </receiver>

        <!-- BootReceiver for reboot recovery (optional but recommended) -->
        <receiver
            android:name="com.timesafari.dailynotification.BootReceiver"
            android:enabled="true"
            android:exported="false">
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED" />
            </intent-filter>
        </receiver>
    </application>
</manifest>

3.2 Update build.gradle (if needed)

The plugin should work with standard Capacitor setup. If you encounter dependency issues, ensure these are in android/app/build.gradle:

dependencies {
    // ... your existing dependencies ...
    
    // Plugin dependencies (usually auto-added by Capacitor sync)
    implementation "androidx.room:room-runtime:2.6.1"
    implementation "androidx.work:work-runtime-ktx:2.9.0"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
    annotationProcessor "androidx.room:room-compiler:2.6.1"
}

Step 4: iOS Configuration

4.1 Update Info.plist

Add to ios/App/App/Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>background-app-refresh</string>
    <string>background-processing</string>
</array>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.timesafari.dailynotification.content-fetch</string>
    <string>com.timesafari.dailynotification.notification-delivery</string>
</array>

4.2 Enable Capabilities

In Xcode:

1. Select your app target
2. Go to "Signing & Capabilities"
3. Enable "Background Modes"
4. Check "Background App Refresh" and "Background Processing"

Step 5: Use the Plugin

Basic Usage

import { DailyNotification } from '@timesafari/daily-notification-plugin';

// Configure the plugin
await DailyNotification.configure({
  storage: 'tiered',
  ttlSeconds: 1800,
  enableETagSupport: true
});

// Schedule a daily notification
await DailyNotification.scheduleDailyNotification({
  title: 'Daily Update',
  body: 'Your daily content is ready',
  schedule: '0 9 * * *' // 9 AM daily (cron format)
});

Request Permissions

// Check permissions
const status = await DailyNotification.checkPermissions();
console.log('Notification permission:', status.notifications);

// Request permissions
if (status.notifications !== 'granted') {
  await DailyNotification.requestPermissions();
}

Schedule a Simple Reminder

// Schedule a static daily reminder (no network required)
await DailyNotification.scheduleDailyReminder({
  id: 'morning_checkin',
  title: 'Good Morning!',
  body: 'Time to check your updates',
  time: '09:00', // HH:mm format
  sound: true,
  vibration: true,
  priority: 'normal'
});

Diagnostic Methods (Android)

// Check if an alarm is scheduled
const result = await DailyNotification.isAlarmScheduled({
  triggerAtMillis: scheduledTime
});
console.log('Alarm scheduled:', result.scheduled);

// Get next alarm time
const nextAlarm = await DailyNotification.getNextAlarmTime();
if (nextAlarm.scheduled) {
  console.log('Next alarm:', new Date(nextAlarm.triggerAtMillis));
}

// Test alarm delivery (schedules alarm for 10 seconds from now)
await DailyNotification.testAlarm({ secondsFromNow: 10 });

Step 6: Verify Installation

Check Plugin Registration

// Verify plugin is available
if (window.Capacitor?.Plugins?.DailyNotification) {
  console.log('✅ Plugin is registered');
} else {
  console.error('❌ Plugin not found');
}

Test Notification

// Schedule a test notification for 10 seconds from now
await DailyNotification.testAlarm({ secondsFromNow: 10 });

// Or schedule a regular notification
await DailyNotification.scheduleDailyReminder({
  id: 'test',
  title: 'Test Notification',
  body: 'This is a test',
  time: new Date(Date.now() + 60000).toTimeString().slice(0, 5) // 1 minute from now
});

Troubleshooting

Notifications Not Appearing

1. Check NotifyReceiver Registration: Verify NotifyReceiver is in your AndroidManifest.xml (see Step 3.1)
2. Check Permissions: Ensure notification permissions are granted
3. Check Logs: Use ADB to check logs:

   adb logcat | grep -E "DNP-|NotifyReceiver|Notification"
   

4. Use Diagnostic Methods: Use isAlarmScheduled() and getNextAlarmTime() to verify alarms

Common Issues

Android: "Alarm fires but notification doesn't appear"

• Solution: Ensure NotifyReceiver is registered in your app's AndroidManifest.xml (not just the plugin's manifest)

Android: "Permission denied" errors

• Solution: Request POST_NOTIFICATIONS and SCHEDULE_EXACT_ALARM permissions

iOS: Background tasks not running

• Solution: Ensure Background Modes are enabled in Xcode capabilities

Plugin not found

• Solution: Run npx cap sync and rebuild the app

Next Steps

• Read the API Reference for complete method documentation
• Check README.md for advanced usage examples
• Review docs/notification-testing-procedures.md for testing guidance

Support

For issues or questions:

• Check the troubleshooting section above
• Review the API documentation
• Check docs/notification-testing-procedures.md for debugging steps