Mobile Messaging SDK plugin for Cordova

Mobile Messaging SDK is designed and developed to easily enable push notification channel in your mobile application. In almost no time of implementation you get push notification in your application and access to the features of Infobip IP Messaging Platform. The document describes library integration steps for your Cordova project.

• Requirements
• Quick start guide
• Initialization configuration

Requirements

• cordova 12.0.0 (sudo npm install -g cordova)
• npm (version 8.13.x or higher)
• node (version 16.13.0 or higher)

For iOS project:

• Xcode 16.x
• Cocoapods 1.14.x
• Minimum deployment target 15.0
• [email protected]
• Ruby (2.7.x - 3.1.x)

For Android project:

• Android Studio
• Supported API Levels: 22 ( Android 5.1 - Lollipop) - 35 (Android 15)
• [email protected]

For Huawei:

• Android Studio
• Installed AppGallery with HMS Core at device
• Supported API Levels: 22 ( Android 5.1 - Lollipop) - 31 (Android 12.0)

Quick start guide

This guide is designed to get you up and running with Mobile Messaging SDK plugin for Cordova:

1. Make sure to setup application at Infobip portal, if you haven't already.

2. Add MobileMessaging plugin to your project, run in terminal:

   $ cordova plugin add com-infobip-plugins-mobilemessaging --save

   You can add typings if you are using TypeScript in yours project

   npm install --save-dev @types/mobile-messaging-cordova

   expand to see Ionic code

   ionic cordova plugin add com-infobip-plugins-mobilemessaging --save
   npm install @awesome-cordova-plugins/mobile-messaging --save

3. Configure platforms

   1. iOS: Integrate Notification Service Extension into your app in order to obtain:
      • more accurate processing of messages and delivery stats
      • support of rich notifications on the lock screen
   2. Android:
      1. Get the Firebase configuration file (google-services.json) as described in Firebase documentation and put it to the root application folder.
      2. Add following to your config.xml

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

   Notice (when targeting Android 13):

   Starting from Android 13, Google requires to ask user for notification permission. Follow this guide to make a permission request.

