alarmee

2.7.0indexed

Facilitates seamless alarm and notification scheduling across Android and iOS, ensuring easy integration and cross-platform functionality with straightforward installation steps.

AndroidJSJVMNativeWasm·Tweener/alarmee

315

Stars

Used by

dependents

Health

/ 100

gradle-version

Alarmee logo

Alarmee

Alarmee is a Kotlin/Compose Multiplatform library designed to simplify scheduling alarms and notifications on both Android and iOS platforms. With Alarmee, you can schedule one-time or repeating alarms, display platform-specific notifications, and now supports push notifications using Firebase Cloud Messaging (Android) and Apple Push Notification service (iOS).

[!WARNING] Upgrading from v1.x?
Check out the Migration Guide to update your code for version 2.0.

Be sure to show your support by starring ⭐️ this repository, and feel free to contribute if you're interested!

🌟 Features

Group 4

🚀 Used in production

Alarmee powers notifications in real-world apps:

KMPShip: a Kotlin Multiplatform boilerplate / starter-kit to build mobile apps faster.
Snappit: a daily video journaling app.
Bloomeo: a personal finance app.

🛠️ Installation

In your settings.gradle.kts file, add Maven Central to your repositories:

repositories {
  mavenCentral()
}

Then add Alarmee dependency to your module.

For local notifications only, use alarmee dependency.
For both local and push notifications, use alarmee-push dependency.

With version catalog:

Open libs.versions.toml:

[versions]
alarmee = "2.4.0" // Check latest version

[libraries]
alarmee = { group = "io.github.tweener", name = "alarmee", version.ref = "alarmee" } // For local notifications only
alarmee = { group = "io.github.tweener", name = "alarmee-push", version.ref = "alarmee" } // For both local & push notifications

Then in your module build.gradle.kts add:

Without version catalog:

In your module build.gradle.kts add:

dependencies {
    val alarmee_version = "2.4.0" // Check latest version

    // Only one of these is needed, depending on your use case
    implementation("io.github.tweener:alarmee:$alarmee_version") // For local notifications only
    implementation("io.github.tweener:alarmee-push:$alarmee_version") // For both local & push notifications
}

The latest version is:

🔧 Configuration

To get started with Alarmee, you need to provide a platform-specific configuration for Android and iOS. Follow these steps.

1. Declare an expect function in `commonMain`

In your commonMain source set, declare the following function to provide platform-specific configuration:

expect fun createAlarmeePlatformConfiguration(): AlarmeePlatformConfiguration

2. Provide the actual implementation in `androidMain`

In the androidMain source set, implement the actual function and return an AlarmeeAndroidPlatformConfiguration:

actual fun createAlarmeePlatformConfiguration(): AlarmeePlatformConfiguration =
    AlarmeeAndroidPlatformConfiguration(
        notificationIconResId = R.drawable.ic_notification,
        notificationIconColor = androidx.compose.ui.graphics.Color.Red, // Defaults to Color.Transparent is not specified
        useExactScheduling = , 
        notificationChannels = listOf(
            AlarmeeNotificationChannel(
                id = ,
                name = ,
                importance = NotificationManager.IMPORTANCE_HIGH,
                soundFilename = ,
            ),
            AlarmeeNotificationChannel(
                id = ,
                name = ,
                importance = NotificationManager.IMPORTANCE_LOW,
            ),
            
        )
    )

3. Provide the actual implementation in `iosMain`

In the iosMain source set, implement the actual function and return an AlarmeeIosPlatformConfiguration:

val platformConfiguration: AlarmeePlatformConfiguration = AlarmeeIosPlatformConfiguration

4. Initialize `AlarmeeService`

There are multiple ways to initialize Alarmee depending on your setup.

✅ For all targets (Android, iOS, desktop, etc.)

With Compose:

val alarmService: AlarmeeService = rememberAlarmeeService(
    platformConfiguration = createAlarmeePlatformConfiguration()
)

Without Compose:

val alarmeeService = createAlarmeeService()
alarmeeService.initialize(platformConfiguration = createAlarmeePlatformConfiguration())

