diff --git a/docs/general-api.md b/docs/general-api.md index 851b213985dbd5e6193ee7e4875c2ef5907f37cd..24ebb7528ac803a8a76c94432ff707456cc3b966 100755 --- a/docs/general-api.md +++ b/docs/general-api.md @@ -13,7 +13,7 @@ Notifications.registerRemoteNotifications(); ``` ## getInitialNotification() -This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type [Notification](http://localhost:3000/react-native-notifications/docs/notification-object). Otherwise, it resolves to undefined. +This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type [Notification](notification-object). Otherwise, it resolves to undefined. ```js const notification: Notification = await Notifications.getInitialNotification(); diff --git a/docs/general-events.md b/docs/general-events.md index 14ffe54dce069d5ba85e112b1275be683d686ab0..d1e5a55d76944dd82e72c786b6a5afe679bd3b7d 100755 --- a/docs/general-events.md +++ b/docs/general-events.md @@ -14,7 +14,7 @@ Notifications.events().registerRemoteNotificationsRegistered((event: Registered) ``` ## registerNotificationReceived() -Fired when a remote notification is received in foreground state. The handler will be invoked with an instance of [Notification](http://localhost:3000/react-native-notifications/docs/notification-object). +Fired when a remote notification is received in foreground state. The handler will be invoked with an instance of [Notification](notification-object). Should call completion function on iOS, will be ignored on Android. ```js @@ -27,7 +27,7 @@ Notifications.events().registerNotificationReceived((notification: Notification, ``` ## registerRemoteNotificationOpened() -Fired when a remote notification is opened from dead or background state. The handler will be invoked with an instance of [Notification](http://localhost:3000/react-native-notifications/docs/notification-object). +Fired when a remote notification is opened from dead or background state. The handler will be invoked with an instance of [Notification](notification-object). Should call completion function on iOS, will be ignored on Android. ```js diff --git a/docs/notification-object.md b/docs/notification-object.md index 7628e55093a3a19fdc2b2992acb14771689e2b62..da676260f8458b5cc303dcfb2f72f5c9313f1f56 100755 --- a/docs/notification-object.md +++ b/docs/notification-object.md @@ -6,6 +6,11 @@ sidebar_label: Notification Contains the payload data. +- **`message`**- returns the notification's main message string. +- **`sound`**- returns the sound string from the `aps` object. +- **`badge`**- returns the badge count number from the `aps` object. +- **`category`**- returns the category from the `aps` object (related to interactive notifications). +- **`data`**- returns the data payload (additional info) of the notification. Example: ```js diff --git a/docs/notifications-events.md b/docs/notifications-events.md new file mode 100644 index 0000000000000000000000000000000000000000..a9f0ed3a18fca475242464a9b4c59d104ea88117 --- /dev/null +++ b/docs/notifications-events.md @@ -0,0 +1,58 @@ +--- +id: notifications-events +title: Handling Notification Events +sidebar_label: Events +--- + +## iOS + +When a push notification is received by the device, the application can be in one of the following states: + +1. **Forground:** When the app is running and is used by the user right now; in this case, a `notificationReceived` event will be fired, do not forget to invoke `completion()` callback. + +Finally, when a notification is _opened_ by the device user (i.e. tapped-on), a `notificationOpened` event is fired, here as well you need to remember invoking `completion()` callback. + +Example: + +```javascript +constructor() { + Notifications.events().registerNotificationReceived((notification: Notification, completion: (response: NotificationCompletion) => void) => { + console.log("Notification Received - Foreground", notification.data); + + // Calling completion on iOS with `alert: true` will present the native iOS inApp notification. + completion({alert: true, sound: true, badge: false}); + }); + + Notifications.events().registerRemoteNotificationOpened((notification: Notification, completion: () => void, action: NotificationActionResponse) => { + console.log("Notification opened by device user", notification.data); + console.log(`Notification opened with an action identifier: ${action.identifier} and response text: ${action.text}`); + completion(); + }); +} +``` + +### Notification Object + +When you receive a push notification, you'll get an instance of [Notification](notification-object) object, contains the following methods: + +## Querying initial notification + +React-Native's [`PushNotificationsIOS.getInitialNotification()`](https://facebook.github.io/react-native/docs/pushnotificationios.html#getinitialnotification) allows for the async retrieval of the original notification used to open the App on iOS, but it has no equivalent implementation for Android. + +```javascript +import {Notifications} from 'react-native-notifications'; + +Notifications.getInitialNotification() + .then((notification) => { + console.log("Initial notification was:", (notification ? notification.data : 'N/A')); + }) + .catch((err) => console.error("getInitialNotifiation() failed", err)); + +``` + +> **Note** +> +> Notifications are considered 'initial' under the following terms: + +> - User tapped on a notification, _AND_ - +> - App was either not running at all ("dead" state), _OR_ it existed in the background with **no running activities** associated with it. diff --git a/example/index.js b/example/index.js index b0bbf368ba5ecb6a431158e0572493b2252eb413..776b78a9df34eba84239dd273852ff437a3c93db 100644 --- a/example/index.js +++ b/example/index.js @@ -39,7 +39,7 @@ class NotificationsExampleApp extends Component { } requestPermissions() { - Notifications.ios.requestPermissions(); + Notifications.registerRemoteNotifications(); } setCategories() { diff --git a/lib/ios/RNNotificationEventHandler.m b/lib/ios/RNNotificationEventHandler.m index 1075d427cd8a4b3f46c76bebcf766d01d3fdd851..db5e7fe4c4d2dde6563d9053def6e183275e010b 100644 --- a/lib/ios/RNNotificationEventHandler.m +++ b/lib/ios/RNNotificationEventHandler.m @@ -30,7 +30,7 @@ - (void)didReceiveNotificationResponse:(UNNotificationResponse *)response completionHandler:(void (^)(void))completionHandler { [_store setActionCompletionHandler:completionHandler withCompletionKey:response.notification.request.identifier]; - [RNEventEmitter sendEvent:RNNotificationOpened body:[RNNotificationParser parseNotification:response.notification]]; + [RNEventEmitter sendEvent:RNNotificationOpened body:[RNNotificationParser parseNotificationResponse:response]]; } @end diff --git a/lib/src/Notifications.ts b/lib/src/Notifications.ts index ca0016caf17ad8e5e5b2e92c90b350e71fee3def..6291136f9beb2977e709115960c5eab6ecc25d64 100644 --- a/lib/src/Notifications.ts +++ b/lib/src/Notifications.ts @@ -56,7 +56,7 @@ export class NotificationsRoot { /** * getInitialNotification */ - public getInitialNotification(): Promise { + public getInitialNotification(): Promise { return this.commands.getInitialNotification(); } diff --git a/lib/src/adapters/NativeEventsReceiver.ts b/lib/src/adapters/NativeEventsReceiver.ts index de54bb46732f43599f18e40110f028f4dffbdbd2..e8e712d96a9d284061489ee697ca2d01e97978e2 100644 --- a/lib/src/adapters/NativeEventsReceiver.ts +++ b/lib/src/adapters/NativeEventsReceiver.ts @@ -3,6 +3,7 @@ import { Registered, RegistrationError, RegisteredPushKit } from '../interfaces/NotificationEvents'; import { Notification } from '../DTO/Notification'; +import { NotificationActionResponse } from '../interfaces/NotificationActionResponse'; export class NativeEventsReceiver { private emitter: EventEmitter; @@ -28,9 +29,10 @@ export class NativeEventsReceiver { return this.emitter.addListener('pushKitNotificationReceived', callback); } - public registerRemoteNotificationOpened(callback: (response: Notification, completion: () => void) => void): EmitterSubscription { - return this.emitter.addListener('notificationOpened', (payload, completion) => { - callback(new Notification(payload), completion); + public registerRemoteNotificationOpened(callback: (notification: Notification, completion: () => void, actionResponse?: NotificationActionResponse) => void): EmitterSubscription { + return this.emitter.addListener('notificationOpened', (response, completion) => { + const action = response.action ? new NotificationActionResponse(response.action) : undefined + callback(new Notification(response.notification), completion, action); }); } diff --git a/lib/src/commands/Commands.ts b/lib/src/commands/Commands.ts index 9e5ea0ec8fcea7846cab050780242dd99e0d422d..41b62f4ac00c0db88bca65aeda4fdfdbe2b4e02b 100644 --- a/lib/src/commands/Commands.ts +++ b/lib/src/commands/Commands.ts @@ -9,7 +9,7 @@ export class Commands { constructor( private readonly nativeCommandsSender: NativeCommandsSender, private readonly uniqueIdProvider: UniqueIdProvider - ) {} + ) { } public postLocalNotification(notification: Notification, id?: number) { const notificationId: number = id ? id : this.uniqueIdProvider.generate(); @@ -17,9 +17,13 @@ export class Commands { return result; } - public async getInitialNotification(): Promise { + public async getInitialNotification(): Promise { return this.nativeCommandsSender.getInitialNotification().then((payload) => { - return new Notification(payload); + if (payload) { + return new Notification(payload); + } + + return undefined; }); } diff --git a/lib/src/interfaces/NotificationActionResponse.ts b/lib/src/interfaces/NotificationActionResponse.ts index 4659e97cadda80321ffe1e1c786b2387be3893c2..664c1b97a9928ac5cd83049f1e01fee91d48ac7a 100644 --- a/lib/src/interfaces/NotificationActionResponse.ts +++ b/lib/src/interfaces/NotificationActionResponse.ts @@ -1,4 +1,9 @@ -export interface NotificationActionResponse { +export class NotificationActionResponse { identifier: string; - text: string; + text?: string; + + constructor(response: any) { + this.identifier = response.identifier; + this.text = response.text; + } } diff --git a/website/i18n/en.json b/website/i18n/en.json index 04230eb1047462ee5c72ea4e152fe085aae45b54..17492b929d4fa45a99589bdb5534f29f13e58083 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -45,6 +45,10 @@ "title": "Notification object", "sidebar_label": "Notification" }, + "notifications-events": { + "title": "Handling Notification Events", + "sidebar_label": "Events" + }, "subscription": { "title": "Push Notifications Subscription", "sidebar_label": "Subscription" diff --git a/website/sidebars.json b/website/sidebars.json index 0a27c717d001a0bcdeefc35ba3ff1ac171cc1ba4..71d313fbb46d04021301fcf3548fe3942726757b 100755 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,7 +1,7 @@ { "docs": { "Installation": ["installation-ios", "installation-android"], - "Guides": ["subscription", "localNotifications"], + "Guides": ["subscription", "notifications-events", "localNotifications"], "Advanced": ["advanced-ios"] }, "api": {