Pluggable's Smartpush Plugin for Cordova apps

A Cordova plugin for Cordova apps.

Pre-conditions [Integrate with FCM]

Before using this plugin you should guarantee that your app integrates with Firebase Cloud Messaging. Unfortunately, there is no official support from Google to Cordova's Firebase. One possible plugin, Cloud Messaging, can be used even though it has a set of issues that require specific attention when implementing it. Nonetheless, the integration of Firebase in Cordova can be done as follows:

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 package name which can be found inside your app's config.xml file;
• Download the google-services.json file and place it into the root directory of your Cordova project;
• Add a new tag for the Android platform inside your app's config.xml file:

  ...
  <platform name="android">
      <resource-file src="google-services.json" target="app/google-services.json" />
  </platform>
  ...

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 or in your app's config.xml file;
• Download the GoogleService-Info.plist file and place it into the root directory of your Cordova project;
• Add a new tag for the iOS platform inside your app's config.xml file:

  ...
  <platform name="ios">
      <resource-file src="GoogleService-Info.plist" />
  </platform>
  ...

4. 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.

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.

Smartpush Usage

The Smartpush plugin for Cordova gives you a set of methods that you can use based on your needs.

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

cordova plugin add cordova-plugin-smartpush

2. For iOS, using Xcode, open the {projectName}.xcworkspace file, go to the Plugins folder and open the SmartpushPlugin.m file. There, at the top of the file, guarantee that you import your project's header (<projectName>-Swift.h), like:

#import <Cordova/CDV.h>
#import <HelloCordova-Swift.h> // <- Add your project's header (HelloCordova, p.e.)

3. 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.

4. Finally, this library exposes three mandatory methods, which can be imported and used in your .js files as demonstrated in the next lines.

• The pluggableInitialize method is used to initialize the Smartpush plugin:

let COMPANY_NAME = 'your_company_name';
let COMPANY_LICENSE = 'your_company_key';
let FCM_TOKEN = 'the_fcm_token';
let EXTERNAL_USER_ID = 'your_user_id';
let EXTERNAL_TOKEN_ID = 'the_id_of_the_device';
let EXTERNAL_USER_EMAIL = '[email protected]';
let PLUGGABLE_LOG = true;

cordova.plugins.SmartpushPlugin.pluggableInitialize(
    COMPANY_NAME, 
    COMPANY_LICENSE, 
    FCM_TOKEN, 
    EXTERNAL_USER_ID, 
    EXTERNAL_TOKEN_ID, 
    EXTERNAL_USER_EMAIL, 
    PLUGGABLE_LOG,
    function (response) {
        console.log("JS | SUCCESS pluggableInitialize | " + response);
    }, function(error){
        console.log("JS | ERROR pluggableInitialize | " + error);
});

• The pluggableExecute method is used to deliver the notification to the user. It autonomously executes the artificial intelligence models that deliveres the notification when the user is engaged:

let PLUGGABLE_LOG = true;

cordova.plugins.SmartpushPlugin.pluggableExecute(payload, PLUGGABLE_LOG, function(response){
    console.log("JS | SUCCESS pluggableExecute | " + JSON.stringify(response));
}, function(error){
    console.log("JS | ERROR pluggableExecute | " + JSON.stringify(error));
});

• The pluggableStoreFeedback method is used to create engagement metrics, being called every time a notification is clicked. In addition, all extras sent in this notification (for deep linking, for example) are availabe in the notificationData dictionary:

let PLUGGABLE_LOG = true;

cordova.plugins.SmartpushPlugin.pluggableStoreFeedback(notificationData, PLUGGABLE_LOG, function(response){
    console.log("JS | SUCCESS pluggableStoreFeedback | " + JSON.stringify(response));
}, function(error){
    console.log("JS | ERROR pluggableStoreFeedback | " + JSON.stringify(error));
});

5. Three additional methods are exposed by the library to handle tags (aka segments) subscriptions and can be used, if needed, as follows.

