diff --git a/docs/localNotifications.md b/docs/localNotifications.md new file mode 100644 index 0000000000000000000000000000000000000000..ea503ea0315cca898499244216fd30a491a3f9ca --- /dev/null +++ b/docs/localNotifications.md @@ -0,0 +1,87 @@ +--- +id: localNotifications +title: Local Notifications +sidebar_label: Local Notifications +--- + +## iOS + +You can manually trigger local notifications in your JS code, to be posted immediately or in the future. +Triggering local notifications is fully compatible with React Native `PushNotificationsIOS` library. + +Example: + +```javascript +let localNotification = Notifications.postLocalNotification({ + body: "Local notificiation!", + title: "Local Notification Title", + sound: "chime.aiff", + silent: false, + category: "SOME_CATEGORY", + userInfo: { } +}); +``` + +Notification object contains: + +- **`fireDate`**- The date and time when the system should deliver the notification (optinal - default is immidiate dispatch). +- `body`- The message displayed in the notification alert. +- `title`- The title of the notification, displayed in the notifications center. +- `alertAction`- The "action" displayed beneath an actionable notification on the lockscreen (e.g. "Slide to **open**"). Note that Apple no longer shows this in iOS 10. +- `sound`- The sound played when the notification is fired (optional -- will play default sound if unspecified). This must be the filename of a sound included in the application bundle; the sound must be 30 seconds or less and should be encoded with linear PCM or IMA4. +- `silent`- Whether the notification sound should be suppressed (optional). +- `category`- The category of this notification, required for [interactive notifications](#interactive--actionable-notifications-ios-only) (optional). +- `userInfo`- An optional object containing additional notification data. + +### Cancel Scheduled Local Notifications + +The `Notifications.postLocalNotification()` method return unique `notificationId` values, which can be used in order to cancel specific local notifications that were scheduled for delivery on `fireDate` and have not yet been delivered. You can cancel local notification by calling `Notifications.cancelLocalNotification(notificationId)`. + +Example: + +```javascript +let someLocalNotification = Notifications.postLocalNotification({ + body: "Local notificiation!", + title: "Local Notification Title", + sound: "chime.aiff", + category: "SOME_CATEGORY", + userInfo: { } +}); + +Notifications.cancelLocalNotification(someLocalNotification); +``` + +To cancel all local notifications (**iOS only!**), use `cancelAllLocalNotifications()`: + +```javascript +Notifications.ios.cancelAllLocalNotifications(); +``` + +#### Cancel Delivered Local Notifications (iOS 10+ only) + +To dismiss notifications from the notification center that have already been shown to the user, call `Notifications.ios.removeDeliveredNotifications([notificationId])`: + +```javascript +let someLocalNotification = Notifications.postLocalNotification({...}); + +Notifications.ios.removeDeliveredNotifications([someLocalNotification]); +``` + +Call `removeAllDeliveredNotifications()` to dismiss all delivered notifications +(note that this will dismiss push notifications in addition to local +notifications). + + +## Android + +Much like on iOS, notifications can be triggered locally. The API to do so is a simplified version of the iOS equivalent that works more natually with the Android perception of push (remote) notifications: + +```javascript +Notifications.postLocalNotification({ + title: "Local notification", + body: "This notification was generated by the app!", + extra: "data" +}); +``` + +Upon notification opening (tapping by the device user), all data fields will be delivered as-is). diff --git a/website/i18n/en.json b/website/i18n/en.json index 040c605a0da6e3f6b8a530c9943c435f110cc6a5..04230eb1047462ee5c72ea4e152fe085aae45b54 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -37,6 +37,10 @@ "title": "iOS", "sidebar_label": "iOS specific" }, + "localNotifications": { + "title": "Local Notifications", + "sidebar_label": "Local Notifications" + }, "notification-object": { "title": "Notification object", "sidebar_label": "Notification" diff --git a/website/sidebars.json b/website/sidebars.json index 1321381d15e387078f9b6924588931b359194410..0a27c717d001a0bcdeefc35ba3ff1ac171cc1ba4 100755 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,7 +1,7 @@ { "docs": { "Installation": ["installation-ios", "installation-android"], - "Guides": ["subscription"], + "Guides": ["subscription", "localNotifications"], "Advanced": ["advanced-ios"] }, "api": {