capacitor-alarm-notification-plugin

A Capacitor plugin for scheduling full-screen alarm notifications that work even when the app is closed.

Installation

npm install capacitor-alarm-notification-plugin

Usage

import { AlarmNotification } from 'capacitor-alarm-notification-plugin';

// Check and request permissions first
const checkPermission = async () => {
  const { hasPermission } = await AlarmNotification.checkPermission();
  if (!hasPermission) {
    await AlarmNotification.requestPermission();
  }
};

// Set an alarm
const setAlarm = async () => {
  try {
    const result = await AlarmNotification.setAlarm({
      delay: 5000, // delay in milliseconds
      title: "Wake Up!",
      message: "Time to get up!",
      id: "my-alarm", // optional
      openButtonText: "Open App" // optional
    });
    console.log('Alarm set:', result);
  } catch (error) {
    console.error('Error setting alarm:', error);
  }
};

// Cancel the alarm
const cancelAlarm = async () => {
  try {
    const result = await AlarmNotification.cancelAlarm();
    console.log('Alarm cancelled:', result);
  } catch (error) {
    console.error('Error cancelling alarm:', error);
  }
};

// Listen for alarm actions
AlarmNotification.addListener('alarmAction', (data) => {
  console.log('Alarm action:', data.action);
  if (data.action === 'snooze') {
    console.log('Snooze for', data.snoozeMinutes, 'minutes');
  }
});

Features

• ✅ Exact alarms that work when app is closed
• ✅ Full-screen alarm UI with modern design
• ✅ Alarm sound and vibration
• ✅ Wake up device from sleep
• ✅ Show on lock screen
• ✅ Handle device reboots
• ✅ Battery optimization handling
• ✅ Permission management
• ✅ Cross-platform support (Android & iOS)
• ✅ Snooze functionality
• ✅ Customizable alarm interface
• ✅ Action buttons (Open, Dismiss, Snooze)
• ✅ Event listeners for alarm actions

Platform Support

Android

• Full native alarm implementation with exact timing
• Foreground service for reliable alarm delivery
• Boot completion handling to restore alarms after device restart
• Battery optimization bypass for critical alarms
• Custom full-screen alarm activity with snooze functionality
• Wake lock support to ensure device wakes up

iOS

• Native iOS notification system using UNUserNotificationCenter
• Action buttons (Open, Dismiss, Snooze) for user interaction
• Background app refresh support for reliable delivery
• Notification categories for organized alarm management
• Sound and vibration support
• Permission handling for notifications

Web

• Local storage-based alarm simulation for development
• Notification API integration when available
• Custom event system for alarm triggers
• Fallback implementation for testing

Android Permissions

The plugin requires the following permissions:

• SCHEDULE_EXACT_ALARM (Android 12+)
• USE_EXACT_ALARM (Android 12+)
• FOREGROUND_SERVICE
• FOREGROUND_SERVICE_SPECIAL_USE
• POST_NOTIFICATIONS (Android 13+)
• WAKE_LOCK
• RECEIVE_BOOT_COMPLETED
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS

iOS Permissions

For iOS, the plugin requires:

• Notification permissions (alert, sound, badge)
• Background app refresh capability (optional, for better reliability)

API Reference

Methods

setAlarm(options)

Schedule a new alarm notification.

Parameters:

• delay (number): Delay in milliseconds before alarm triggers
• title (string): Alarm title
• message (string): Alarm message
• id (string, optional): Unique identifier for the alarm
• openButtonText (string, optional): Custom text for the open button

cancelAlarm()

Cancel all scheduled alarms.

checkPermission()

Check if notification permissions are granted.

requestPermission()

Request notification permissions from the user.

checkIntentExtras()

Check if the app was opened from an alarm notification.

checkAlarmOpened()

Check if any alarms were opened by the user.

checkAlarmDismissed()

Check if any alarms were dismissed by the user.

addListener(eventName, listener)

Add an event listener for alarm actions.

removeAllListeners(eventName)

Remove all event listeners for a specific event.

Events

alarmAction

Fired when user interacts with alarm actions (snooze, dismiss, open).

Event data:

• action (string): Action type ('snooze', 'dismiss', 'open')
• notificationId (string): Alarm identifier
• title (string): Alarm title
• message (string): Alarm message
• snoozeMinutes (number): Snooze duration (for snooze action)

Development

Building the Plugin

npm run build

Running Tests

npm run verify

Code Quality

npm run lint
npm run fmt

License

MIT

Author

Karthik S

Repository

• GitHub: https://github.com/srikarthiks/capacitoralarm
• Issues: https://github.com/srikarthiks/capacitoralarm/issues

🚀 Key Features

• 🔔 Schedule full-screen alarms with exact timing
• ⏰ Wake the device and show alert, even when locked
• ✅ cancelAlarm() and snooze support
• 📱 Opens the main activity when alarm triggers
• 🍎 Cross-platform: Android & iOS support
• 🎨 Modern, customizable alarm interface
• 📦 Ready to publish on npm
• 🔧 Comprehensive development tools
• 🎯 Action buttons for user interaction
• 📡 Event-driven architecture

📦 Quick Start

npm install capacitor-alarm-notification-plugin
npx cap sync