{"id":23372769,"url":"https://github.com/kdroidfilter/composenativenotification","last_synced_at":"2025-04-10T17:41:47.437Z","repository":{"id":258694542,"uuid":"866393006","full_name":"kdroidFilter/ComposeNativeNotification","owner":"kdroidFilter","description":"KNotify is a Kotlin library for sending native notifications across different operating systems. It provides a simple, unified interface for sending notifications on Linux, Windows, and macOS.","archived":false,"fork":false,"pushed_at":"2024-10-27T00:17:32.000Z","size":1403,"stargazers_count":50,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-27T00:21:34.995Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kdroidFilter.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-10-02T07:15:29.000Z","updated_at":"2024-10-27T00:16:29.000Z","dependencies_parsed_at":"2024-10-27T00:21:35.762Z","dependency_job_id":null,"html_url":"https://github.com/kdroidFilter/ComposeNativeNotification","commit_stats":null,"previous_names":["kdroidfilter/knotify","kdroidfilter/composenativenotification"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdroidFilter%2FComposeNativeNotification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdroidFilter%2FComposeNativeNotification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdroidFilter%2FComposeNativeNotification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdroidFilter%2FComposeNativeNotification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kdroidFilter","download_url":"https://codeload.github.com/kdroidFilter/ComposeNativeNotification/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248262190,"owners_count":21074260,"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":[],"created_at":"2024-12-21T16:49:30.648Z","updated_at":"2025-04-10T17:41:47.407Z","avatar_url":"https://github.com/kdroidFilter.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Compose Native Notification\n\n## 🚀 Overview\n\n⚠️ **Warning**: This library is highly experimental, and bugs may occur. The API is subject to change.\n\nThe Compose Native Notification library is a Kotlin Multiplatform library designed to work with Compose Multiplatform that enables developers to add notifications to their applications in a unified way across different platforms, including Windows, Linux, Android, and macOS. The main goal of this library is to provide a declarative way to send notifications on Android while removing all boilerplate code, and to enable sending native notifications on other platforms. The library provides seamless integration with Jetpack Compose, allowing notifications to be handled consistently within Compose-based applications.\n\n- **Android**: Full notification support, except for `onDismissed` callback which is currently not functional.\n- **Windows \u0026 Linux**: Full notification support, including all callbacks (`onActivated`, `onDismissed`, `onFailed`).\n- **macOS**: Supports only sending notifications without any callbacks.\n\nThis guide explains how to use the library in your KMP project.\n\n## 📦 Installation\n\nTo use this library, add the following dependency to your KMP project:\n\n```kotlin\nimplementation(\"io.github.kdroidfilter:compose-native-notification:0.2.0\")\n```\n\nMake sure to replace `latest-version` with the version you want to use.\n\n## ⚙️ Setup\n\nThe setup is platform-specific and involves initializing the notification settings for each platform where your app will run.\n\n### 🤖 Android Setup\n\nFor Android, you need to initialize the notification channel in a context receiver:\n\n```kotlin\nnotificationInitializer(\n    defaultChannelConfig = AndroidChannelConfig(\n        channelId = \"Notification Example 1\",\n        channelName = \"Notification Example 1\",\n        channelDescription = \"Notification Example 1\",\n        channelImportance = NotificationManager.IMPORTANCE_DEFAULT,\n        smallIcon = android.R.drawable.ic_notification_overlay\n    )\n)\n```\n\n### 🖥️ JVM Setup (Linux, Windows)\n\nFor JVM-based environments like Linux and Windows, the notification initialization can be done in the `main` function:\n\n```kotlin\nNotificationInitializer.configure(\n    AppConfig(\n        appName = \"My awesome app\",\n        smallIcon = Res.getUri(\"drawable/kdroid.png\"),\n    )\n)\n```\n\n## ✨ Usage Example\n\nThe library uses a Kotlin DSL to define notifications in a declarative way, without the usual boilerplate code. Here is an example of how you can create and send a notification:\n\n```kotlin\nNotification(\n    title = \"Notification from Screen 1\",\n    message = \"This is a test notification from Screen 1\",\n    largeImage = Res.getUri(\"drawable/kdroid.png\"),\n    onActivated = { Log.d(\"NotificationLog\", \"Notification 1 activated\") },\n    onDismissed = { reason -\u003e Log.d(\"NotificationLog\", \"Notification 1 dismissed: $reason\") },\n    onFailed = { Log.d(\"NotificationLog\", \"Notification 1 failed\") }\n) {\n    Button(\"Show Message from Button 1\") {\n        Log.d(\"NotificationLog\", \"Button 1 from Screen 1 clicked\")\n        onShowMessage(\"Button 1 clicked from Screen 1's notification\")\n    }\n    Button(\"Hide Message from Button 2\") {\n        Log.d(\"NotificationLog\", \"Button 2 from Screen 1 clicked\")\n        onShowMessage(null)\n    }\n}\n```\n\nWith this DSL approach, you can create rich and interactive notifications while keeping the code clean and readable. The library handles all the necessary details, allowing you to focus on your app's core logic.\n\n### 🔑 Permission Handling Example\n\nHere's an example of how to handle notification permissions within your application:\n\n```kotlin\nval notificationProvider = getNotificationProvider()\nval hasPermission by notificationProvider.hasPermissionState\n\nnotificationProvider.requestPermission(\n    onGranted = {\n        notificationProvider.updatePermissionState(true)\n    },\n    onDenied = {\n        notificationProvider.updatePermissionState(false)\n        permissionDenied = true\n    }\n)\n```\n\nThis code helps ensure that your app properly manages permissions, updating the notification state as permissions are granted or denied.\n\n## 🌍 Platform-Specific Considerations\n\n- **Android**: Notifications require proper permission setup. You need to request permissions at runtime, as shown in the example.\n- **Linux \u0026 Windows**: Full support, including callbacks such as `onActivated`, `onDismissed`, and `onFailed`.\n- **macOS**: Notifications can be sent, but callbacks (`onDismissed`, `onActivated`) are not supported yet.\n\n## ⭐ Features\n\n- **Rich Interactive Notifications**: Use a Kotlin DSL to create rich notifications with multiple actions, images, and buttons.\n- **Callbacks for User Interaction**: Handle user actions such as `onActivated`, `onDismissed`, and `onFailed` to add interactivity to your notifications.\n- **Custom Actions**: Add buttons with custom actions to your notifications, such as showing or hiding messages.\n- **Button Support**: Notifications can include interactive buttons, allowing users to take specific actions directly from the notification.\n- **Permission Request Handling**: Manage notification permissions seamlessly using `hasPermissionState` and `requestPermission` to ensure smooth user interaction. Note: Permission handling is currently necessary only for Android.\n- **Cross-Platform Compatibility**: Seamless integration across Android, Linux, Windows, and macOS with platform-specific considerations.\n\n## 📸 Screenshots\n\n### Android\n![Android](/screenshots/Android.png)\n\n### Windows\n![Windows](/screenshots/Windows.png)\n\n### Gnome (Linux)\n![Gnome](/screenshots/Gnome.png)\n\n### KDE (Linux)\n![KDE](/screenshots/KDE.png)\n\n## ➕ Additional Usage Example\n\nHere's another example that shows how to handle permission requests and send a notification:\n\n```kotlin\nval notificationProvider = getNotificationProvider()\nval hasPermission by notificationProvider.hasPermissionState\n\nif (hasPermission) {\n    Notification(\n        title = \"Permission Granted Notification\",\n        message = \"You have successfully granted notification permissions!\",\n        onActivated = { Log.d(\"NotificationLog\", \"Permission Granted Notification activated\") },\n        onFailed = { Log.d(\"NotificationLog\", \"Permission Granted Notification failed\") }\n    ) {\n        Button(\"Acknowledge\") {\n            Log.d(\"NotificationLog\", \"Acknowledge button clicked\")\n            onShowMessage(\"Thank you for acknowledging!\")\n        }\n    }\n} else {\n    notificationProvider.requestPermission(\n        onGranted = {\n            notificationProvider.updatePermissionState(true)\n            Log.d(\"NotificationLog\", \"Notification permission granted\")\n        },\n        onDenied = {\n            notificationProvider.updatePermissionState(false)\n            Log.d(\"NotificationLog\", \"Notification permission denied\")\n        }\n    )\n}\n```\n\nThis example illustrates how to first check for notification permission, and if granted, send a notification with a custom action button.\n\n## 🛤️ Roadmap\n\n- **Native iOS and macOS Support**: Integrate native support for iOS and macOS to extend full functionality across Apple platforms.\n\n- **WASM and JavaScript Support**: Add support for WebAssembly (WASM) and JavaScript environments.\n\n- **Persistent Notifications for Audio Players**: Integrate persistent notifications, specifically tailored for use cases such as audio players.\n\n- **Progress Bar Support**: Add support for notifications with progress bars, useful for tasks such as file downloads or ongoing processes.\n\n- **Input Support for Notifications**: Add support for notifications with input fields, allowing users to respond directly within the notification.\n\n## 📜 License\n\nThe Compose Notification Library is distributed under the [MIT License](LICENSE).\n\n## 🤝 Contributing\n\nIf you would like to contribute, feel free to submit issues or pull requests on the [GitHub repository](https://github.com/kdroidFilter/ComposeNativeNotification).\n\n## 🛠️ Troubleshooting\n\n- **Android `onDismissed` callback**: This callback is not functional on Android. You can handle dismissal through other application state monitoring if needed.\n- **macOS Callbacks**: macOS does not support interactive callbacks for notifications. Only basic notifications are available.\n\n## 🧰 Under the Hood\n\n- **Linux**: Uses `libnotify` for handling notifications.\n- **Windows**: Utilizes [WinToast](https://github.com/mohabouje/WinToast) and [WinToastLibC](https://github.com/AlienCowEatCake/WinToastLibC) for managing notifications.\n\nFeel free to reach out for support or additional questions regarding implementation.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdroidfilter%2Fcomposenativenotification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkdroidfilter%2Fcomposenativenotification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdroidfilter%2Fcomposenativenotification/lists"}