Cordova-plugin-smartpush NPM

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 already integrates with Firebase Cloud Messaging so that your app can receive push notifications.

Create a new Firebase project;

Install Cordova's Firebase plugin by running:

cordova plugin add cordova-plugin-firebase-messaging

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

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

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

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:

First install the Smartpush Package by running in the root of the project:
```
cordova plugin add cordova-plugin-smartpush
```
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.)
```
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.
Finally, this library exposes two mandatory methods, which can be imported and used in your .js files as demonstrated in the next lines.

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:

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

This should be called to handle notifications in background or foreground, as follows:

// Register background handler
cordova.plugins.firebase.messaging.onBackgroundMessage(function(payload) {
    cordova.plugins.SmartpushPlugin.pluggableExecute(payload, function(response){
        console.log("JS | SUCCESS pluggableExecute | " + JSON.stringify(response));
    }, function(error){
        console.log("JS | ERROR pluggableExecute | " + JSON.stringify(error));
    });
});

// ...

// Register foreground handler
cordova.plugins.firebase.messaging.onMessage(function(payload) {
    cordova.plugins.SmartpushPlugin.pluggableExecute(payload, 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:

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

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

You may want to send notifications to specific devices/users. For that, you need to know the FCM registration token associated with each device. To know that, you need to add the following methods:

// Get users FCM token 
cordova.plugins.firebase.messaging.getToken().then(function(token) {
    console.log("Got device token: ", token);
    // Save the token
    // saveTokenToDatabase(token);
});

// ...

// Registers callback to notify when FCM token is updated
cordova.plugins.firebase.messaging.onTokenRefresh(function() {
    console.log("Device token updated");
    // Save the token
    // saveTokenToDatabase(token);
});

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

const USER_API_NAME = "YOUR_API_USERNAME"
const USER_API_KEY = "YOUR_API_KEY"
const PROMOTIONS_NOTIFICATION_TOPIC = "some_topic"

cordova.plugins.SmartpushPlugin.pluggableSubscribeTopic(USER_API_NAME, USER_API_KEY, PROMOTIONS_NOTIFICATION_TOPIC, users_fcm_token, 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 topic. You should call the pluggableUnsubscribeTopic method to let the SDK unsubscribe the user from that topic. This returns 1, if success, otherwise an error message. For that, you must do as follows:

cordova.plugins.SmartpushPlugin.pluggableUnsubscribeTopic(USER_API_NAME, USER_API_KEY, PROMOTIONS_NOTIFICATION_TOPIC, users_fcm_token, 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 topics the user is currently subscribed to you should call the pluggableGetSubscribedTopics method. This returns an array of strings. For that, you must do as follows:

cordova.plugins.SmartpushPlugin.pluggableGetSubscribedTopics(USER_API_NAME, USER_API_KEY, users_fcm_token, function(response){
    console.log("JS | SUCCESS Topics | " + JSON.stringify(response));
}, function(error){
    console.log("JS | ERROR Topics | " + JSON.stringify(error));
});

Three additional methods are exposed by the library to handle internal permissions (you are still required to ask the user for PUSH NOTIFICATION permission) and can be used, if needed, as follows.

To ask for the OS permission, you can do as follows:

// Request all permissions
cordova.plugins.firebase.messaging.requestPermission({forceShow: false}).then(function() {
    console.log("Push messaging is allowed");
});

Finally, the three additional methods that allows you to internally enable/disable push notifications (without disabling the OS permission itself) are the 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:
```
cordova.plugins.SmartpushPlugin.pluggableEnableInternalPushPermission(function(response){
    //...
}, function(error){
    //...
});

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

cordova.plugins.SmartpushPlugin.pluggableGetPushPermissionState(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 info@pluggableai.xyz.

ecosystem:cordova cordova-android cordova-ios

@everything-registry/sub-chunk-1386

1 month ago

1 month ago

1 month ago

4 months ago

5 months ago

6 months ago

6 months ago