daily-notification-plugin/QUICK_INTEGRATION.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](./README.md) and [API.md](./API.md).

**For AI Agents**: See [AI_INTEGRATION_GUIDE.md](./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

```bash
npm install @timesafari/daily-notification-plugin
```

Or install from Git:

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

## Step 2: Sync Capacitor

```bash
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`:

```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`:

```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`:

```xml
<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

```typescript
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

```typescript
// 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

```typescript
// 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)

```typescript
// 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

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

### Test Notification

```typescript
// 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:
   ```bash
   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](./API.md) for complete method documentation
- Check [README.md](./README.md) for advanced usage examples
- Review [docs/notification-testing-procedures.md](./docs/notification-testing-procedures.md) for testing guidance

## Support

For issues or questions:
- Check the troubleshooting section above
- Review the [API documentation](./API.md)
- Check [docs/notification-testing-procedures.md](./docs/notification-testing-procedures.md) for debugging steps