Skip to content

Commit 34fcbd5

Browse files
cengiz-pzcengiz-pz
committed
Updated and unified README docs.
1 parent 5323975 commit 34fcbd5

File tree

3 files changed

+169
-250
lines changed

3 files changed

+169
-250
lines changed

‎README.md‎

Lines changed: 169 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -8,144 +8,215 @@
88

99
# <img src="addon/icon.png" width="24"> Godot Notification Scheduler Plugin
1010

11-
Notification Scheduler Plugin provides a unified GDScript interface for the scheduling of local notifications on the Android and iOS platforms.
11+
A unified GDScript interface for scheduling **local notifications** on **Android** and **iOS**.
1212

13-
_This plugin has been moved under the umbrella of [Godot SDK Integrations](https://github.com/godot-sdk-integrations) organization in Github. Previously, the plugin was placed under three separate repositories: [Android](https://github.com/cengiz-pz/godot-android-notification-scheduler-plugin), [iOS](https://github.com/cengiz-pz/godot-ios-notification-scheduler-plugin), and [addon interface](https://github.com/cengiz-pz/godot-notification-scheduler-addon)._
13+
**Features:**
14+
- Schedule local notifications with customizable titles, content, and delays.
15+
- Manage notification channels (Android) and badges (iOS).
16+
- Handle permissions and user interactions via signals.
17+
- Compatible with Godot 4.x (or specify supported versions).
1418

15-
<br/>
19+
---
1620

17-
## <img src="addon/icon.png" width="20"> Installation
18-
_Before installing this plugin, make sure to uninstall any previous versions of the same plugin._
21+
## <img src="addon/icon.png" width="20"> Table of Contents
22+
- [Installation](#installation)
23+
- [Usage](#usage)
24+
- [Signals](#signals)
25+
- [Error Codes](#error-codes)
26+
- [Platform-Specific Notes](#platform-specific-notes)
27+
- [Links](#links)
28+
- [All Plugins](#all-plugins)
29+
- [Credits](#credits)
30+
- [Contributing](#contributing)
1931

20-
_If installing both Android and iOS versions of the plugin in the same project, then make sure that both versions use the same addon interface version._
32+
---
2133

22-
There are 2 ways to install the `Notification Scheduler` plugin into your project:
23-
- Through the Godot Editor's AssetLib
24-
- Manually by downloading archives from Github
34+
<a name="installation">
2535

26-
### <img src="addon/icon.png" width="18"> Installing via AssetLib
27-
Steps:
28-
- search for and select the `Notification Scheduler` plugin in Godot Editor
29-
- click `Download` button
30-
- on the installation dialog...
31-
- keep `Change Install Folder` setting pointing to your project's root directory
32-
- keep `Ignore asset root` checkbox checked
33-
- click `Install` button
34-
- enable the plugin via the `Plugins` tab of `Project->Project Settings...` menu, in the Godot Editor
36+
## <img src="addon/icon.png" width="20"> Installation
3537

36-
#### <img src="addon/icon.png" width="16"> Installing both Android and iOS versions of the plugin in the same project
37-
When installing via AssetLib, the installer may display a warning that states "_[x number of]_ files conflict with your project and won't be installed." You can ignore this warning since both versions use the same addon code.
38+
**Uninstall previous versions** before installing.
39+
If using both Android & iOS, ensure **same addon interface version**.
40+
41+
**Options:**
42+
1. **AssetLib**
43+
- Search for `Notification Scheduler`
44+
- Click `Download` → `Install`
45+
- Install to project root, `Ignore asset root` checked
46+
- Enable via **Project → Project Settings → Plugins**
47+
- Ignore file conflict warnings when installing both versions
48+
2. **Manual**
49+
- Download release from GitHub
50+
- Unzip to project root
51+
- Enable via **Plugins** tab
3852

39-
### <img src="addon/icon.png" width="18"> Installing manually
40-
Steps:
41-
- download release archive from Github
42-
- unzip the release archive
43-
- copy to your Godot project's root directory
44-
- enable the plugin via the `Plugins` tab of `Project->Project Settings...` menu, in the Godot Editor
53+
---
4554

55+
<a name="usage">
4656

4757
## <img src="addon/icon.png" width="20"> Usage
48-
Add a `NotificationScheduler` node to your scene and follow the following steps:
49-
- Register listeners for the following signals emitted from the `NotificationScheduler` node
50-
- `notification_opened` - when user taps notification item
58+
59+
1. Add a **NotificationScheduler** node to your scene.
60+
2. Connect [signals](#signals):
61+
- `initialization_completed`
62+
- `notification_opened`
63+
- `notification_dismissed`
5164
- `permission_granted`
5265
- `permission_denied`
53-
- At startup, using the `NotificationScheduler` node to check that the application has permissions to post notifications:
54-
```
55-
$NotificationScheduler.has_post_notifications_permission()
56-
```
57-
- If the application doesn't have permissions to post notifications, then request permission using the `NotificationScheduler` node:
58-
```
59-
$NotificationScheduler.request_post_notifications_permission()
60-
```
61-
- `permission_granted` signal will be emitted when the application receives the permissions
62-
> On Android, apps that target Android 13 or higher can ask for notification permission as many times as they want until the user explicitly denies the permission twice. If the user targets Android 12 or lower, the app can ask for permission as many times as it wants until the user denies the permission once. If the user denies the permission twice, the app can't ask again unless the user reinstalls the app
63-
- After user has denied the request, you can ask to turn on notification permission manually and send them to App_Info screen using the `NotificationScheduler` node:(Best Practice: Don't promt users automatically, insted keep a button in settings to toggle notifications)
64-
```
66+
3. Check permission:
67+
```gdscript
68+
if not $NotificationScheduler.has_post_notifications_permission():
69+
$NotificationScheduler.request_post_notifications_permission()
70+
```
71+
4. To send user to App Info (manual enable):
72+
```gdscript
6573
$NotificationScheduler.open_app_info_settings()
66-
```
67-
- Create a notification channel using the `NotificationScheduler` node:
68-
```
69-
var __result = $NotificationScheduler.create_notification_channel(
70-
NotificationChannel.new()
71-
.set_id("my_channel_id")
72-
.set_name("My Channel Name")
73-
.set_description("My channel description")
74-
.set_importance(NotificationChannel.Importance.DEFAULT))
75-
```
76-
_Note: `create_notification_channel()` method returns `OK` if channel has been created successfully, `ERR_UNAVAILABLE` if plugin was not initialized, `ERR_INVALID_DATA` if `NotificationChannel` data is invalid, and `ERR_ALREADY_EXISTS` if a channel with the same ID already exists._
77-
- Build `NotificationData` object:
78-
```
79-
var my_notification_data = NotificationData.new()
80-
my_notification_data.set_id(__notification_id).\
81-
set_channel_id("my_channel_id").\
82-
set_title("My Notification Title").\
83-
set_content("My notification content").\
84-
set_small_icon_name("ic_name_of_the_icon_that_you_generated").\
85-
set_delay(my_delay_in_seconds)
86-
```
87-
- Schedule notification using the `NotificationScheduler` node:
88-
```
89-
$NotificationScheduler.schedule(
90-
my_notification_data
91-
)
92-
```
93-
- _`NotificationData`'s `set_interval(interval_in_seconds)` method can be used for scheduling repeating notifications._
94-
- _`NotificationData`'s `set_deeplink(data)` method can be used for delivering URI data along with the notification._
95-
- _The [Deeplink Plugin](https://github.com/cengiz-pz/godot-android-deeplink-plugin) can then be used to process the URI data._
96-
97-
### <img src="addon/icon.png" width="18"> Other Available Methods
98-
- `cancel(notification_id)` - cancel a notification before it is delivered.
99-
- `set_badge_count()` - set the number that appears on the app icon. (Set to 0 to remove.)
100-
- `get_notification_id()` - alternative way to get the ID of the last opened notification.
101-
102-
<br/><br/>
74+
```
75+
5. Create a notification channel:
76+
```gdscript
77+
var res = $NotificationScheduler.create_notification_channel(
78+
NotificationChannel.new()
79+
.set_id("my_channel_id")
80+
.set_name("My Channel Name")
81+
.set_description("My channel description")
82+
.set_importance(NotificationChannel.Importance.DEFAULT))
83+
```
84+
6. Build & schedule notification:
85+
```gdscript
86+
var data = NotificationData.new()
87+
.set_id(1)
88+
.set_channel_id("my_channel_id")
89+
.set_title("My Title")
90+
.set_content("My content")
91+
.set_small_icon_name("ic_custom_icon")
92+
.set_delay(10)
93+
94+
var res = $NotificationScheduler.schedule(data)
95+
```
96+
97+
**Other Methods:**
98+
- `cancel(id)` – cancel before opened/dismissed
99+
- `set_badge_count(count)` – set/remove app icon badge (iOS-only)
100+
- `get_notification_id()` – get ID of last opened notification
103101

104102
---
105103

106-
# <img src="addon/icon.png" width="24"> Android Notification Scheduler Plugin
104+
<a name="signals">
107105

108-
<p align="center">
109-
<img width="256" height="256" src="demo/assets/notification-scheduler-android.png">
110-
</p>
106+
## <img src="addon/icon.png" width="20"> Signals
111107

108+
- `initialization_completed()`: Emitted when the plugin is initialized.
109+
- `notification_opened(notification_id: int)`: Emitted when a user taps notification.
110+
- `notification_dismissed(notification_id: int)`: Emitted when a user dismisses notification.
111+
- `permission_granted(permission_name: String)`: Emitted when permission is granted.
112+
- `permission_denied(permission_name: String)`: Emitted when permission is denied.
112113

113-
## [Android-specific Documentation](android/README.md)
114-
## [AssetLib Entry](https://godotengine.org/asset-library/asset/2547)
114+
---
115+
116+
<a name="error-codes">
117+
118+
## <img src="addon/icon.png" width="20"> Error Codes
115119

116-
<br/><br/>
120+
| Constant | Value | Description |
121+
|-----------------------|-------|-----------------------------------------|
122+
| `ERR_ALREADY_EXISTS` | `1` | Channel ID already exists |
123+
| `ERR_INVALID_DATA` | `2` | Invalid notification/channel data |
124+
| `ERR_UNAVAILABLE` | `3` | Not supported on current platform |
125+
| `ERR_UNCONFIGURED` | `4` | Plugin not initialized |
126+
| `OK` | `0` | Success |
117127

118128
---
119129

120-
# <img src="addon/icon.png" width="24"> iOS Notification Scheduler Plugin
130+
<a name="platform-specific-notes">
131+
132+
## <img src="addon/icon.png" width="20"> Platform-Specific Notes
133+
134+
### Android
135+
- **Default icon:** `ic_default_notification` in `res://assets/NotificationSchedulerPlugin`
136+
- **Custom icon:**
137+
1. Generate via Android Studio → **Image Asset Studio** → **Notification Icons**
138+
2. Copy generated drawables into `res://assets/NotificationSchedulerPlugin`
139+
3. Use `set_small_icon_name("icon_name")`
140+
- **Troubleshooting:**
141+
- Logs: `adb logcat | grep 'godot'` (Linux), `adb.exe logcat | select-string "godot"` (Windows)
142+
- No small icon error: ensure icons exist in assets directory.
143+
- Battery restrictions: check **Settings → Apps → Your App → Battery**.
144+
145+
### iOS
146+
- Set notification icons in **Project → Export → iOS**.
147+
- System limits:
148+
- Max repeating notifications: 64
149+
- Min interval: 60 seconds
150+
- View XCode logs while running the game for troubleshooting.
151+
- See [Godot iOS Export Troubleshooting](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_ios.html#troubleshooting).
121152

122-
<p align="center">
123-
<img width="256" height="256" src="demo/assets/notification-scheduler-ios.png">
124-
</p>
153+
---
125154

126-
## [iOS-specific Documentation](ios/README.md)
127-
## [AssetLib Entry](https://godotengine.org/asset-library/asset/3186)
155+
## <img src="addon/icon.png" width="20"> Links
128156

129-
<br/><br/>
157+
- [AssetLib Entry Android](https://godotengine.org/asset-library/asset/2547)
158+
- [AssetLib Entry iOS](https://godotengine.org/asset-library/asset/3186)
130159

131160
---
161+
162+
<a name="all-plugins">
163+
132164
# <img src="addon/icon.png" width="24"> All Plugins
133165

134166
| Plugin | Android | iOS |
135-
| :---: | :--- | :--- |
167+
| :--- | :---: | :---: |
136168
| [Notification Scheduler](https://github.com/godot-sdk-integrations/godot-notification-scheduler) | ✅ | ✅ |
137169
| [Admob](https://github.com/godot-sdk-integrations/godot-admob) | ✅ | ✅ |
138170
| [Deeplink](https://github.com/godot-sdk-integrations/godot-deeplink) | ✅ | ✅ |
139171
| [Share](https://github.com/godot-sdk-integrations/godot-share) | ✅ | ✅ |
140172
| [In-App Review](https://github.com/godot-sdk-integrations/godot-inapp-review) | ✅ | ✅ |
141173

142-
<br/><br/>
174+
---
175+
176+
<a name="credits">
177+
178+
## <img src="addon/icon.png" width="24"> Credits
179+
180+
- Developed by [Cengiz](https://github.com/cengiz-pz)
181+
- iOS part based on [Godot iOS Plugin Template](https://github.com/cengiz-pz/godot-ios-plugin-template)
182+
- Original: [Godot Notification Scheduler](https://github.com/godot-sdk-integrations/godot-notification-scheduler)
183+
184+
---
185+
186+
<a name="contributing">
187+
188+
# <img src="addon/icon.png" width="24"> Contributing
189+
190+
This section provides information on how to build the plugin for contributors.
191+
192+
---
193+
194+
## <img src="addon/icon.png" width="20"> iOS
195+
196+
### Prerequisites
197+
198+
- [Install SCons](https://scons.org/doc/production/HTML/scons-user/ch01s02.html)
199+
- [Install CocoaPods](https://guides.cocoapods.org/using/getting-started.html)
200+
201+
---
202+
203+
### Build
204+
205+
- Run `./script/build.sh -A <godot version>` initially to run a full build
206+
- Run `./script/build.sh -cgA <godot version>` to clean, redownload Godot, and rebuild
207+
- Run `./script/build.sh -ca` to clean and build without redownloading Godot
208+
- Run `./script/build.sh -h` for more information on the build script
143209

144210
---
145-
# <img src="addon/icon.png" width="24"> Credits
146211

147-
Developed by [Cengiz](https://github.com/cengiz-pz)
212+
## <img src="addon/icon.png" width="20"> Android
148213

149-
iOS part is based on: [Godot iOS Plugin Template](https://github.com/cengiz-pz/godot-ios-plugin-template)
214+
### Build
150215

151-
Original repository: [Godot Notification Scheduler Plugin](https://github.com/godot-sdk-integrations/godot-notification-scheduler)
216+
**Options:**
217+
1. Use [Android Studio](https://developer.android.com/studio) to build via **Build->Assemble Project** menu
218+
- Switch **Active Build Variant** to **release** and repeat
219+
- Run **packageDistribution** task to create release archive
220+
2. Use project-root-level **build.sh** script
221+
- `./script/build.sh -ca` - clean existing build, do a debug build for Android
222+
- `./script/build.sh -carz` - clean existing build, do a release build for Android, and create archive

0 commit comments

Comments
 (0)