📱 For mobile targets only (Android & iOS)

Alarmee also supports push notifications on mobile via Firebase (Android) or APNs (iOS). If you're already using Firebase in your app, you can pass your own Firebase instance to avoid initializing it twice.

With Compose:

If you're not using Firebase yet:

val alarmService: MobileAlarmeeService = rememberAlarmeeMobileService(
    platformConfiguration = createAlarmeePlatformConfiguration()
)

If you're already using Firebase elsewhere in your app:

val alarmService: MobileAlarmeeService = rememberAlarmeeMobileService(
    platformConfiguration = createAlarmeePlatformConfiguration(),
    firebase = Firebase
)

Without Compose:

If you're not using Firebase yet:

val alarmeeService = createAlarmeeMobileService()
alarmeeService.initialize(platformConfiguration = createAlarmeePlatformConfiguration())

If you're already using Firebase:

val alarmeeService = createAlarmeeMobileService()
alarmeeService.initialize(
    platformConfiguration = createAlarmeePlatformConfiguration(),
    firebase = Firebase
)

You can then use this instance to schedule or cancel alarms from your shared code.

🧑‍💻 Usage

[!IMPORTANT] Before using Alarmee, make sure the Notifications permission is granted on the target platform (Android official documentation, iOS official documentation).

Alternativally, you can use moko-permissions to easily handle permissions for you.

After initializing AlarmeeService, you can access the notification services:

Local Notifications (all platforms)

To send local notifications, use the local service:

val localService = alarmService.local
localService.schedule(...) // For instance

This is available on all targets (Android, iOS, desktop, web, etc.).

Push Notifications (mobile only)

To access push notifications (e.g. Firebase):

val pushService = alarmService.push

This is only available on Android and iOS. On non-mobile targets, pushService will be null.

Local Notification Service

1. Scheduling a one-off alarm

You can schedule an alarm to be triggered at a specific time of the day, using AlarmeeService#schedule(...). When the alarm is triggered, a notification will be displayed.

For instance, to schedule an alarm on January 12th, 2025, at 5 PM:

localService.schedule(
    alarmee = Alarmee(
        uuid = "myAlarmId",
        notificationTitle = "🎉 Congratulations! You've scheduled an Alarmee!",
        notificationBody = "This is the notification that will be displayed at the specified date and time.",
        scheduledDateTime = LocalDateTime(year = 2025, month = Month.JANUARY, dayOfMonth = , hour = , minute = ),
        deepLinkUri = , 
        imageUrl = , 
        androidNotificationConfiguration = AndroidNotificationConfiguration( 
            priority = AndroidNotificationPriority.HIGH,
            channelId = ,
        ),
        iosNotificationConfiguration = IosNotificationConfiguration(),
    )
)

2. Scheduling a repeating alarm

You can specify a RepeatInterval parameter, which allows scheduling an alarm to repeat hourly, daily, weekly, monthly, yearly or custom, based on the specified scheduledDateTime.

Fixed repeat interval

You can use a fixed repeat interval to schedule an Alarmee every hour, day, week, month, or year. For instance, to schedule an alarm to repeat every day at 9:30 AM, you can use RepeatInterval.Daily:

localService.schedule(
    alarmee = Alarmee(
        uuid = "myAlarmId",
        notificationTitle = "🔁 Congratulations! You've scheduled a daily repeating Alarmee!",
        notificationBody = "This notification will be displayed every day at 09:30.",
        scheduledDateTime = LocalDateTime(year = 2025, month = Month.JANUARY, dayOfMonth = 12, hour = 9, minute = 30),
        repeatInterval = RepeatInterval.Daily, // Will repeat every day
        androidNotificationConfiguration = AndroidNotificationConfiguration( // Required configuration for Android target only (this parameter is ignored on iOS)
            priority = AndroidNotificationPriority.DEFAULT,
            channelId = ,
        ),
        iosNotificationConfiguration = IosNotificationConfiguration(),
    )
)

Custom repeat interval

You can also set a custom repeat interval using RepeatInterval.Custom(duration) to schedule an Alarmee at a specified duration interval. For example, to schedule an alarm to repeat every 15 minutes, you can use RepeatInterval.Custom(duration = 15.minutes):

