From 4b9e837a474c31c68797cb3f5a5829781e447ae7 Mon Sep 17 00:00:00 2001 From: Ovidiu Cristescu <55203625+LunatiqueCoder@users.noreply.github.com> Date: Fri, 11 Oct 2024 00:19:39 +0300 Subject: [PATCH 1/4] docs(ios) - Improve Remote Notification Support section --- .../docs/ios/remote-notification-support.md | 217 +++++++++++------- 1 file changed, 130 insertions(+), 87 deletions(-) diff --git a/docs-react-native/react-native/docs/ios/remote-notification-support.md b/docs-react-native/react-native/docs/ios/remote-notification-support.md index ad7450f1..f96db7e4 100644 --- a/docs-react-native/react-native/docs/ios/remote-notification-support.md +++ b/docs-react-native/react-native/docs/ios/remote-notification-support.md @@ -5,41 +5,21 @@ next: / previous: /react-native/docs/ios/permissions --- -It's possible to display a notification with Notifee features from outside the app using remote notifications (a.k.a push notifications) in two ways: - - using APNs keys - - using `notifee_options` with our notification service extension helper +> It is recommended to only use a notification service extension if you require an image or need to modify the contents of the notification before its displayed. -It is recommended to only use a notification service extension if you require an image or need to modify the contents of the notification before its displayed. +It's possible to display a notification with Notifee features from outside the app using remote notifications (a.k.a push notifications) by using `notifee_options` in APNs keys with our notification service extension helper. -### Using APNs keys +Adding a custom key `notifee_options` in the message payload enables Notifee to modify the notification before it is finally displayed to the end user. You can also change it as you please during this time. -Notification messages sent through APNs follow the APNs payload format which allows us to be able to specify a category or a custom sound with no extra configuration on the client: +> ⭐️ In order to bring the iOS experience closer to the Android one, you can still send **data-only/local/background** notifications for Android while using **remote/alert** notifications for iOS [by configuring the right payload.](#configure-the-payload) -```json -// FCM -{ - notification: { - title: 'A notification title!', - body: 'A notification body', - }, - apns: { - payload: { - aps: { - category: 'post', // A category that's already been created by your app - sound: 'media/kick.wav', // A local sound file you have inside your app's bundle - ... // any other properties - }, - }, - }, - ... -}; -``` - -### Using `notifee_options` +To get started, you will need to implement a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) for your iOS app, the following steps will guide you through how to set it up. -By adding a custom key `notifee_options` in the message payload, the notification will be modified by Notifee before it is finally displayed to the end user. +### Expo -To get started, you will need to implement a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) for your iOS app, the following steps will guide you through how to set it up. +You can jump straght to [configuring the payload](#configure-the-payload) if you use Expo with one of the community plugins: +- https://github.com/LunatiqueCoder/expo-notifee-remote-plugin +- https://github.com/evennit/notifee-expo-plugin ## Add the notification service extension @@ -48,6 +28,7 @@ To get started, you will need to implement a [Notification Service Extension](ht * Add a product name (use `NotifeeNotificationService` to follow along) and click Finish * Make sure that the **deployment target** of your newly added extension (e.g. `NotifeeNotificationService`) matches the **deployment target** of your app. You can check it by selecting you app's target -> `Build Settings` -> `Deployment` + ## Add target to the Podfile @@ -64,7 +45,7 @@ target 'NotifeeNotificationService' do end ``` - +* Assuming you are using `react-native-firebase`, you'll also have to add `use_frameworks!` inside the target above as [you did when you followed their docs](https://rnfirebase.io/#altering-cocoapods-to-use-frameworks). * Install or update your pods using pod install from the ios folder `pod install --repo-update` @@ -95,79 +76,141 @@ At this point everything should still be running normally. This is the final ste ``` -Before, moving to the next step, run the app and check it builds successfully – make sure you have the correct target selected. +## Mutate the content with Notifee: +> 🔗 [Apple Docs: Modifying content in newly delivered notifications](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications#Implement-your-extensions-handler-methods) -## Edit the payload -Now everything is setup in your app, you can alter your notification payload in two ways: +#### Objective C: -1. Update the message payload, sent via your backend -2. In a Notification Service Extension in your app when a device receives a remote message +In your `NotifeeNotificationService.m` file you should have method `didReceiveNotificationRequest` where we are calling `NotifeeExtensionHelper`. Now you can modify +`bestAttemptContent` before you send it to `NotifeeExtensionHelper`: -> Make sure that you will set `mutable-content: 1` (mutableContent if you are using firebase admin sdk) when sending notification otherwise Notification Service Extension will NOT be triggered +```objectivec +- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { + self.contentHandler = contentHandler; + self.bestAttemptContent = [request.content mutableCopy]; + + // You can also modify the payload as you please here. + // You have around 30 seconds + + // Notifee will mutate the notification according to notifee_options + [NotifeeExtensionHelper populateNotificationContent:request + withContent: self.bestAttemptContent + withContentHandler:contentHandler]; +} +``` -> Make sure that you will set `content-available: 1` (contentAvailable if you are using firebase admin sdk) if you want to receive notification when your app is in foreground +#### Swift: +In your `NotifeeNotificationService.swift` file, use the `didReceive(_:withContentHandler:)` method to enable the `NotifeeExtensionHelper`. +```swift +override func didReceive(_ request: UNNotificationRequest, + withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) { + self.contentHandler = contentHandler + self.bestAttempt = (request.content.mutableCopy() as? UNMutableNotificationContent) -### 1. Update the message payload, sent via your backend + // Here you can also modify the content of the notification as you please here. + // You have around 30 seconds -```json -// FCM -{ - notification: { - title: 'A notification title!', - body: 'A notification body', + + // Notifee will mutate the notification according to notifee_options + NotifeeExtensionHelper.populateNotificationContent(request, + with: self.bestAttempt!, + withContentHandler: contentHandler) +} +``` + +
+ +Before moving to the next step, run the app and check it builds successfully – make sure you have the correct target selected. + +## Configure the payload +> Make sure that you will set `mutable-content: 1` (mutableContent if you are using firebase admin sdk) when sending notification otherwise Notification Service Extension will NOT be triggered +> +> 🔗 [**Apple docs:** Configure-the-payload-for-the-remote-notification](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications#Configure-the-payload-for-the-remote-notification) + +### Here's an example of a payload sent from the backend with Firebase Admin Node.js SDK + +```ts + +import type {Notification} from '@notifee/react-native/src/types/Notification'; +import {AndroidImportance} from '@notifee/react-native/src/types/NotificationAndroid'; +import {MulticastMessage} from 'firebase-admin/lib/messaging/messaging-api'; +import admin from '../src/firebase-admin'; + +/** + * @link https://notifee.app/react-native/reference/notification + */ +const notifeeOptions: Notification = { + title: 'Title', + subtitle: 'Subtitle', + body: 'Main body content of the notification', + image: 'https://placeimg.com/640/480/any', // URL to pointing to a remote image + android: { + channelId: 'default', + importance: AndroidImportance.HIGH, + lightUpScreen: true, + pressAction: { + id: 'default', }, - apns: { - payload: { - aps: { - // Payloads coming from Admin SDK should specify params in camelCase. - // Payloads from REST API should specify in kebab-case - // see their respective reference documentation - 'contentAvailable': 1, // Important, to receive `onMessage` event in the foreground when message is incoming - 'mutableContent': 1, // Important, without this the extension won't fire - }, - notifee_options: { - image: 'https://placeimg.com/640/480/any', // URL to pointing to a remote image - ios: { - sound: 'media/kick.wav', // A local sound file you have inside your app's bundle - foregroundPresentationOptions: {alert: true, badge: true, sound: true, banner: true, list: true}, - categoryId: 'post', // A category that's already been created by your app - attachments: [{url: 'https://placeimg.com/640/480/any', thumbnailHidden: true}] // array of attachments of type `IOSNotificationAttachment` - ... // any other api properties for NotificationIOS - }, - ... // any other api properties for Notification, excluding `id` - }, - }, + sound: 'default', + }, + ios: { + sound: 'media/kick.wav', // A local sound file you have inside your app's bundle + categoryId: 'post', // A category that's already been created by your app + attachments: [{url: 'https://placeimg.com/640/480/any', thumbnailHidden: true}] // array of attachments of type `IOSNotificationAttachment` + // 🚧 Adding `foregroundPresentationOptions` controls how to + // 👇 behave when app is UP AND RUNNING, not terminated, AND not in background! + foregroundPresentationOptions: { + badge: true, + banner: true, + list: true, + sound: true, }, - ... + }, }; -``` -### 2. In a Notification Service Extension in your app when a device receives a remote message -In your NotifeeNotificationService.m file you should have method `didReceiveNotificationRequest` where we are calling `NotifeeExtensionHelper`. Now you can modify -`bestAttemptContent` before you send it to `NotifeeExtensionHelper`: - -```objectivec -- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { - self.contentHandler = contentHandler; - self.bestAttemptContent = [request.content mutableCopy]; - - NSMutableDictionary *userInfoDict = [self.bestAttemptContent.userInfo mutableCopy]; - userInfoDict[@"notifee_options"] = [NSMutableDictionary dictionary]; - userInfoDict[@"notifee_options"][@"title"] = @"Modified Title"; - - self.bestAttemptContent.userInfo = userInfoDict; +/** + * @description Firebase Message + * @link https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.basemessage.md#basemessage_interface + */ +const message: MulticastMessage = { + // ✅ We can continue using local/data-only notification for Android + // 👍 while triggering iOS remote notifications from `apns` + data: {notifee_options: JSON.stringify(notifeeOptions)}, + tokens: [], + android: { + priority: 'high', // Needed to trigger data-only notifications + }, + apns: { + payload: { + notifee_options: notifeeOptions, + aps: { + // Payloads coming from Admin SDK should specify params in camelCase. + // Payloads from REST API should specify in kebab-case + // see their respective reference documentation + alert: { + // 🚧 This is needed to trigger an alert/remote notification only for iOS + // 👍 but Android will continue using data-only notifications + title: 'ANY_DUMMY_STRING', // Or notifeeOptions.title :) + }, + 'mutableContent': 1, // Important, without this the extension won't fire + }, + }, + }, +}; - [NotifeeExtensionHelper populateNotificationContent:request - withContent: self.bestAttemptContent - withContentHandler:contentHandler]; +try { + admin.messaging().sendEachForMulticast(message) + res.status(200).end(); +} catch (e) { + res.status(400).end(); } ``` Please note, the `id` of the notification is the `request.identifier` and cannot be changed. For this reason, the `id` property in `notifee_options` should be excluded. -> if both `attachments` and `image` are present, `attachments` will take precedence over `image` +> If both `attachments` and `image` are present, `attachments` will take precedence over `image` ### Handling Events @@ -176,6 +219,8 @@ Currently, notifee supports the following events for remote notifications: - `ACTION_PRESSED` - `DISMISSED` +> On iOS, only notifications with a `categoryId` will receive a `DISMISSED` event. + To know identify when an interaction is from a remote notification, we can check if `notification.remote` is populated: ```jsx @@ -198,5 +243,3 @@ function App() { }, []); } ``` - -> On iOS, only notifications with a `categoryId` will receive a `DISMISSED` event. \ No newline at end of file From 480b3b08d51b1b11f548d34836f703de698acf2e Mon Sep 17 00:00:00 2001 From: Ovidiu Cristescu <55203625+LunatiqueCoder@users.noreply.github.com> Date: Fri, 11 Oct 2024 00:19:39 +0300 Subject: [PATCH 2/4] docs(ios): - Improve Remote Notification Support section --- .../docs/ios/remote-notification-support.md | 217 +++++++++++------- 1 file changed, 130 insertions(+), 87 deletions(-) diff --git a/docs-react-native/react-native/docs/ios/remote-notification-support.md b/docs-react-native/react-native/docs/ios/remote-notification-support.md index ad7450f1..f96db7e4 100644 --- a/docs-react-native/react-native/docs/ios/remote-notification-support.md +++ b/docs-react-native/react-native/docs/ios/remote-notification-support.md @@ -5,41 +5,21 @@ next: / previous: /react-native/docs/ios/permissions --- -It's possible to display a notification with Notifee features from outside the app using remote notifications (a.k.a push notifications) in two ways: - - using APNs keys - - using `notifee_options` with our notification service extension helper +> It is recommended to only use a notification service extension if you require an image or need to modify the contents of the notification before its displayed. -It is recommended to only use a notification service extension if you require an image or need to modify the contents of the notification before its displayed. +It's possible to display a notification with Notifee features from outside the app using remote notifications (a.k.a push notifications) by using `notifee_options` in APNs keys with our notification service extension helper. -### Using APNs keys +Adding a custom key `notifee_options` in the message payload enables Notifee to modify the notification before it is finally displayed to the end user. You can also change it as you please during this time. -Notification messages sent through APNs follow the APNs payload format which allows us to be able to specify a category or a custom sound with no extra configuration on the client: +> ⭐️ In order to bring the iOS experience closer to the Android one, you can still send **data-only/local/background** notifications for Android while using **remote/alert** notifications for iOS [by configuring the right payload.](#configure-the-payload) -```json -// FCM -{ - notification: { - title: 'A notification title!', - body: 'A notification body', - }, - apns: { - payload: { - aps: { - category: 'post', // A category that's already been created by your app - sound: 'media/kick.wav', // A local sound file you have inside your app's bundle - ... // any other properties - }, - }, - }, - ... -}; -``` - -### Using `notifee_options` +To get started, you will need to implement a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) for your iOS app, the following steps will guide you through how to set it up. -By adding a custom key `notifee_options` in the message payload, the notification will be modified by Notifee before it is finally displayed to the end user. +### Expo -To get started, you will need to implement a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) for your iOS app, the following steps will guide you through how to set it up. +You can jump straght to [configuring the payload](#configure-the-payload) if you use Expo with one of the community plugins: +- https://github.com/LunatiqueCoder/expo-notifee-remote-plugin +- https://github.com/evennit/notifee-expo-plugin ## Add the notification service extension @@ -48,6 +28,7 @@ To get started, you will need to implement a [Notification Service Extension](ht * Add a product name (use `NotifeeNotificationService` to follow along) and click Finish * Make sure that the **deployment target** of your newly added extension (e.g. `NotifeeNotificationService`) matches the **deployment target** of your app. You can check it by selecting you app's target -> `Build Settings` -> `Deployment` + ## Add target to the Podfile @@ -64,7 +45,7 @@ target 'NotifeeNotificationService' do end ``` - +* Assuming you are using `react-native-firebase`, you'll also have to add `use_frameworks!` inside the target above as [you did when you followed their docs](https://rnfirebase.io/#altering-cocoapods-to-use-frameworks). * Install or update your pods using pod install from the ios folder `pod install --repo-update` @@ -95,79 +76,141 @@ At this point everything should still be running normally. This is the final ste ``` -Before, moving to the next step, run the app and check it builds successfully – make sure you have the correct target selected. +## Mutate the content with Notifee: +> 🔗 [Apple Docs: Modifying content in newly delivered notifications](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications#Implement-your-extensions-handler-methods) -## Edit the payload -Now everything is setup in your app, you can alter your notification payload in two ways: +#### Objective C: -1. Update the message payload, sent via your backend -2. In a Notification Service Extension in your app when a device receives a remote message +In your `NotifeeNotificationService.m` file you should have method `didReceiveNotificationRequest` where we are calling `NotifeeExtensionHelper`. Now you can modify +`bestAttemptContent` before you send it to `NotifeeExtensionHelper`: -> Make sure that you will set `mutable-content: 1` (mutableContent if you are using firebase admin sdk) when sending notification otherwise Notification Service Extension will NOT be triggered +```objectivec +- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { + self.contentHandler = contentHandler; + self.bestAttemptContent = [request.content mutableCopy]; + + // You can also modify the payload as you please here. + // You have around 30 seconds + + // Notifee will mutate the notification according to notifee_options + [NotifeeExtensionHelper populateNotificationContent:request + withContent: self.bestAttemptContent + withContentHandler:contentHandler]; +} +``` -> Make sure that you will set `content-available: 1` (contentAvailable if you are using firebase admin sdk) if you want to receive notification when your app is in foreground +#### Swift: +In your `NotifeeNotificationService.swift` file, use the `didReceive(_:withContentHandler:)` method to enable the `NotifeeExtensionHelper`. +```swift +override func didReceive(_ request: UNNotificationRequest, + withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) { + self.contentHandler = contentHandler + self.bestAttempt = (request.content.mutableCopy() as? UNMutableNotificationContent) -### 1. Update the message payload, sent via your backend + // Here you can also modify the content of the notification as you please here. + // You have around 30 seconds -```json -// FCM -{ - notification: { - title: 'A notification title!', - body: 'A notification body', + + // Notifee will mutate the notification according to notifee_options + NotifeeExtensionHelper.populateNotificationContent(request, + with: self.bestAttempt!, + withContentHandler: contentHandler) +} +``` + +
+ +Before moving to the next step, run the app and check it builds successfully – make sure you have the correct target selected. + +## Configure the payload +> Make sure that you will set `mutable-content: 1` (mutableContent if you are using firebase admin sdk) when sending notification otherwise Notification Service Extension will NOT be triggered +> +> 🔗 [**Apple docs:** Configure-the-payload-for-the-remote-notification](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications#Configure-the-payload-for-the-remote-notification) + +### Here's an example of a payload sent from the backend with Firebase Admin Node.js SDK + +```ts + +import type {Notification} from '@notifee/react-native/src/types/Notification'; +import {AndroidImportance} from '@notifee/react-native/src/types/NotificationAndroid'; +import {MulticastMessage} from 'firebase-admin/lib/messaging/messaging-api'; +import admin from '../src/firebase-admin'; + +/** + * @link https://notifee.app/react-native/reference/notification + */ +const notifeeOptions: Notification = { + title: 'Title', + subtitle: 'Subtitle', + body: 'Main body content of the notification', + image: 'https://placeimg.com/640/480/any', // URL to pointing to a remote image + android: { + channelId: 'default', + importance: AndroidImportance.HIGH, + lightUpScreen: true, + pressAction: { + id: 'default', }, - apns: { - payload: { - aps: { - // Payloads coming from Admin SDK should specify params in camelCase. - // Payloads from REST API should specify in kebab-case - // see their respective reference documentation - 'contentAvailable': 1, // Important, to receive `onMessage` event in the foreground when message is incoming - 'mutableContent': 1, // Important, without this the extension won't fire - }, - notifee_options: { - image: 'https://placeimg.com/640/480/any', // URL to pointing to a remote image - ios: { - sound: 'media/kick.wav', // A local sound file you have inside your app's bundle - foregroundPresentationOptions: {alert: true, badge: true, sound: true, banner: true, list: true}, - categoryId: 'post', // A category that's already been created by your app - attachments: [{url: 'https://placeimg.com/640/480/any', thumbnailHidden: true}] // array of attachments of type `IOSNotificationAttachment` - ... // any other api properties for NotificationIOS - }, - ... // any other api properties for Notification, excluding `id` - }, - }, + sound: 'default', + }, + ios: { + sound: 'media/kick.wav', // A local sound file you have inside your app's bundle + categoryId: 'post', // A category that's already been created by your app + attachments: [{url: 'https://placeimg.com/640/480/any', thumbnailHidden: true}] // array of attachments of type `IOSNotificationAttachment` + // 🚧 Adding `foregroundPresentationOptions` controls how to + // 👇 behave when app is UP AND RUNNING, not terminated, AND not in background! + foregroundPresentationOptions: { + badge: true, + banner: true, + list: true, + sound: true, }, - ... + }, }; -``` -### 2. In a Notification Service Extension in your app when a device receives a remote message -In your NotifeeNotificationService.m file you should have method `didReceiveNotificationRequest` where we are calling `NotifeeExtensionHelper`. Now you can modify -`bestAttemptContent` before you send it to `NotifeeExtensionHelper`: - -```objectivec -- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { - self.contentHandler = contentHandler; - self.bestAttemptContent = [request.content mutableCopy]; - - NSMutableDictionary *userInfoDict = [self.bestAttemptContent.userInfo mutableCopy]; - userInfoDict[@"notifee_options"] = [NSMutableDictionary dictionary]; - userInfoDict[@"notifee_options"][@"title"] = @"Modified Title"; - - self.bestAttemptContent.userInfo = userInfoDict; +/** + * @description Firebase Message + * @link https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.basemessage.md#basemessage_interface + */ +const message: MulticastMessage = { + // ✅ We can continue using local/data-only notification for Android + // 👍 while triggering iOS remote notifications from `apns` + data: {notifee_options: JSON.stringify(notifeeOptions)}, + tokens: [], + android: { + priority: 'high', // Needed to trigger data-only notifications + }, + apns: { + payload: { + notifee_options: notifeeOptions, + aps: { + // Payloads coming from Admin SDK should specify params in camelCase. + // Payloads from REST API should specify in kebab-case + // see their respective reference documentation + alert: { + // 🚧 This is needed to trigger an alert/remote notification only for iOS + // 👍 but Android will continue using data-only notifications + title: 'ANY_DUMMY_STRING', // Or notifeeOptions.title :) + }, + 'mutableContent': 1, // Important, without this the extension won't fire + }, + }, + }, +}; - [NotifeeExtensionHelper populateNotificationContent:request - withContent: self.bestAttemptContent - withContentHandler:contentHandler]; +try { + admin.messaging().sendEachForMulticast(message) + res.status(200).end(); +} catch (e) { + res.status(400).end(); } ``` Please note, the `id` of the notification is the `request.identifier` and cannot be changed. For this reason, the `id` property in `notifee_options` should be excluded. -> if both `attachments` and `image` are present, `attachments` will take precedence over `image` +> If both `attachments` and `image` are present, `attachments` will take precedence over `image` ### Handling Events @@ -176,6 +219,8 @@ Currently, notifee supports the following events for remote notifications: - `ACTION_PRESSED` - `DISMISSED` +> On iOS, only notifications with a `categoryId` will receive a `DISMISSED` event. + To know identify when an interaction is from a remote notification, we can check if `notification.remote` is populated: ```jsx @@ -198,5 +243,3 @@ function App() { }, []); } ``` - -> On iOS, only notifications with a `categoryId` will receive a `DISMISSED` event. \ No newline at end of file From aa5336b32f9d8fd47d3cfa46e4e1650d8ce4937a Mon Sep 17 00:00:00 2001 From: Ovidiu Cristescu <55203625+LunatiqueCoder@users.noreply.github.com> Date: Fri, 11 Oct 2024 14:25:20 +0300 Subject: [PATCH 3/4] update community expo plugin links --- .../react-native/docs/ios/remote-notification-support.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-react-native/react-native/docs/ios/remote-notification-support.md b/docs-react-native/react-native/docs/ios/remote-notification-support.md index f96db7e4..f58972b0 100644 --- a/docs-react-native/react-native/docs/ios/remote-notification-support.md +++ b/docs-react-native/react-native/docs/ios/remote-notification-support.md @@ -18,7 +18,7 @@ To get started, you will need to implement a [Notification Service Extension](ht ### Expo You can jump straght to [configuring the payload](#configure-the-payload) if you use Expo with one of the community plugins: -- https://github.com/LunatiqueCoder/expo-notifee-remote-plugin +- https://github.com/LunatiqueCoder/expo-notifee-plugin - https://github.com/evennit/notifee-expo-plugin ## Add the notification service extension @@ -126,7 +126,7 @@ Before moving to the next step, run the app and check it builds successfully – ## Configure the payload > Make sure that you will set `mutable-content: 1` (mutableContent if you are using firebase admin sdk) when sending notification otherwise Notification Service Extension will NOT be triggered > -> 🔗 [**Apple docs:** Configure-the-payload-for-the-remote-notification](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications#Configure-the-payload-for-the-remote-notification) +> 🔗 [**Apple docs:** Configure-the-payload-for-thenotification](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications#Configure-the-payload-for-thenotification) ### Here's an example of a payload sent from the backend with Firebase Admin Node.js SDK From be32ba282e611da86ad4902989c04476ae8711a1 Mon Sep 17 00:00:00 2001 From: Ovidiu Cristescu <55203625+LunatiqueCoder@users.noreply.github.com> Date: Mon, 21 Oct 2024 01:56:32 +0300 Subject: [PATCH 4/4] docs(ios):#1120-resolve-comments --- .../docs/ios/remote-notification-support.md | 42 ++++++++++++------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/docs-react-native/react-native/docs/ios/remote-notification-support.md b/docs-react-native/react-native/docs/ios/remote-notification-support.md index f58972b0..861da896 100644 --- a/docs-react-native/react-native/docs/ios/remote-notification-support.md +++ b/docs-react-native/react-native/docs/ios/remote-notification-support.md @@ -5,19 +5,19 @@ next: / previous: /react-native/docs/ios/permissions --- -> It is recommended to only use a notification service extension if you require an image or need to modify the contents of the notification before its displayed. +> It is recommended to only use a notification service extension if you require an image or need to modify the contents of the notification before display. -It's possible to display a notification with Notifee features from outside the app using remote notifications (a.k.a push notifications) by using `notifee_options` in APNs keys with our notification service extension helper. +It is possible to display a notification with Notifee features from outside the app using remote notifications (a.k.a push notifications) by using the combination of a`notifee_options` section in your remote notification message (see below for example) and the Notifee notification service extension helper. -Adding a custom key `notifee_options` in the message payload enables Notifee to modify the notification before it is finally displayed to the end user. You can also change it as you please during this time. +Adding a custom key `notifee_options` in the remote notification message (as shown below) enables Notifee to modify the notification before it is finally displayed to the end user. If your use case requires it, you may also use custom native code as shown below to change the notification before display. -> ⭐️ In order to bring the iOS experience closer to the Android one, you can still send **data-only/local/background** notifications for Android while using **remote/alert** notifications for iOS [by configuring the right payload.](#configure-the-payload) +> ⭐️ In order to bring the iOS experience - where data-only messages are rarely delivered - closer to the Android one where data-only messages have high delivery rates, you may still send **data-only** notifications for Android while using messages with a **notification** payload for iOS [by configuring the right payload.](#configure-the-payload) To get started, you will need to implement a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) for your iOS app, the following steps will guide you through how to set it up. ### Expo -You can jump straght to [configuring the payload](#configure-the-payload) if you use Expo with one of the community plugins: +You can jump straight to [configuring the payload](#configure-the-payload) if you use Expo with one of the community plugins: - https://github.com/LunatiqueCoder/expo-notifee-plugin - https://github.com/evennit/notifee-expo-plugin @@ -26,6 +26,7 @@ You can jump straght to [configuring the payload](#configure-the-payload) if you * From Xcode top menu go to: File > New > Target... * A modal will present a list of possible targets, scroll down or use the filter to select Notification Service Extension. Press Next. * Add a product name (use `NotifeeNotificationService` to follow along) and click Finish +* You may use Swift or Objective-C where it says 'language' but be sure to follow the correct section below depending on your implementation language selection * Make sure that the **deployment target** of your newly added extension (e.g. `NotifeeNotificationService`) matches the **deployment target** of your app. You can check it by selecting you app's target -> `Build Settings` -> `Deployment` @@ -45,7 +46,7 @@ target 'NotifeeNotificationService' do end ``` -* Assuming you are using `react-native-firebase`, you'll also have to add `use_frameworks!` inside the target above as [you did when you followed their docs](https://rnfirebase.io/#altering-cocoapods-to-use-frameworks). +* Assuming you are using `react-native-firebase`, you must also add `use_frameworks!` inside the target above as [you did when you followed their docs](https://rnfirebase.io/#altering-cocoapods-to-use-frameworks). * Install or update your pods using pod install from the ios folder `pod install --repo-update` @@ -68,7 +69,7 @@ At this point everything should still be running normally. This is the final ste ```objectivec - // Modify the notification content here... - self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title]; - + - self.contentHandler(self.bestAttemptContent); + [NotifeeExtensionHelper populateNotificationContent:request withContent: self.bestAttemptContent @@ -79,12 +80,15 @@ At this point everything should still be running normally. This is the final ste ## Mutate the content with Notifee: > 🔗 [Apple Docs: Modifying content in newly delivered notifications](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications#Implement-your-extensions-handler-methods) -#### Objective C: +#### Objective-C: In your `NotifeeNotificationService.m` file you should have method `didReceiveNotificationRequest` where we are calling `NotifeeExtensionHelper`. Now you can modify `bestAttemptContent` before you send it to `NotifeeExtensionHelper`: ```objectivec +#import "NotificationService.h" +#import "NotifeeExtensionHelper.h" + - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { self.contentHandler = contentHandler; self.bestAttemptContent = [request.content mutableCopy]; @@ -99,10 +103,16 @@ In your `NotifeeNotificationService.m` file you should have method `didReceiveNo } ``` -#### Swift: +#### Swift: In your `NotifeeNotificationService.swift` file, use the `didReceive(_:withContentHandler:)` method to enable the `NotifeeExtensionHelper`. + ```swift +import UIKit +import RNNotifeeCore + +typealias ContentHandler = (UNNotificationContent) -> Void + override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) { self.contentHandler = contentHandler @@ -119,9 +129,9 @@ override func didReceive(_ request: UNNotificationRequest, } ``` -
+
-Before moving to the next step, run the app and check it builds successfully – make sure you have the correct target selected. +Before moving to the next step, run the app and check it builds successfully – make sure you have the correct target selected. ## Configure the payload > Make sure that you will set `mutable-content: 1` (mutableContent if you are using firebase admin sdk) when sending notification otherwise Notification Service Extension will NOT be triggered @@ -156,7 +166,7 @@ const notifeeOptions: Notification = { }, ios: { sound: 'media/kick.wav', // A local sound file you have inside your app's bundle - categoryId: 'post', // A category that's already been created by your app + categoryId: 'post', // Must be a category that has already been created by your app attachments: [{url: 'https://placeimg.com/640/480/any', thumbnailHidden: true}] // array of attachments of type `IOSNotificationAttachment` // 🚧 Adding `foregroundPresentationOptions` controls how to // 👇 behave when app is UP AND RUNNING, not terminated, AND not in background! @@ -170,7 +180,7 @@ const notifeeOptions: Notification = { }; -/** +/** * @description Firebase Message * @link https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.basemessage.md#basemessage_interface */ @@ -180,17 +190,17 @@ const message: MulticastMessage = { data: {notifee_options: JSON.stringify(notifeeOptions)}, tokens: [], android: { - priority: 'high', // Needed to trigger data-only notifications + priority: 'high', // Needed to achieve reliable delivery for data-only notifications on Android }, apns: { payload: { notifee_options: notifeeOptions, aps: { - // Payloads coming from Admin SDK should specify params in camelCase. + // Payloads coming from Admin SDK should specify params in camelCase. // Payloads from REST API should specify in kebab-case // see their respective reference documentation alert: { - // 🚧 This is needed to trigger an alert/remote notification only for iOS + // 🚧 This is needed to achieve reliable delivery only for iOS // 👍 but Android will continue using data-only notifications title: 'ANY_DUMMY_STRING', // Or notifeeOptions.title :) },