Overview

Skill Level: Intermediate

To get started configuring basic mobile app messaging in Cordova projects for iOS and Android apps, create an example app in Cordova, add your platforms and the Cordova plug-in to the example app, and then configure and build your Android and iOS apps. After configuring basic mobile app messages, you can configure advanced mobile app messaging features.

WARNING: When IBM Mobile App Messaging stores data that you send, the data is not encrypted. IBM Mobile App Messaging recommends that you do not transmit sensitive information in inbox, inapp, and mobile app messages. We do not encrypt the data in our databases or log files, or when stored on the device. If you must transmit sensitive information, encrypt the data before sending it and decrypt the data in memory on the device.

Prerequisites

To get started, you need:

Step-by-step

  1. Download the Apache Cordova package.

    Download the Cordova package at https://cordova.apache.org/#download. Verify that you have the appropriate environment, as described in the prerequisites.

  2. Create a Cordova application. If you are adding the SDK to an existing app, go to step 4.

    Cordova creates an example app called com.app.id Example App. You must replace com.app.id with your Apple app ID. For example,

    $ cordova create destination_folder com.xtify.silverpop Example
    
  3. Change the project folder and add the iOS and Android platforms to the app.

    For example,

    $ cd destination_folder
    $ cordova platform add android@7.1.4 
    $ cordova platform add ios 
    
     
  4. Verify that the prerequisite Cordova plug-ins exist in your project, and if a plug-in does not exist, add the plug-in.

    Starting in Cordova SDK version 3.4.3 (and later), you are not required to add the google.playservices plugin before you install the IBM Mobile App Messaging SDK.

  5. Add the IBM Mobile App Messaging Cordova plug-ins.

    To use mobile app messaging with Cordova apps, add the following plug-ins:

    • Cordova plug-in for mobile app messaging in Cordova apps
    • Locations plug-in for geofences and beacons with Cordova apps 
    • Crosswalk-webview plug-in for videos with Cordova apps
    • Multidex plugin (if your supported platforms require it) to allow you to use more than 64k methods

    Add the Cordova plug-in

    Add the Cordova plug-in by using the syntax in the Cordova plug-in syntax examples, as shown below. Ensure that you replace path-to-mce-cordova-sdk with the path for the IBM Mobile App Messaging SDK.

    The following variables are required.

    • ANDROID_APPKEY – Specify the app key that was generated from Watson Campaign Automation. Do not change the app key after you publish your app.
    • IOS_DEV_APPKEY and IOS_PROD_APPKEY – Specify the development app keys and production app keys that were generated in IBM Watson Campaign Automation. Depending on how the app is compiled, the SDK can choose the correct app key to use. Do not change your app key after you publish your app.
    • CUSTOM_ACTIONS – CUSTOM_ACTIONS is a space-separated list of plug-in actions that your app should respond to. The default value is “none”. Cordova does not let you set this value to an empty string. For this reason, if you do not want to use inbox messages, set CUSTOM_ACTIONS to a dummy value. For example:
      CUSTOM_ACTIONS="dummyValue"
      

      Note: If you want to modify custom actions, you must first remove the Cordova plug-in by using the Cordova plug-in Remove command and then re-add the plug-in by using the original command.

      $ cordova plugin remove ./path-to-mce-cordova-sdk/plugins/com.xtify.mce.sdk
      

    The following variables are optional. If you do not include an optional variable in the command line, the default value is used.

    • AUTO_INITIALIZE – Tells the SDK to start immediately when the application is started. This is usually what you want, but sometimes it’s useful to hold off starting the SDK (with its associated requests for permissions) until after you have had a chance to notify or authenticate the user.
    • LOGLEVEL – Sets the loglevel for debugging output messages. The default value is “error”. For more information, see Configuring log level message types.
    • SERVER_URL – Sets the SERVER_URL for your pod. The default value is https://sdk.ibm.xtify.com. For information about SERVER_URLs for your pod, see Setting the baseURL.
    • INVALIDATE_EXISTING_USER – Sets the “non-sticky MUID” option. If set to “true”, new MUIDs are assigned to devices when apps are uninstalled and then reinstalled. The default value is “false”. For more information, see Assign new MUIDs to devices when reinstalling apps.
    • AUTO_REINITIALIZE – Sets the “Auto Reinitialize” option that determines the plug-in’s behavior when the GDPR state is “true”. The default value is “true”. For more information, see Re initializing the SDK after GDPR request for erasure.

       

      Cordova plug-in syntax example:

      $ cordova plugin add ./path-to-mce-cordova-sdk/plugins/com.xtify.mce.sdk
      --variable ANDROID_APPKEY=gcXXXX
      --variable CUSTOM_ACTIONS="openInboxMessage"
      --variable IOS_DEV_APPKEY=apXXXXXX
      --variable IOS_PROD_APPKEY=apXXXXX
      --variable SERVER_URL=https://sdkX.ibm.xtify.com
      --variable AUTO_INITIALIZE=true
      --variable LOGLEVEL=verbose
      --variable AUTO_INITIALIZE_LOCATION=true
      --variable INVALIDATE_EXISTING_USER=true --variable AUTO_REINITIALIZE=true
      --variable CHANNEL_NAME="The name of the channel as it appears in the Notifications system dialog. This is required for Android 8 and higher."
      --variable CHANNEL_DESCRIPTION="The description of the channel as it appears in the Notifications system dialog. This is required for Android 8 and higher."
      --variable CHANNEL_ID="The ID (string) used to identify notifications as being sent to the SDK. Only one ID may be used for all SDK messages. This is required for Android 8 and higher."

    Add support for FCM or GCM.

    Are you implementing a new project?
    IBM recommends that you use FCM because Google has deprecated GCM and will soon disable it entirely. 

    Do you have an existing project that uses GCM?
    IBM recommends that you migrate from GCM to FCM. For information, see Migrating from Google Cloud Messaging (GCM) to Firebase Cloud Messaging (FCM) to get your code running under FCM.

    Do not use both FCM and GCM plugins; they will conflict.

    For FCM Support:

    cordova plugin add ./path-to-mce-cordova-sdk/plugins/com.xtify.mce.sdk.fcm
     

    After adding the plugin, to enable FCM support, place your google-services.json file in Project’s main directory.

    For GCM, please contact Support.

    Add the Location plug-in

    If you want to use geofences or beacons with Cordova apps, add the location plug-in for Cordova. For more information, see Configuring location plug-ins for beacon and geofence integration with apps developed in Cordova.

    The following variables are optional. If you do not include optional variables in the command line, the default value is used.

    • SYNC_RADIUS – Sets the radius of the reference area for geofences. The default is 100000 m.
    • SYNC_INTERVAL – Sets the the time interval between reference area geofence and beacon synchronizations with the server. The default is 600 seconds.
    • AUTO_INITIALIZE_LOCATION – Starts location services and monitoring for locations. The default is “true”.

    Add geofence example:

    $ cordova plugin add ./path-to-mce-cordova-sdk/plugins/com.xtify.mce.sdk.location
     --variable SYNC_RADIUS=10000 --variable SYNC_INTERVAL=60
    

     

    Add beacon example: 

    $ cordova plugin add ./path-to-mce-cordova-sdk/plugins/com.xtify.mce.sdk.beacon
     --variable UUID=your_beacon_UUID 
    

    Add the Crosswalk-webview plug-in

    If you want to use video with your Cordova apps, add the crosswalk-webview plug-in.

    $ cordova plugin add cordova-plugin-crosswalk-webview
    

     

    Add the Multidex plug-in
    If you need to use multidex with your app, please use the Phonegap plugin

    $ cordova plugin add phonegap-plugin-multidex
    

     

  6. Prepare the project.

    1. Run the prepare command.
      $ cordova prepare
      
  7. Add push capabilities to your iOS project.

    1. Open the .xcworkspace file in platforms/ios/{project_name}.xcworkspace.
    2. Select your project in Xcode | Capabilities and verify that Push Notification is enabled (On).

    Note: If you do not set your team and provisioning profile, the app does not have permission to get the APNs deviceToken.

  8. Set up your Android project.

    Note: If you are migrating the Cordova build from an earlier release to one later than 3.5.0, you must make the changes described in Migrating the Android SDK to release 3.7.1.0.2 (or later).

    1. Edit the AndroidManifest.xml file.
      1. Verify that the <application> segment of your AndroidManifest.xml contains the following entry.
        android:name="com.ibm.mce.sdk.js.MceJsonApplication
        

        If <application> segment does not contain the entry, add the entry manually. For example,

        <application android:hardwareAccelerated="true"
        android:icon="@drawable/icon"
        android:label="@string/app_name"
        android:name="com.ibm.mce.sdk.js.MceJsonApplication"
        android:supportsRtl="true">
        
      2. If you want to use the drawable resource instead of the Cordova default mipmap, modify the <application> node of the AndroidManifest.xml file after you install the Cordova plug-in. For example,
        <application
        android:hardwareAccelerated="true"
        android:icon="@mipmap/icon" <--- change to "@drawable/icon" if desired
        android:label="@string/app_name"
        android:name="com.ibm.mce.sdk.js.MceJsonApplication"
        android:supportsRtl="true" />
        
    2. Ensure that you set the ANDROID_HOME variable. For example,
      export ANDROID_HOME=/Applications/android
      
  9. Test your Apache Cordova iOS and Android apps.

    1. Build and run your Android app and iOS app.

      $ cordova run android # build and run .apk on an android device
      $ cordova emulate android # build and run on an emulator
      
    2. Run the emulator for your sample apps.

    3. Ensure that the app registers and receives the userId. You can either check the console log or the Watson Campaign Automation console for the registered mobile user ID.

    4. Send notifications to the iOS and Android apps and confirm that the devices receive the notification.

