feat(firebase_messaging): roadmap rework (#4012)

Co-authored-by: ehesp <[email protected]>
Co-authored-by: Helena Ford <[email protected]>
Co-authored-by: Kirsty Williams <[email protected]>
Co-authored-by: Salakar <[email protected]>
Co-authored-by: Elliot Hesp <[email protected]>

Author: 4 people

.github/workflows/firebase_messaging.yaml

@@ -38,18 +38,24 @@ jobs:
           profile: Nexus 5X
           script: ./.github/workflows/scripts/drive-example.sh android
 
-  ios:
+  apple:
     runs-on: macos-latest
-    timeout-minutes: 30
+    timeout-minutes: 40
     steps:
       - uses: actions/checkout@v1
         with:
           fetch-depth: 0
       - name: "Install Flutter"
-        run: ./.github/workflows/scripts/install-flutter.sh stable
+        run: ./.github/workflows/scripts/install-flutter.sh dev
       - name: "Install Tools"
-        run: ./.github/workflows/scripts/install-tools.sh
-      - name: "Build Example"
+        run: |
+          ./.github/workflows/scripts/install-tools.sh
+          flutter config --enable-macos-desktop
+      - name: "Build iOS Example"
         run: ./.github/workflows/scripts/build-example.sh ios
-      - name: "Drive Example"
+      - name: "Drive iOS Example"
         run: ./.github/workflows/scripts/drive-example.sh ios
+      - name: "Build MacOS Example"
+        run: ./.github/workflows/scripts/build-example.sh macos
+      - name: "Drive MacOS Example"
+        run: ./.github/workflows/scripts/drive-example.sh macos

.github/workflows/scripts/build-example.sh

@@ -10,7 +10,7 @@ melos bootstrap
 if [ "$ACTION" == "android" ]
 then
   melos exec -c 1 --scope="$FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE" -- \
-    flutter build apk --debug --target="$TARGET_FILE"
+    flutter build apk --debug --target="$TARGET_FILE" --dart-define=CI=true
   MELOS_EXIT_CODE=$?
   pkill dart || true
   pkill java || true
@@ -21,7 +21,7 @@ fi
 if [ "$ACTION" == "ios" ]
 then
   melos exec -c 1 --scope="$FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE" -- \
-    flutter build ios --no-codesign --simulator --debug --target="$TARGET_FILE"
+    flutter build ios --no-codesign --simulator --debug --target="$TARGET_FILE" --dart-define=CI=true
   exit
 fi
 
@@ -31,6 +31,6 @@ then
   echo "TODO: Skipping macOS testing due to Flutter dev branch issue."
   exit
   melos exec -c 1 --scope="$FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE" -- \
-    flutter build macos --debug --target="$TARGET_FILE"
+    flutter build macos --debug --target="$TARGET_FILE" --dart-define=CI=true
   exit
 fi

.github/workflows/scripts/drive-example.sh

@@ -7,7 +7,7 @@ then
   # Sleep to allow emulator to settle.
   sleep 15
   melos exec -c 1 --fail-fast --scope="$FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE" --dir-exists=test_driver -- \
-    flutter drive --no-pub --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart
+    flutter drive --no-pub --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart --dart-define=CI=true
   exit
 fi
 
@@ -22,7 +22,7 @@ then
   # Uncomment following line to have simulator logs printed out for debugging purposes.
   # xcrun simctl spawn booted log stream --predicate 'eventMessage contains "flutter"' &
   melos exec -c 1 --fail-fast --scope="$FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE" --dir-exists=test_driver -- \
-    flutter drive -d \"$SIMULATOR\" --no-pub --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart
+    flutter drive -d \"$SIMULATOR\" --no-pub --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart --dart-define=CI=true
   MELOS_EXIT_CODE=$?
   xcrun simctl shutdown "$SIMULATOR"
   exit $MELOS_EXIT_CODE
@@ -34,7 +34,7 @@ then
   echo "TODO: Skipping macOS testing due to Flutter dev branch issue."
   exit
   melos exec -c 1 --fail-fast --scope="$FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE" --dir-exists=test_driver -- \
-    flutter drive -d macos --no-pub --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart
+    flutter drive -d macos --no-pub --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart --dart-define=CI=true
   exit
 fi
 
@@ -43,6 +43,6 @@ then
   melos bootstrap
   chromedriver --port=4444 &
   melos exec -c 1 --scope="$FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE" --dir-exists=web -- \
-    flutter drive --release --no-pub --verbose-system-logs --browser-name=chrome --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart
+    flutter drive --release --no-pub --verbose-system-logs --browser-name=chrome --target=./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart --dart-define=CI=true
   exit
 fi

.gitignore

@@ -2,6 +2,7 @@
 .atom/
 .idea/
 .vscode/*
+.melos_tool/*
 !.vscode/tasks.json
 !.vscode/settings.json
 

README.md

@@ -1,14 +1,18 @@
 ---
-title: iOS Messaging Integration
-sidebar_label: iOS Integration
-description: iOS requires additional configuration steps to be completed before you can receive messages.
+title: FCM via APNs Integration
+sidebar_label: Apple Integration
+description: iOS & macOS require additional configuration steps to be completed before you can receive messages.
 ---
 
-Integrating the Cloud Messaging plugin on iOS devices requires additional setup before your devices receive messages.
+:::caution
+This guide applies to both iOS & macOS Flutter apps, repeat each step for the platforms you require. E.g. if you support iOS & macOS then you will need to integrate twice, once per platform Xcode project.
+:::
+
+Integrating the Cloud Messaging plugin on iOS & macOS devices requires additional setup before your devices receive messages.
 There are also a number of prerequisites which are required to be able to enable messaging:
 
 - You must have an active [Apple Developer Account](https://developer.apple.com/membercenter/index.action).
-- You must have a physical iOS device to receive messages.
+- For iOS; you must have a physical iOS device to receive messages.
   - Firebase Cloud Messaging integrates with the [Apple Push Notification service (APNs)](https://developer.apple.com/notifications/),
     however APNs only works with real devices.
 
@@ -17,7 +21,7 @@ There are also a number of prerequisites which are required to be able to enable
 Before your application can start to receive messages, you must explicitly enable "Push Notifications" and "Background Modes"
 within Xcode.
 
-Open your project workspace file via Xcode (`/ios/Runner.xcworkspace`). Once open, follow the steps below:
+Open your project workspace file via Xcode (`/{ios|macos}/Runner.xcworkspace`). Once open, follow the steps below:
 
 1. Select your project.
 2. Select the project target.
@@ -38,7 +42,7 @@ Next the "Push Notifications" capability needs to be added to the project. This
 Once selected, the capability will be shown below the other enabled capabilities. If no option appears when searching, the
 capability may already be enabled.
 
-### Enable Background Modes
+### Enable Background Modes (iOS only)
 
 Next the "Background Modes" capability needs to be enabled, along with both the "Background fetch" and "Remote notifications" sub-modes.
 This can be added via the "Capability" option on the "Signing & Capabilities" tab:
@@ -55,7 +59,7 @@ Now ensure that both the "Background fetch" and the "Remote notifications" sub-m
 
 ![Xcode - Enabling Background Modes](https://images.prismic.io/invertase/3a618574-dd9f-4478-9f39-9834d142b2e5_xcode-background-modes-check.gif?auto=compress,format)
 
-## Linking APNs with FCM (iOS)
+## Linking APNs with FCM
 
 > Note: APNs is required for both `foreground` and `background` messaging to function correctly on iOS.
 
@@ -99,7 +103,7 @@ application that you're developing.
 On the Apple Developer portal:
 
 1. Click the "Identifiers" side menu item.
-2. Click the plus button to register a App Identifier. 
+2. Click the plus button to register a App Identifier.
 3. Select the "App IDs" option and click "Continue".
 4. Select the "App" type option and click "Continue".
 
@@ -127,7 +131,7 @@ A provisioning profile enables signed communicate between Apple and your applica
 real devices, a signed certificate ensures that the app being installed on a device is genuine and has the correct
 permissions enabled.
 
-On the "Profiles" menu item, register a new Profile. Select the "iOS App Development" checkbox and click "Continue".
+On the "Profiles" menu item, register a new Profile. Select the "iOS App Development" (or macOS) checkbox and click "Continue".
 
 If you followed [Step 2](#2-registering-an-app-identifier) correctly, your App Identifier will be available in the drop down
 provided:
@@ -146,15 +150,74 @@ real device (using Xcode). Back within Xcode, select your project target and sel
 If Xcode (via Preferences) is linked to your Apple Account, Xcode can automatically sync the profile created above. Otherwise,
 you must manually add the profile from the Apple Developer console:
 
-1. Select the project.
-2. Select the project target.
-3. Assign the provisioning profile.
+1. Select the project (usually called 'Runner') in the left hand side project navigator.
+2. Select the project target under the 'Targets' heading, usually called 'Runner'.
+3. Select the Signing & Capabilities tab.
+3. Assign the provisioning profile in the 'Signing' section.
 
 ![Xcode - Assign provisioning profile](ios-xcode-assign-provisioning-profile.png)
 
+## (Advanced, Optional) Allowing Notification Images
+
+> If you want to know more about the specifics of this setup read the [official Firebase docs](https://firebase.google.com/docs/cloud-messaging/ios/send-image).
+
+On Apple devices, in order for incoming FCM [Notifications](notifications.mdx) to display images from the FCM payload, you must add an additional notification
+service extension. This is not a required step.
+
+### Step 1 - Add a notification service extension
+
+- 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 `ImageNotification` to follow along) and click **Finish**.
+- Enable the scheme by clicking **Activate**.
+
+![Xcode - Add a notification service extension](ios-notification-images-step-1.gif)
+
+### Step 2 - Add target to the Podfile
+
+Ensure that your new extension has access to Firebase/Messaging pod by adding it in the Podfile:
+
+- From the Navigator open the Podfile: Pods > Podfile
+- Scroll down to the bottom of the file and add:
+```ruby
+target 'ImageNotification' do
+  pod 'Firebase/Messaging'
+end
+```
+
+- Install or update your pods using `pod install` from the `ios` and/or `macos` directory.
+
+![Xcode - Add target to the Podfile](ios-notification-images-step-2.gif)
+
+### Step 3 - Use the extension helper
+
+At this point everything should still be running normally. This is the final step which is invoking the extension helper.
+
+- From the navigator select your `ImageNotification` extension
+- Open the `NotificationService.m` file
+- At the top of the file import `FirebaseMessaging.h` right after the `NotificationService.h` as shown below:
+```diff
+#import "NotificationService.h"
++ #import "FirebaseMessaging.h"
+```
+- Replace everything from line 25 to 28 with the extension helper:
+```diff
+- // Modify the notification content here...
+- self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title];
+
+- self.contentHandler(self.bestAttemptContent);
++ [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent withContentHandler:contentHandler];
+```
+
+![Xcode - Use the extension helper](ios-notification-images-step-3.gif)
+
+### Step 4
+
+Your device can now display images in a notification by specifying the `imageUrl` option in your FCM payload. Keep in mind that a 300KB max image size is enforced by the device.
+
 ## Next steps
 
-Once the above has been completed, you're ready to get started receiving messages on your iOS device for both
+Once the above has been completed, you're ready to get started receiving messages on your iOS and/or macOS device for both
 testing and production.
 
-> Usage documentation will be available once the Firebase Firebase Cloud Messaging plugin update lands as part of the [FlutterFire roadmap](https://github.com/FirebaseExtended/flutterfire/issues/2582).
+View the [Usage documentation](usage.mdx) to get started.