{"id":15111168,"url":"https://github.com/carterchen247/alarmscheduler","last_synced_at":"2025-10-23T04:31:16.928Z","repository":{"id":43073412,"uuid":"245651581","full_name":"CarterChen247/AlarmScheduler","owner":"CarterChen247","description":"A library that helps to schedule time-exact tasks(calendar reminders, alarms, etc.)","archived":false,"fork":false,"pushed_at":"2025-01-11T04:01:47.000Z","size":1047,"stargazers_count":32,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-02-06T15:02:33.236Z","etag":null,"topics":["alarm","alarmmanager","android","android-15","android-application","android15","background-jobs","job-scheduler"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CarterChen247.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-07T14:53:45.000Z","updated_at":"2025-02-04T17:33:33.000Z","dependencies_parsed_at":"2024-06-21T23:40:49.715Z","dependency_job_id":"c5ffb4e0-9c05-4b75-8baa-2a3f1b52ee78","html_url":"https://github.com/CarterChen247/AlarmScheduler","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterChen247%2FAlarmScheduler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterChen247%2FAlarmScheduler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterChen247%2FAlarmScheduler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarterChen247%2FAlarmScheduler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CarterChen247","download_url":"https://codeload.github.com/CarterChen247/AlarmScheduler/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237780080,"owners_count":19365123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alarm","alarmmanager","android","android-15","android-application","android15","background-jobs","job-scheduler"],"created_at":"2024-09-26T00:01:59.830Z","updated_at":"2025-10-23T04:31:11.531Z","avatar_url":"https://github.com/CarterChen247.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AlarmScheduler\n\n![](https://img.shields.io/maven-central/v/com.carterchen247/alarm-scheduler) \n![](https://img.shields.io/github/languages/top/CarterChen247/AlarmScheduler)\n![](https://img.shields.io/github/actions/workflow/status/CarterChen247/AlarmScheduler/.github/workflows/android.yml?branch=master)\n\n\n\n\n\n\n\n\n**AlarmScheduler is a tool to schedule time exact tasks, even in very short period of time.**\n\n**AlarmScheduler provides various supports:**\n\n- Easy-to-use API\n- Alarms survive after device reboot\n- debuggable with built-in logger\n\n**AlarmScheduler** is built on top of **AlarmManager** + **Kotlin Coroutines** + **Room** and ❤️ !!\n\n## Add AlarmScheduler **to your project**\n\n### Gradle ![](https://img.shields.io/maven-central/v/com.carterchen247/alarm-scheduler) \n\nAdd the dependency to your **module**'s `build.gradle` file:\n\n```groovy\ndependencies {\n    implementation 'com.carterchen247:alarm-scheduler:x.x.x'\n}\n```\n\n## How to Use\n\nTo see the complete usage of AlarmScheduler, please build and refer to the [demo app](https://github.com/CarterChen247/AlarmScheduler/tree/develop/app).\n\n### Schedule an Alarm\n\n#### 1️⃣ Define a AlarmTask callback\n\n```kotlin\nAlarmScheduler.setAlarmTaskFactory(object : AlarmTaskFactory {\n    override fun createAlarmTask(alarmType: Int): AlarmTask {\n        return MyAlarmTask()\n    }\n})\n```\n\n```kotlin\nclass MyAlarmTask : AlarmTask {\n    override fun onAlarmFires(alarmId: Int, dataPayload: DataPayload) {\n        // do something with dataPayload you set\n    }\n\n    companion object {\n        const val TYPE = 1\n    }\n}\n```\n\n#### 2️⃣ And then just schedule it!\n\n```kotlin\nval config = AlarmConfig(\n    Date().time + 10000L, // trigger time\n    MyAlarmTask.TYPE\n) {\n    dataPayload(\"reminder\" to \"have a meeting\")\n}\n\nAlarmScheduler.schedule(config){ ... }\n```\n\n#### 3️⃣ Handle the result on your own\n\n```kotlin\nAlarmScheduler.schedule(config) { result: ScheduleResult -\u003e\n    when (result) {\n        is ScheduleResult.Success -\u003e {\n            // alarm scheduling success!\n        }\n        is ScheduleResult.Failure -\u003e {\n            when (result) {\n                ScheduleResult.Failure.CannotScheduleExactAlarm -\u003e {\n                    // handle scenarios like user disables exact alarm permission\n                }\n                is ScheduleResult.Failure.Error -\u003e {\n                    // handle error\n                }\n            }\n        }\n    }\n}\n```\n\n### For Android 12+\n\nWhen receiving a `CannotScheduleExactAlarm` failure result, it means the user disable the exact alarm permission. Try to use `openExactAlarmSettingPage()`  extension function with prompts to guide your user.\n\n```kotlin\nfun Activity.openExactAlarmSettingPage() {\n    if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.S) {\n        startActivity(Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM))\n    }\n}\n```\n\nget notified once user grants the exact alarm permission.\n\n```kotlin\nAlarmSchedulerEventObserver { event -\u003e\n    if (event is ScheduleExactAlarmPermissionGrantedEvent) {\n\t// get notified\n    }\n}\n```\n\n### Debugging\n\nIf something is not working, enable the built-in logger to see what’s going on.\n\n```kotlin\nAlarmScheduler.setLogger(AlarmSchedulerLogger.DEBUG)\n```\n\n### Other Features\n\n```kotlin\nAlarmScheduler.getScheduledAlarmsAsync { scheduledAlarms: List\u003cAlarmInfo\u003e -\u003e\n    // list the scheduled alarms \n}\n```\n\nThere are more! refer to [AlarmSchedulerContract](https://github.com/CarterChen247/AlarmScheduler/blob/develop/alarmscheduler/src/main/java/com/carterchen247/alarmscheduler/AlarmSchedulerContract.kt) see full APIs.\n\n```kotlin\ninternal interface AlarmSchedulerContract {\n    fun setAlarmTaskFactory(alarmTaskFactory: AlarmTaskFactory)\n    fun setLogger(loggerImpl: AlarmSchedulerLogger)\n    fun setErrorHandler(errorHandler: AlarmSchedulerErrorHandler)\n    fun isAlarmTaskScheduled(alarmId: Int): Boolean\n    fun cancelAlarmTask(alarmId: Int)\n    fun cancelAllAlarmTasks()\n    fun getScheduledAlarmsAsync(callback: ScheduledAlarmsCallback)\n    fun addEventObserver(observer: AlarmSchedulerEventObserver)\n    fun removeEventObserver(observer: AlarmSchedulerEventObserver)\n    fun schedule(config: AlarmConfig, callback: ScheduleResultCallback?)\n    fun canScheduleExactAlarms(): Boolean\n}\n```\n\n## Dealing with behavior changes\n### [Android 15 - Changes to package stopped state](https://developer.android.com/about/versions/15/behavior-changes-all#enhanced-stop-states)\n\n\u003e**✅ Tested**\n\nBy using AlarmScheduler, when the app recovers from the stopped state, it will automatically detect the `ACTION_BOOT_COMPLETED` action, and alarms will be automatically rescheduled.\n\n### [Android 14 - Schedule exact alarms are denied by default](https://developer.android.com/about/versions/14/behavior-changes-all#schedule-exact-alarms)\n\n\u003e **✅ Handled**\n\nTo handle the behavior change in Android 14, use `ScheduleResultCallback` when calling `AlarmScheduler.schedule()`. This callback will return one of the following results:\n\n- `Success`: The alarm was successfully scheduled.\n- `Failure.CannotScheduleExactAlarm`: The app doesn't have permission to schedule exact alarms.\n- `Failure.Error`: An error occurred during scheduling.\n\nHere's how to use it:\n\n```kotlin\nAlarmScheduler.schedule(config) { result: ScheduleResult -\u003e\n    when (result) {\n        is ScheduleResult.Success -\u003e {\n            // Alarm scheduling success!\n        }\n        is ScheduleResult.Failure -\u003e {\n            when (result) {\n                ScheduleResult.Failure.CannotScheduleExactAlarm -\u003e {\n                    // Handle scenarios like user disables exact alarm permission\n                    // Consider prompting the user to grant permission\n                }\n                is ScheduleResult.Failure.Error -\u003e {\n                    // Handle other errors\n                }\n            }\n        }\n    }\n}\n```\n\nFor Android 12 and above, you can use the `openExactAlarmSettingPage()` extension function to guide users to the exact alarm permission settings:\n\n```kotlin\nfun Activity.openExactAlarmSettingPage() {\n    if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.S) {\n        startActivity(Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM))\n    }\n}\n```\n\nYou can also get notified when the user grants the exact alarm permission:\n\n```kotlin\nAlarmSchedulerEventObserver { event -\u003e\n    if (event is ScheduleExactAlarmPermissionGrantedEvent) {\n        // Permission granted, you can try scheduling the alarm again\n    }\n}\n```\n\n## Apps using AlarmScheduler\n\n- [吉時倒垃圾(GarbageTruckAlarm)](https://play.google.com/store/apps/details?id=com.carterchen247.garbagetruckalarm\u0026hl=zh_TW)\n\n## License\n\n```\nMIT License\n\nCopyright (c) 2020 Carter Chen\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarterchen247%2Falarmscheduler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarterchen247%2Falarmscheduler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarterchen247%2Falarmscheduler/lists"}