---

A Kotlin Multiplatform library for effortless alarm and local notification scheduling on both Android and iOS.

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

⚙️ Setup

Installation

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

repositories {
    mavenCentral()
}

Then add Alarmee dependency to your module:

• With version catalog, open libs.versions.toml:

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

[libraries]
alarmee = { group = "io.github.tweener", name = "alarmee", version.ref = "alarmee" }

Then in your module build.gradle.kts add:

dependencies {
    implementation(libs.alarmee)
}

• Without version catalog, in your module build.gradle.kts add:

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

    implementation("io.github.tweener:alarmee:$alarmee_version")
}

The latest version is:

Platform configurations

In the commonModule, you need to use an instance of a subclass of AlarmeeScheduler. Each platform will create the corresponding subclass of the AlarmeeScheduler. This can be easily done with dependency injection.

🤖 Android

In the androidMain module, create a AlarmeePlatformConfiguration.Android(...) instance with the following parameters:

val platformConfiguration: AlarmeePlatformConfiguration = AlarmeePlatformConfiguration.Android(
    notificationIconResId = R.drawable.ic_notification,  
    notificationChannelId = "dailyNewsChannelId",  
    notificationChannelName = "Daily news notifications",  
)

🍎 iOS

In your iosMain module, create a AlarmeePlatformConfiguration.Ios:

val platformConfiguration: AlarmeePlatformConfiguration = AlarmeePlatformConfiguration.Ios

Usage

Notifications permission

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.

Create an instance of AlarmeeScheduler

Depending on your project configuration, you can create an instance of AlarmeeScheduler in two different ways:

Kotlin Multplatform (without Compose)

Using createAlarmeeScheduler(...) with the configuration created previously:

val alarmeeScheduler: AlarmeeScheduler = createAlarmeeScheduler(platformConfiguration = platformConfiguration)

Compose Multplatform

Using rememberAlarmeeScheduler(...) with the configuration created previously:

val alarmeeScheduler: AlarmeeScheduler = rememberAlarmeeScheduler(platformConfiguration = platformConfiguration)

Scheduling an alarm

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

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

alarmeeScheduler.schedule(
    alarmee = Alarmee(
        uuid = "myAlarmId",
        notificationTitle = "🎉 Congratulations! You've schedule 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 = 12, hour = 17, minute = 0),
    )
)

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.

alarmeeScheduler.cancel(uuid = "myAlarmId")

👨‍💻 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.