• You can subscribe your client's app to a particular tag - the client will then receive notifications that are sent to that particular tag. You should call the pluggableSubscribeTag method to let the SDK subscribe the user to that tag. This returns 1, if success, otherwise an error message. For that, you must do as follows:

let TAG_NAME = 'tag_name';
let TAG_VALUE = 'tag_value';
let EXTERNAL_USER_ID = 'your_user_id';
let EXTERNAL_TOKEN_ID = 'the_id_of_the_device';
let PLUGGABLE_LOG = true;

cordova.plugins.SmartpushPlugin.pluggableSubscribeTag(TAG_NAME, TAG_VALUE, EXTERNAL_USER_ID, EXTERNAL_TOKEN_ID, PLUGGABLE_LOG, function(response){
    console.log("JS | SUCCESS Subscribed | " + JSON.stringify(response));
}, function(error){
    console.log("JS | ERROR Subscribed | " + JSON.stringify(error));
});

• You can also unsubscribe your client's app from a particular tag. You should call the pluggableUnsubscribeTag method to let the SDK unsubscribe the user from that tag. This returns 1, if success, otherwise an error message. For that, you must do as follows:

let TAG_NAME = 'tag_name';
let EXTERNAL_USER_ID = 'your_user_id';
let EXTERNAL_TOKEN_ID = 'the_id_of_the_device';
let PLUGGABLE_LOG = true;

cordova.plugins.SmartpushPlugin.pluggableUnsubscribeTag(TAG_NAME, EXTERNAL_USER_ID, EXTERNAL_TOKEN_ID, PLUGGABLE_LOG, function(response){
    console.log("JS | SUCCESS Unsubscribed | " + JSON.stringify(response));
}, function(error){
    console.log("JS | ERROR Unsubscribed | " + JSON.stringify(error));
});

• To get the list of tags the user is currently subscribed to you should call the pluggableGetSubscribedTags method. This returns an array of strings. For that, you must do as follows:

let EXTERNAL_USER_ID = 'your_user_id';
let EXTERNAL_TOKEN_ID = 'the_id_of_the_device';
let PLUGGABLE_LOG = true;

cordova.plugins.SmartpushPlugin.pluggableGetSubscribedTags(EXTERNAL_USER_ID, EXTERNAL_TOKEN_ID, PLUGGABLE_LOG, function(response){
    console.log("JS | SUCCESS Tags | " + JSON.stringify(response));
}, function(error){
    console.log("JS | ERROR Tags | " + JSON.stringify(error));
});

6. Three additional methods are exposed by the library to handle internal permissions (you are still required to ask the user for PUSH NOTIFICATION permission). These methods allow you to internally enable/disable push notifications (without disabling the OS permission itself) and are called as pluggableEnableInternalPushPermission, pluggableDisableInternalPushPermission, and pluggableGetPushPermissionState. These methods return 0, if the push permissions is disabled, 1, if the push permission is enabled, and -1, meaning that the user did not grant the required OS permission for push notifications. You can use these as follows:

let PLUGGABLE_LOG = true;

cordova.plugins.SmartpushPlugin.pluggableEnableInternalPushPermission(PLUGGABLE_LOG, function(response){
    //...
}, function(error){
    //...
});

cordova.plugins.SmartpushPlugin.pluggableDisableInternalPushPermission(PLUGGABLE_LOG, function(response){
    //...
}, function(error){
    //...
});

cordova.plugins.SmartpushPlugin.pluggableGetPushPermissionState(PLUGGABLE_LOG, function(response){
    //...
}, function(error){
    //...
});

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

NOTE 2: If your platform app (iOS and/or Android) is unable to get the new plugin, then, between steps 1. and 2., you'll probably need to relink the platform data:

# Android apps
cordova platform remove android
cordova platform add android

# iOS apps
cordova platform remove ios
cordova platform add ios

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 [email protected].