Expected outcome

When the plug-in is installed and the config.xml file is filled out, the application registers with the push provider servers and the MCE servers automatically. You can start using the APIs that send bulk mobile app messages immediately with no changes only if you need to support the standard actions available.

If you would like to keep a copy of the user ID and channel ID in your own systems to send mobile app messages to specific users, you can get those values by asking MCEPlugin.getRegistrationDetails with a callback. The callback includes an object with user ID and channel ID keys. If the system did not register with the servers, you can instead use the MCEPlugin.setRegistrationCallback callback, which is called only once when the registration happens.

Next, you can configure advanced mobile app messaging features for your Cordova apps. For more information, see the Documentation.

Go Back to Mobile Application Messaging home page.

6 comments on"Getting Started with Mobile App Messaging in apps developed with Apache Cordova"

  1. How about windows project using Cordova?

  2. I’m having problems with basic registration on iOS. The device asks for permission to receive notifications, but it does not get registered on Watson console (at least that’s what I was told). What am I missing?

    cordova plugin add /Users/admin/mce-cordova-sdk/plugins/com.xtify.mce.sdk
    –variable ANDROID_APPKEY=$androidApiKey
    –variable ANDROID_SENDER_ID=$senderId
    –variable CUSTOM_ACTIONS=”openInboxMessage”
    –variable IOS_DEV_APPKEY=$iosDevKey
    –variable IOS_PROD_APPKEY=$iosProdKey
    –variable SERVER_URL=https://apiX.ibm.xtify.com/3.0
    –variable LOGLEVEL=verbose
    –variable AUTO_INITIALIZE_LOCATION=true –force
    –variable INVALIDATE_EXISTING_USER=true

    MceConfig.json (iOS)
    {
    “baseUrl”: “https://api.ibm.xtify.com/3.0/”,
    “appKey”: {
    “dev”:”DEV_KEY”,
    “prod”:”PROD_KEY”
    },
    “autoInitializeFlag”: true,
    “sessionTimeout”: 20,
    “metricTimeInterval”: 180,
    “loglevel”: “error”,
    “logfile”: false,
    “logIterations”: 1,
    “logIterationDurationInHours”: 0,
    “logBufferSize”: 10
    }

    • JoanGriffin April 04, 2018

      Hello,
      Why are you using a MceConfig.json? It shouldn’t be included for Cordova. Also, in your example, are you using literals or placehoders? thanks

      • Hi,

        yes, we are using mceconfig.json. I’ll remove it from our project per your recommendation. We are using variables to determine the proper appkey as we generate up to 6 distinct apps from a single source code (actually 3 apps but with versions for android/iOS)

        I’ll try a new build today. I’ll let you know how it goes.

        Thanks!

        Emerson

        PS:it took me sometime to respond as the project went through a freeze, so to speak. We should finish this implementation by this Friday (05/25), so we may expect to hear new from me right here in this page 🙂

        • PS:it took me sometime to respond as the project went through a freeze, so to speak. We should finish this implementation by this Friday (05/25), so YOU may expect to hear news from me right here in this page 🙂

  3. Oh, now I see why you asked about the placeholders. I’ve posted the wrong mceconfig.json file, but I’ll remove it anyway per your recommendation.

Join The Discussion

Your email address will not be published. Required fields are marked *