smartpush-sdk-ionic v1.8.5

Pluggable's Smartpush Plugin for Ionic apps

A Ionic plugin for Ionic apps.

Pre-conditions Integrate with FCM

Before using this plugin you should guarantee that your app already integrates with Firebase Cloud Messaging so that your app can receive push notifications.

1. Create a new Firebase project;

2. Android Setup - a configuration file must be downloaded and added to the project:

• On the Firebase console, add a new Android application and enter the projects details. The "Android package name" must match the local projects package name which can be found inside of the manifest tag within the /android/app/src/main/AndroidManifest.xml file within the project;
• Download the google-services.json file and place it at the module (app-level) directory of your app.

3. iOS Setup - to allow the iOS app to securely connect to the Firebase project, a configuration file must be downloaded and added to the project:

• On the Firebase console, add a new iOS application and enter your projects details. The "Apple bundle ID" must match your local project bundle ID. The bundle ID can be found within the "General" tab when opening the project with Xcode;
• Download the GoogleService-Info.plist file;
• Using Xcode, open the projects /ios/App/{projectName}.xcodeproj file (or /ios/App/{projectName}.xcworkspace if using Pods) and right click on the project name and "Add files" to the project. Select the downloaded GoogleService-Info.plist file from your computer, and ensure the Copy items if needed checkbox is enabled.

4. Still for iOS, you must enable the Push Notifications capability. See Setting Capabilities for instructions on how to enable the capability.

5. Additional iOS Setup - iOS requires further configuration before you can start receiving and sending messages through Firebase. For instance:

• You must upload your APNs authentication key to Firebase. If you don't already have an APNs authentication key, make sure to create one in the Apple Developer Member Center;
• Inside your project in the Firebase console, select the gear icon, select Project Settings, and then select the Cloud Messaging tab;
• In APNs authentication key under iOS app configuration, click the Upload button.
• Browse to the location where you saved your key, select it, and click Open. Add the key ID for the key (available in the Apple Developer Member Center;) and click Upload.
• For further notes, you can check React-Native iOS with Firebase Cloud Messaging, which is quite illustrative.

Cordova's Firebase plugin

If you don't want to implement FCM's logic natively, one possibility is to install Cordova's Firebase plugin by running:

npm install cordova-plugin-firebase-messaging
npx cap sync

The tutorial is quite easy to follow.

Ionic's Firebase plugin

If you want an Ionic plugin, one possible plugin is the @capacitor/push-notifications plugin. Even though it has some limitations, a tutorial is available in Ionic Docs. To do that, on the project's root:

1. Add the @capacitor/push-notifications plugin to the project (npm install @capacitor/push-notifications) followed by npx cap sync;

2. After enabling the Push Notifications capability in iOS, add the following to your app's AppDelegate.swift:

   func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
       NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)
   }
   
   func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
       NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
   }

3. On Android, see Set up a Firebase Cloud Messaging client app on Android for additional information.

Final Notes

NOTE 1: Android 13 requires a permission check in order to receive push notifications. You are required to call checkPermissions() and requestPermissions() accordingly, when targeting SDK 33.

NOTE 2: The FCM plugin (@capacitor/push-notifications) does not support iOS Silent Push (Remote Notifications). You must use native code solutions for handling these types of notifications in order to have full compatibility with Pluggable's Smartpush Plugin - see Pushing Background Updates to Your App.

NOTE 3: The FCM plugin (@capacitor/push-notifications) does support data-only notifications, but will NOT call pushNotificationReceived if the app has been killed. To handle this scenario, you will need to create a service that extends FirebaseMessagingService, see Handling FCM Messages.

NOTE 4: FCM via APNs does not work on iOS Simulators. To receive messages & notifications a real device is required. The same is recommended for Android.

Smartpush Usage

After configuring your app to integrate with FCM, you are ready to use this plugin to properly engage with your users. To install the plugin just:

1. First install the Smartpush Package by running in the root of the project:

   npm install smartpush-sdk-ionic
   npx cap sync

2. Go to /android/build.gradle and add the following line to the repositories:

   ...
   repositories {
       google()
       mavenCentral()
   }
   ...

3. Once the above steps have been completed, you need to update the project's PODs:

   # iOS apps
   cd ios/App
   pod install --repo-update

4. Note that for Android, to customize the used notification icon just add the desired icon in the Android's drawble folder and name it ic_push_app_icon. Otherwise, a default icon, not related to your app, will be used.

5. This library exposes two methods which can be imported and used like this in any .tsx file:

   ...
   import { Smartpush } from 'smartpush-sdk-ionic';
   ...

   // In background and foreground handlers that are listening for FCM notifications, add:
   const notificationChannelId = "notificationChannelId"
   const notificationChannelName = "notificationChannelName"
   const notifData = remoteMessage.data as {[key: string]: string}
   let res = await Smartpush.pluggableExecute({notificationChannelId: notificationChannelId, notificationChannelName: notificationChannelName, notificationData: notifData});
   print(res.uuid)
   
   // ...
   
   // To store clicked metrics, add:
   await Smartpush.pluggableStoreFeedback();

6. Considering that you use the @capacitor/push-notifications plugin:

   // Show the notification payload if the app is open on our device
   PushNotifications.addListener('pushNotificationReceived',
       (notification: PushNotificationSchema) => {
           alert('Push received: ' + JSON.stringify(notification));
           const notificationChannelId = "notificationChannelId"
           const notificationChannelName = "notificationChannelName"
           const notifData = notification as {[key: string]: string}
           let res = await Smartpush.pluggableExecute({notificationChannelId: notificationChannelId, notificationChannelName: notificationChannelName, notificationData: notifData});
           print(res.uuid)
       }
   );

   // What happens when user clicks in a received push
   PushNotifications.addListener('pushNotificationActionPerformed',
       (notification: ActionPerformed) => {
           alert('Push action performed: ' + JSON.stringify(notification));
           await Smartpush.pluggableStoreFeedback();
       }
   );

   // Get user token 
   PushNotifications.addListener('registration',
       (token: Token) => {
           alert('Push registration success, token: ' + token.value);
       }
   );
   
   // Some issue with our setup and push will not work
   PushNotifications.addListener('registrationError',
       (error: any) => {
           alert('Error on registration: ' + JSON.stringify(error));
       }
   );

   // Request push permissions
   // iOS will prompt user and return if they granted permission or not
   // Android will just grant without prompting
   PushNotifications.requestPermissions().then(result => {
       if (result.receive === 'granted') {
           // Register with Apple / Google to receive push via APNS/FCM
           PushNotifications.register();
       } else {
           // Show some error
       }
   });

NOTE: FCM via APNs does not work on iOS Simulators. To receive messages & notifications a real device is required. The same is recommended for Android.

More info

• For full compatibility, attention to the used versions of XCODE, SWIFT and COCOAPODS. Recommended versions are XCODE=15, SWIFT=5.9, and COCOAPODS=1.14.2.

• For more info visit https://pluggableai.xyz/ or give us feedback to info@pluggableai.xyz.

API

• pluggableExecute(...)
• pluggableStoreFeedback()

pluggableExecute(...)

pluggableExecute(options: { notificationChannelId: string; notificationChannelName: string; notificationData: object; }) => Promise<{ uuid: string; }>

Returns: Promise<{ uuid: string; }>

pluggableStoreFeedback()

pluggableStoreFeedback() => Promise<void>