localService.schedule(
    alarmee = Alarmee(
        uuid = "myAlarmId",
        notificationTitle = "🔁 Congratulations! You've scheduled a custom repeating Alarmee!",
        notificationBody = "This notification will be displayed every 15 minutes",
        repeatInterval = RepeatInterval.Custom(duration = 15.minutes), // Will repeat every 15 minutes
        androidNotificationConfiguration = AndroidNotificationConfiguration( // Required configuration for Android target only (this parameter is ignored on iOS)
            priority = AndroidNotificationPriority.DEFAULT,
            channelId = "otherChannelId",
        ),
        iosNotificationConfiguration = IosNotificationConfiguration(),
    )
)

3. Cancelling an alarm

An alarm can be cancelled using its uuid, using Alarmee#cancel(...). If an alarm with the specified uuid is found, it will be canceled, preventing any future notifications from being triggered for that alarm.

localService.cancel(uuid = "myAlarmId")

4. Cancelling all alarms

You can cancel all scheduled alarms at once using cancelAll(). This will cancel all pending alarms that have been scheduled through this service.

localService.cancelAll()

[!NOTE] On Android, this cancels all displayed notifications. Due to AlarmManager API limitations, scheduled alarms cannot be canceled in bulk - they must be canceled individually using their specific identifiers.

5. Trigger an alarm right away

You can trigger an alarm to instantly display a notification without scheduling it for a specific time:

localService.immediate(
    alarmee = Alarmee(
        uuid = "myAlarmId",
        notificationTitle = "🚀 Congratulations! You've pushed an Alarmee right now!",
        notificationBody = "This notification will be displayed right away",
        androidNotificationConfiguration = AndroidNotificationConfiguration( // Required configuration for Android target only (this parameter is ignored on iOS)
            priority = AndroidNotificationPriority.DEFAULT,
            channelId = "immediateChannelId",
        ),
        iosNotificationConfiguration = IosNotificationConfiguration(),
    )
)

6. Notification customization

Notification sound

You can customize the notification sound on both Android and iOS.

[!WARNING] Custom sounds must be under 30 seconds in length on both Android and iOS. If the sound exceeds this limit, the system will fall back to the default notification sound..

🤖 Android

Notification sounds are set via AlarmeeNotificationChannel, which allows you to define the sound file for a specific notification channel.

🍎 iOS

Notification sounds are set in the IosNotificationConfiguration by providing the file name of the sound located in the app's bundle.

Add your sound file to your Xcode project under the main bundle.
Reference the sound file with its exact name and extension:

Notification icon

🤖 Android

Global icon customization: You can set a default notification icon color and drawable for all notifications for your app.

🍎 iOS

On iOS, customizing icon colors and drawables is not supported.

Notification badge

🤖 Android

On Android, badge numbers are managed by the system and direct control over the badge number is not available in the notification API. The system automatically handles badge updates based on notifications.

🍎 iOS

You can customize the badge number displayed on the app icon for notifications. This is done using the IosNotificationConfiguration:

Alarmee(
    // ...
    iosNotificationConfiguration = IosNotificationConfiguration(
        badge = 4,
    ),
)

If badge = 0, the badge will be cleared from the app icon. If , the badge will not be updated.

Notification action buttons

You can add up to 3 action buttons to your notifications. When a user taps an action button, your app receives a callback with the action ID.

Adding action buttons to a notification:

localService.immediate(
    alarmee = Alarmee(
        uuid = "messageNotificationId",
        notificationTitle = "📩 New Message",
        notificationBody = "You have a new message!",
        actions = listOf(
            NotificationAction(id = "reply", label = "Reply"),
            NotificationAction(id = "mark_read", label = "Mark as Read"),
            NotificationAction(id = "dismiss", label = "Dismiss"),
        ),
        androidNotificationConfiguration = AndroidNotificationConfiguration(
            priority = AndroidNotificationPriority.HIGH,
            channelId = "messagesChannelId",
        ),
        iosNotificationConfiguration = IosNotificationConfiguration(),
    )
)