4. Configure Huawei build

   1. Configure Huawei application

   2. Change plaform/android/build.gradle

          
          buildscript {
              repositories {
                  mavenCentral()
                  google()
                  maven { url 'https://developer.huawei.com/repo/' } // Added for Huawei support
              }
          
              dependencies {
                  ...
                  classpath 'com.huawei.agconnect:agcp:1.6.0.300' // Added for Huawei support
              }
          }
      
          allprojects {
              repositories {
                  mavenCentral()
                  google()
                  maven {url 'https://developer.huawei.com/repo/'} // Added for Huawei support
              }
              ...
          }
      

   3. Change plaform/android/app/build.gradle

          apply plugin: 'com.android.application'
          apply plugin: 'com.huawei.agconnect' // Added for Huawei support
          
          dependencies {
                 implementation 'com.huawei.hms:push:6.3.0.302' // Added for Huawei support
          }
      

   4. Sign your app to provide config for Generated Signing Certificate Fingerprint at previous step. You can change plaform/android/app/build.gradle or write sign config to build.json

         android {
      
             signingConfigs {
                 release {
                     storeFile file(<path to *.jks file>)
                     storePassword "<password>"
                     keyAlias "<alias>"
                     keyPassword "<password>"
                 }
             }
             buildTypes {
                 release {
                     signingConfig signingConfigs.release
                 }
                 debug {
                     signingConfig signingConfigs.release
                 }
             }
      
             ...
      

   5. Download agconnect-services.json from AppGallery Connect and copy it to platforms/android/app.

      a. Find your App from the list and click the link under Android App in the Mobile phone column.

      b. Go to Develop > Overview.

      c. In the App information area, Click agconnect-services.json to download the configuration file.

   6. Add Huawei App ID via plugin variable in config.xml :

         <plugin name="com-infobip-plugins-mobilemessaging" spec="...">
             <variable name="HUAWEI_SENDER_ID" value="Huawei App ID" />
         </plugin>

      You can take this value from agconnect-services.json.

   7. Remove, if following was added to config.xml

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

   8. Run cordova build android --hms to make build for HMS.

      Note that if you are developing / testing FCM and HMS at the same device then better to remove cache for installed app, remove app and after that install build with other push cloud.

5. Add code to your project to initialize the library after deviceready event with configuration options and library event listener:

   onDeviceReady: function () {
       ...
       MobileMessaging.init({
               applicationCode: '<your_application_code>',
               geofencingEnabled: '<true/false>',
               ios: {
                   notificationTypes: ['alert', 'badge', 'sound']
               },
               android: {
                   notificationIcon: <String; a resource name for a status bar icon (without extension), located in '/platforms/android/app/src/main/res/mipmap'>,
                   multipleNotifications: <Boolean; set to 'true' to enable multiple notifications>,
                   notificationAccentColor: <String; set to hex color value in format '#RRGGBB' or '#AARRGGBB'>
               }
           },
           function() {
               console.log(`Mobile Messaging SDK has started initialization process. Register for registrationUpdated event to know when it's ready to be used.`);
           },
           function(error) {
               console.log('Init error: ' + error.description);
           }
       );
   
       MobileMessaging.register('messageReceived', 
           function(message) {
               console.log('Message Received: ' + message.body);
           }
       );
   
       ...
   }

   expand to see Ionic code

   Add this code to app.module.ts::

   import { MobileMessaging } from '@ionic-native/mobile-messaging/ngx';
   
   ...
   
   @NgModule({
    ...
   
     providers: [
       ...
       MobileMessaging
       ...
     ]
     ...
   })
   export class AppModule { }

   Usage sample:

   import {Message, MobileMessaging, UserData} from '@ionic-native/mobile-messaging/ngx';
   
   ...
   
   @Component({
     selector: 'app-root',
     templateUrl: 'app.component.html',
     styleUrls: ['app.component.scss']
   })
   export class AppComponent {
     constructor(
       private platform: Platform,
       private splashScreen: SplashScreen,
       private statusBar: StatusBar,
       private mobileMessaging: MobileMessaging
     ) {
       this.initializeApp();
     }
   
   ...
   
     this.mobileMessaging.init({
       applicationCode: '<your_application_code>',
       ios: {
         notificationTypes: ['alert', 'badge', 'sound']
       },
       android: {
         notificationIcon: <String; a resource name for a status bar icon (without extension), located in '/platforms/android/app/src/main/res/mipmap'>,
         multipleNotifications: <Boolean; set to 'true' to enable multiple notifications>,
         notificationAccentColor: <String; set to hex color value in format '#RRGGBB' or '#AARRGGBB'>
      }}, 
       () => {},
       (err) => {
        ...
      });
    
      this.mobileMessaging.register('messageReceived', function (message: any) {
        ...
      });

Initialization configuration

Notice:

The callback function will be called after successful start of Mobile Messaging SDK initialization. When the callback is called, it does not mean that the Mobile Messaging SDK is fully initialized and no Mobile Messaging SDK methods should be called inside the callback. To know when the Mobile Messaging SDK is fully initialized, you should subscribe to the registrationUpdated event.

MobileMessaging.init({
        applicationCode: <String; Infobip Application Code from the Customer Portal obtained in step 2>,

        // General configuration
        inAppChatEnabled: <Boolean; set to true to enable in-app chat feature>, // optional
        fullFeaturedInAppsEnabled: <Boolean; set to true to enable full featured in-app messages>, // optional
        loggingEnabled: <Boolean; set to true to enable debug logging>, // optional
        userDataJwt: <String; JWT token for authorization of user data related operations>, // optional
        trustedDomains: <Array<String>; list of trusted domain strings for web views, e.g. ['example.com', 'trusted.org']>, // optional
        messageStorage: <Object; message storage implementation>, // optional
        defaultMessageStorage: <Boolean; set to 'true' to enable default message storage implementation>, // optional

        // iOS-specific configuration
        ios: {
            notificationTypes: <Array; values: 'alert', 'badge', 'sound'; notification types to indicate how the app should alert user when push message arrives>,
            forceCleanup: <Boolean; defines whether the SDK must be cleaned up on startup. Default: false>, // optional
            registeringForRemoteNotificationsDisabled: <Boolean; set to true to disable automatic registration for remote notifications. Default: false>, // optional
            overridingNotificationCenterDelegateDisabled: <Boolean; set to true to prevent SDK from overriding UNUserNotificationCenterDelegate. Default: false>, // optional
            unregisteringForRemoteNotificationsDisabled: <Boolean; set to true to prevent SDK from unregistering for remote notifications when stopping SDK or after depersonalization, useful when using MobileMessaging SDK with another push provider. Default: false>, // optional
            webViewSettings: { // optional; settings for web view configuration in in-app messages
                title: <String; custom title for the web view toolbar>,
                barTintColor: <String; hex color string for the toolbar background color>,
                titleColor: <String; hex color string for the toolbar title text color>,
                tintColor: <String; hex color string for the toolbar button color>
            }
        },

        // Android-specific configuration
        android: { // optional
            notificationIcon: <String; a resource name for a status bar icon (without extension), located in '/platforms/android/app/src/main/res/mipmap'>,
            notificationChannelId: <String; identifier for notification channel>, // optional
            notificationChannelName: <String; user visible name for notification channel>, // optional
            notificationSound: <String; a resource name for a notification sound (without extension), located in '/platforms/android/app/src/main/res/raw'>, // optional
            multipleNotifications: <Boolean; set to 'true' to enable multiple notifications>,
            notificationAccentColor: <String; set to hex color value in format '#RRGGBB' or '#AARRGGBB'>,
            withBannerForegroundNotificationsEnabled: <Boolean; set to true to always display Push notifications as Banner> // optional
        },

        // Interactive notifications
        notificationCategories: [ // optional
           {
               identifier: <String; a unique category string identifier>,
               actions: [
                   {
                       identifier: <String; a unique action identifier>,
                       title: <String; an action title, represents a notification action button label>,
                       foreground: <Boolean; to bring the app to foreground or leave it in background state (or not)>,
                       textInputPlaceholder: <String; custom input field placeholder>,
                       moRequired: <Boolean; to trigger MO message sending (or not)>,

                       // iOS only
                       authenticationRequired: <Boolean; to require device to be unlocked before performing (or not)>,
                       destructive: <Boolean; to be marked as destructive (or not)>,
                       textInputActionButtonTitle: <String; custom label for a sending button>,

                       // Android only
                       icon: <String; a resource name for a special action icon>
                   }
               ]
           }
        ],

        // Privacy settings
        privacySettings: { // optional
            userDataPersistingDisabled: <Boolean; set to true to disable persisting User Data locally. Default: false>,
            carrierInfoSendingDisabled: <Boolean; set to true to disable sending carrier information to server. Default: false>,
            systemInfoSendingDisabled: <Boolean; set to true to disable sending system information (OS version, device model, app version) to server. Default: false>
        }
    },
    function() {
        console.log(`Mobile Messaging SDK has started initialization process. Register for registrationUpdated event to know when it's ready to be used.`);
    },
    function(error) {
        console.log('Init error: ' + error.description);
    }
);

More details on SDK features and FAQ you can find on Wiki

NEXT STEPS: Users and installations

If you have any questions or suggestions, feel free to send an email to [email protected] or create an issue.