Handling action button clicks:

To receive callbacks when a user taps an action button, register a callback using the onActionClicked extension function:

import com.tweener.alarmee.onActionClicked

// Register the callback early in your app lifecycle
alarmService.local.onActionClicked { event ->
    println("Action clicked: ${event.actionId} on notification ${event.notificationUuid}")

    when (event.actionId) {
        "reply" -> { /* Handle reply action */ }
        "mark_read" -> { /* Handle mark as read action */ }
        "dismiss" -> { /* Handle dismiss action */ }
    }
}

[!IMPORTANT]

Only one callback can be registered at a time. Subsequent calls replace the previous callback.

Register the callback early in your app lifecycle (e.g., in Application.onCreate() on Android or a LaunchedEffect in your root composable).

On Android, the notification is automatically dismissed when an action button is tapped.

Notification grouping

You can bundle related notifications together by giving them the same groupKey. On Android, notifications sharing a key are displayed as a notification group; on iOS, they are grouped by thread in Notification Center. The same groupKey works across both platforms.

localService.immediate(
    alarmee = Alarmee(
        uuid = "newMessage_42",
        notificationTitle = "📩 New Message",
        notificationBody = "You have a new message!",
        groupKey = "chat_messages", // Notifications sharing this key are bundled together
        androidNotificationConfiguration = AndroidNotificationConfiguration(
            priority = AndroidNotificationPriority.HIGH,
            channelId = "messagesChannelId",
        ),
        iosNotificationConfiguration = IosNotificationConfiguration(),
    )
)

On Android only, you can optionally post a dedicated summary notification that represents the whole bundle when collapsed by setting isGroupSummary = true on one notification of the group (isGroupSummary is ignored on other platforms):

androidNotificationConfiguration = AndroidNotificationConfiguration(
    channelId = "messagesChannelId",
    isGroupSummary = true, // Marks this notification as the summary of its group
)

[!NOTE] For push notifications, add a groupKey entry to the message data payload to group incoming remote notifications.

Push Notification Service

[!WARNING] On iOS, make sure to add Firebase as a dependency (https://github.com/firebase/firebase-ios-sdk) to your Xcode project.

Then, in your target, add Background Modes (check Remote notifications) and Push notifications capabilities.

The PushNotificationService handles push notifications for mobile platforms only (Android & iOS). It is available via the MobileAlarmeeService interface.

You can access it like this:

val pushService = alarmService.push

This is only available on Android and iOS. On other targets, pushService will be null.

Getting the Firebase Installation ID

You can retrieve the Firebase Installation ID for the current app instance:

val installationIdResult = pushService.getInstallationId()
installationIdResult.onSuccess { installationId ->
    println("Firebase Installation ID: $installationId")
}.onFailure { error ->
    println("Failed to get Installation ID: $error")
}

The Installation ID uniquely identifies the app installation on the device and is useful for analytics, targeting specific devices, or debugging.

Firebase Token Management

Firebase Cloud Messaging (FCM) tokens can change when:

The app is restored on a new device
The app is restored from backup
The app data is cleared
The token is periodically refreshed by Firebase

You can retrieve the current FCM token:

val tokenResult = pushService.getToken()
tokenResult.onSuccess { token ->
    println("FCM Token: $token")
    // Send token to your server
}.onFailure { error ->
    println("Failed to get token: $error")
}

To handle token updates, register a callback that will be notified whenever a new token is generated:

pushService.onNewToken { newToken ->
    // Update your server with the new token
    sendTokenToServer(newToken)
}

You can also manually refresh the token for testing purposes:

pushService.forceTokenRefresh()

Push Message Callbacks

To handle incoming push message payloads in your app (e.g., for custom processing, updating UI, or syncing data), register a callback that will be invoked whenever a push message is received:

pushService.onPushMessageReceived { payload ->
    println("📩 Push message received with payload: $payload")
    // Handle custom logic here, e.g., update UI, sync data, etc.
}

This callback receives the complete key-value payload from the push message, allowing you to access any custom data sent with the notification. The callback is triggered before the notification is displayed to the user.

Note: You can register multiple callbacks - all registered callbacks will be invoked when a push message is received.

Bridging platform callbacks (iOS only)

On Android, Alarmee receives new FCM tokens and incoming push messages automatically through its internal FirebaseMessagingService — there is nothing to wire up.

On iOS, the host application owns the AppDelegate callbacks, so you must forward token updates and incoming messages to Alarmee. Use PushNotificationServiceRegistry to propagate these events — this triggers the onNewToken and onPushMessageReceived callbacks registered above:

import com.tweener.alarmee.PushNotificationServiceRegistry

// Call when a new FCM token is generated:
PushNotificationServiceRegistry.notifyTokenUpdated(token)

// Call when a push message is received:
PushNotificationServiceRegistry.notifyIncomingMessage(data)

A common pattern is to expose these through a small Kotlin helper that your Swift AppDelegate can call:

class AlarmeeHelper {

     {
        PushNotificationServiceRegistry.notifyTokenUpdated(token = token)
    }

     {
          = userInfo
            ?.mapNotNull { (key, value) ->
                 k = key?.toString()
                 v = value?.toString()
                 (k !=  && v != ) k to v  
            }
            ?.toMap()
            ?: emptyMap()

        PushNotificationServiceRegistry.notifyIncomingMessage( = )
    }
}

Then wire it up in your AppDelegate.swift:

Add the Notification Service Extension (iOS only)

To display images in push notifications on iOS, create a Notification Service Extension and paste the provided NotificationService.swift file:

In Xcode, go to File > New > Target...
Choose Notification Service Extension
Name it AlarmeeNotificationService
Replace the content of the created file with NotificationService.swift

Sending a test push notification

To send a push notification manually using Postman or curl, you can call the FCM v1 HTTP API with the following:

URL:

https://fcm.googleapis.com/v1/projects/{YOUR_FIREBASE_PROJECT_ID}/messages:send

Replace {YOUR_PROJECT_ID} with your Firebase project ID.

Example payload:

token: the FCM token of the target device.
apns.payload.aps.mutable-content: required for displaying images on iOS.

Authentication (Bearer Token)

To authenticate requests to the FCM HTTP v1 API, you must include a Bearer token in the Authorization header.

Make sure you have the gcloud CLI installed and authenticated.
Set the correct project with:

gcloud config set project YOUR_FIREBASE_PROJECT_ID

Get an access token with:

gcloud auth print-access-token

In Postman or cURL, set the header:

Authorization: Bearer YOUR_ACCESS_TOKEN

That's it! Your push notifications will now support images on iOS.

🔄 Migration Guide: From Alarmee 1.x to 2.0

Version 2.0 introduces a new API structure with a focus on clearer service boundaries and support for both local and push notifications. Follow these steps to migrate your existing code:

1. Replace `AlarmeeScheduler` with `AlarmeeService`

In 1.x, the entry point was:

val alarmeeScheduler: AlarmeeScheduler = rememberAlarmeeScheduler(
    platformConfiguration = platformConfiguration
)

In 2.0, it has been replaced by:

val alarmService: AlarmeeService = rememberAlarmeeService(
    platformConfiguration = platformConfiguration
)

2. Update function calls

All method calls on AlarmeeScheduler should now be redirected to the local notification service from AlarmeeService:

Replace:

alarmeeScheduler.schedule(alarmee)

With:

alarmService.local.schedule(alarmee)

Similarly, any other function calls (e.g., cancel(...), immediate(...), etc.) should follow this pattern:

// Before
alarmeeScheduler.cancel(alarmee)

// After
alarmService.local.cancel(alarmee)

3. Rename `push(alarmee)` to `immediate(alarmee)`

In 1.x, to instantly trigger a local notification, you called:

alarmeeScheduler.push(alarmee)

In 2.0, this method has been renamed to:

alarmService.local.immediate(alarmee)

✅ Summary of Changes

👨‍💻 Contributing

We love your input and welcome any contributions! Please read our contribution guidelines before submitting a pull request.

🙏 Credits

Logo by Freeicons

📜 Licence

Alarmee is licensed under the Apache-2.0.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

czan★ 79

TweenerDesign system library inspired by Paul Cezanne, tailored for apps with a specific look and feel for targeted platforms like Material 3 for Android and Cupertino for iOS, following Atomic Design methodology.Shared: compose-multiplatform, compose

passage★ 118

TweenerSimplifies authentication flows using Firebase Authentication, offering composable APIs for Google, Apple, and Email/Password providers. Supports extensible configuration and email actions for user management.Shared: compose-multiplatform, compose

compose-rich-editor★ 1.8k

MohamedRejebRich text editor library for creating customizable WYSIWYG editors, supporting text styling, links, code blocks, lists, and HTML/Markdown import/export with minimal boilerplate.Shared: compose-multiplatform, compose

`AlarmeeScheduler`	`AlarmeeService`
`rememberAlarmeeScheduler(...)`	`rememberAlarmeeService(...)`
`alarmeeScheduler.schedule(...)`	`alarmService.local.schedule(...)`
`alarmeeScheduler.cancel(...)`	`alarmService.local.cancel(...)`
`alarmeeScheduler.push(...)`	`alarmService.local.immediate(...)`

alarmee

Alarmee

🌟 Features

🚀 Used in production

🛠️ Installation

🔧 Configuration

1. Declare an expect function in commonMain

2. Provide the actual implementation in androidMain

3. Provide the actual implementation in iosMain

4. Initialize AlarmeeService

✅ For all targets (Android, iOS, desktop, etc.)

📱 For mobile targets only (Android & iOS)

🧑‍💻 Usage

Local Notifications (all platforms)

Push Notifications (mobile only)

Local Notification Service

1. Scheduling a one-off alarm

2. Scheduling a repeating alarm

Fixed repeat interval

Custom repeat interval

3. Cancelling an alarm

4. Cancelling all alarms

5. Trigger an alarm right away

6. Notification customization

Notification sound

Notification icon

Notification badge

Notification action buttons

Notification grouping

Push Notification Service

Getting the Firebase Installation ID

Firebase Token Management

Push Message Callbacks

Bridging platform callbacks (iOS only)

Add the Notification Service Extension (iOS only)

Sending a test push notification

Authentication (Bearer Token)

🔄 Migration Guide: From Alarmee 1.x to 2.0

1. Replace AlarmeeScheduler with AlarmeeService

2. Update function calls

Replace:

With:

3. Rename push(alarmee) to immediate(alarmee)

✅ Summary of Changes

👨‍💻 Contributing

🙏 Credits

📜 Licence

Related libraries

Alarmee

🌟 Features

🚀 Used in production

🛠️ Installation

🔧 Configuration

1. Declare an expect function in commonMain

2. Provide the actual implementation in androidMain

3. Provide the actual implementation in iosMain

4. Initialize AlarmeeService

✅ For all targets (Android, iOS, desktop, etc.)

📱 For mobile targets only (Android & iOS)

🧑‍💻 Usage

Local Notifications (all platforms)

Push Notifications (mobile only)

Local Notification Service

1. Scheduling a one-off alarm

2. Scheduling a repeating alarm

Fixed repeat interval

Custom repeat interval

3. Cancelling an alarm

4. Cancelling all alarms

5. Trigger an alarm right away

6. Notification customization

Notification sound

Notification icon

Notification badge

Notification action buttons

Notification grouping

Push Notification Service

Getting the Firebase Installation ID

Firebase Token Management

Push Message Callbacks

1. Declare an expect function in `commonMain`

2. Provide the actual implementation in `androidMain`

3. Provide the actual implementation in `iosMain`

4. Initialize `AlarmeeService`

1. Replace `AlarmeeScheduler` with `AlarmeeService`

3. Rename `push(alarmee)` to `immediate(alarmee)`

1. Declare an expect function in `commonMain`

2. Provide the actual implementation in `androidMain`

3. Provide the actual implementation in `iosMain`

4. Initialize `AlarmeeService`

1. Replace `AlarmeeScheduler` with `AlarmeeService`

3. Rename `push(alarmee)` to `immediate(alarmee)`