Quickstart Guide (Discontinued)

🚧

Note

Please note that we have announced end of sale for Cordova SDK. It is no longer offered as a standard Webex Connect capability.

This Quickstart guide explains the necessary steps required to integrate the Cordova plugin into your Android app. It also provides the steps to set-up an app asset corresponding to your app on the Webex Connect platform.

Prerequisites

  1. npmand Node
  2. A Cordova App
  3. An Active Webex Connect account
  4. An Webex Connect App Asset
  5. Webex Connect Cordova Plugin

Android Specific

  1. Android Studio
  2. Android OS 4.4 to 9.0 (API-Level 19 to 28)
  3. Firebase Project
  4. HMS

iOS Specific

  1. Mac OS
  2. iOS 9 or higher
  3. Xcode 8 or higher
  4. Active Apple developer account
  5. APNS or Firebase Project

SDK Version vs OS Version

SDKSDK VersionMin Supported OSTLS Support
Cordova2.3.0 and higherEMUI versions 10.x and above
Cordova2.2.0
Cordova2.1.2 onwards.Android OS 4.4 to 9.0 (API-Level 19 to 28).
iOS 9 or higher.
Android OS version 4.4 & API level 19 (KitKat) does not support TLS version 1.2 by default.
iOS there is no issue for supporting TLS 1.2 support for min supported version is iOS 9 and higher.
till 2.1.1.Android OS 4.0 (API Level 15) and above.
iOS 10 or higher.
Android OS version 4.0 & API level 15 (Ice Cream Sandwich) till KitKat (4.4) version does not support TLS version 1.2 by default.
iOS there is no issue for supporting TLS 1.2 support for min supported version is iOS 10 and higher.

Coexistence of Cordova SDK with other Push Messaging SDKs

Webex Connect platform enables app developers to integrate Webex Connect Cordova SDK alongside other push SDKs. The developers having multiple push SDKs in their app will need to follow the following approach for SDK integration starting Cordova SDK v2.2.0.

  • Webex Connect messaging API v1 already supports a parameter, named icmessage to help identify whether the payload is to be processed using Webex Connect SDK
  • Developers will need to pass the payload to Webex Connect SDK when icmessage parameter is available. By default, Webex Connect SDK will not consume any payload unless specifically passed to it by the developer.
  • This gives the app developer an option to pass the payload to other SDKs depending on the source of the payload.
  • All DRs and RRs will be sent back to Webex Connect platform only in case the payload is passed to Webex Connect SDK.

Jetpack / AndroidX

This plugin requires modern Jetpack libraries (AndroidX). If the application includes plugins that are still on the old Android Support libraries, you will face build issues. The quickest way to work around the issue is to install cordova-plugin-androidx and cordova-plugin-androidx-adapter, which will automatically enable Jetpack and migrate plugins in the application:

cordova plugin add cordova-plugin-androidx-adapter cordova plugin add cordova-plugin-androidx

Add Webex Connect Cordova Plugin

Run the below command in your terminal to add the Webex Connect Cordova Plugin to your app project

$ cordova plugin add

eg: $ cordova plugin add IMIconnectPlugin

Project Set-Up

For iOS App Development

  1. Open the workspace file (../platforms/ios/MyApp.xcworkspace) in Xcode.
  2. After opening the workspace file, Make sure the MyApp project is selected in the left panel.
  3. Create APNS Certificate p12 file. Follow this link
  4. Enable push notifications:
    a. Click your project within the File Navigator.
    b. Click Targets > Select Application Target > Signing & Capabilities.
    c. Add Push Notifications Capability

  1. Add Required Background Modes
    a. Click your project within the File Navigator.
    b. Click Targets > Select Application Target > Signing & Capabilities.
    c. Add Background Modes Capability.
    d. Enable Remote notifications.
3024
  1. On the main window, select the Signing & Capabilities tab and provide the Bundle Identifier(you can change this as per your requirement) and Signing Details
3024
  1. In order to receive Rich Push Notifications, Press "(+)" icon which is available on the target section and add NotificationService Extension in order to receive Rich Push Notifications.
3064

  1. When adding Extension, you will notice a New Folder in your project hierarchy containing three new files NotificationService.h, NotificationService.m and Info.plist.
  2. Add IMIconnectNotificationServiceExtension.framework (available at plugin/src/ios/lib) manually in the new Folder.
  3. In Info.Plist of your new notificationextension Target , add App Transport Security Setting Dictionary with Allow Arbitrary Loads; Bool value YES by selecting +.
  4. In General Tab->Linked Frameworks and Libraries, set the status of IMIconnectNotificationServiceExtension.framework as optional.
  5. Create a Group Identifier. Refer create-an-app-group section in Quickstart Guide for more information
  6. Switch ON the AppGroups, then checkmark your group identifier in the capabilities tab. from main project target as well as from Extension Target.
3024

❗️

For Cordova Plugin version 2.0.0 or below:

Follow the steps in the given link if you are using Cordova plugin version 2.0.0 or below.

Once done, return to this page and jump to step no. 16

For version 2.1.0 and above, simply continue below

  1. Click the Build Phases tab and click the + button.
  2. Select the **New Run Script Phase" option.

  1. Copy-paste the contents of the strip-frameworks.sh, that is contained within plugin zip.
  2. Finally, connect the mobile (device) to your machine to see the connected device on the Scheme menu.
  3. Click the Run button from the same toolbar to the left of the Scheme to build, deploy, and execute the application on the connected device.

Now you can see your application is running on the device.

For Android App Development

  1. Configure Proguard Rules

Add the below rule in proguard-rules.pro file.

📘

If you use an obfuscation tool other than ProGuard, please refer to the tool providers documentation for configuring equivalent rules.

For FCM:

-dontwarn org.eclipse.jetty.** 
-dontwarn com.google.firebase.messaging.FirebaseMessaging 
-dontwarn javax.servlet.** 
-dontwarn org.slf4j.** 
  
# for sqlcipher 
-keep class net.sqlcipher.** { *; } 
-keep class net.sqlcipher.database.* { *; } 

# WorkManager 
-keep class * extends androidx.work.Worker 
-keep class * extends androidx.work.InputMerger 
-keep public class * extends androidx.work.ListenableWorker { 
  public <init>(...); 
} 
-keep class androidx.work.WorkerParameters
For HMS :

-dontwarn org.eclipse.jetty.** 
-dontwarn javax.servlet.** 
-dontwarn org.slf4j.** 
  
# for sqlcipher 
-keep class net.sqlcipher.** { *; } 
-keep class net.sqlcipher.database.* { *; } 

# WorkManager 
-keep class * extends androidx.work.Worker 
-keep class * extends androidx.work.InputMerger 
-keep public class * extends androidx.work.ListenableWorker { 
  public <init>(...); 
} 
-keep class androidx.work.WorkerParameters 
  
#Proguard rules for HMS 
-ignorewarnings 
-keepattributes *Annotation* 
-keepattributes Exceptions 
-keepattributes InnerClasses 
-keepattributes Signature 
-keepattributes SourceFile,LineNumberTable 
-keep class com.hianalytics.android.**{*;} 
-keep class com.huawei.updatesdk.**{*;} 
-keep class com.huawei.hms.**{*;}

Plugin Initialization

Add a reference to your google-services.json / agconnect-services.json file in the app's config.xml:

For FCM :

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

For HMS :

```xml <platform name="android">

... 
 <!--For HMS--> 
  <resource-file src="agconnect-services.json" target="app/agconnect-services.json" /> 
  ```</platform>

Initialize IMIconnectPlugin

Call startup when the device is ready:

IMIconnectPlugin.startupWithConfigOptions(function(status) { 
            //result will be Boolean value. 
            console.log("IMIconnectPlugin.startupWithConfigOptions(): " + result); 
        }, function(error) { 
            console.log('IMIconnectPlugin.startupWithConfigOptions() Failed :' + JSON.stringify(error)); 
        }, { 
            appId: "<APP_ID>", 
            clientKey: "<CLIENT_KEY>", 
            environment: "<SERVER_ENVIRONMENT>"
            serverDomain: "<SERVER_DOMAIN>", 
            groupIdentifier: "<IOS_GROUP_IDENTIFIER>",
            allowUnencryptedDatabaseFallback: "false"
        });

Alternatively, you can configure IMIconnect Plugin through config.xml:

<!-- imiconnect app credentials --> 
<preference name="imiconnect_app_id" value="<APP_ID>" /> 
<preference name="imiconnect_client_key" value="<CLIENT_KEY>" /> 
<!-- OPTIONAL Add the IMIconnect's server environment, by default is UK --> 
<preference name="imiconnect_environment" value="<SERVER_ENVIRONMENT>" /> 
<!-- OPTIONAL Add the server domain to override zero-rating domain --> 
<preference name="imiconnect_server_domain" value="<SERVER_DOMAIN>" />     
<!-- OPTIONAL allows creating a default SQLite database when SQLcipher fails. -->
<preference name="imiconnect_allow_unencrypted_database_fallback" value="<true/false>" />
<!-- OPTIONAL (iOS Only) Application Group Identifier -->
<preference name="imiconnect_group_identifier" value="<IOS_GROUP_IDENTIFIER>" />

and call startup when the device is ready.

IMIconnectPlugin.startup(function(result) { 
            //result will be Boolean value. 
            console.log("IMIconnectPlugin.startup(): " + result); 
        }, function(error) { 
            console.log('IMIconnectPlugin.startup() Failed :' + JSON.stringify(error)); 
        });

Code Integration

1. Register

In order to use the features provided by Webex Connect SDK, the app user must be registered with our platform. Register method creates a new profile of the user on our profile as part of the registration. If an existing user registers again, the profile creation step is omitted in our back-end.

To register a device with the platform, create an ICDeviceProfile instance and invoke the IMIconnect.register method.

A device profile must always have a unique device id and user-id, if you do not supply a user id then the platform will assign one for you. Typically you will want to supply your own user-id value that corresponds to a user within your backend systems.

var deviceProfile = new ICDeviceProfile(); 

            deviceProfile.setAppUserId("9999"); 

            deviceProfile.setDeviceId("PROVIDE UNIQUE DEVICE ID");      

            IMIconnectPlugin.register( 

                  function(result){ 

                        console.log(result); 

                  }, 

                  function(error){ 

                        console.log(error); 

                  },  

                  deviceProfile );

2. Connect to Webex Connect

To use In-App Messaging you must establish a connection with the Webex Connect platform. Invoke the connect method to establish a connection and allow messages to be received.

Once the RT feature is enabled in the app asset created on Webex Connect and user registration is done, the App Developer can establish a connection between the app and Webex Connect platform by calling the connect method appropriately. This enables the messages sent from Webex Connect to be received on the app. When the application is running in the background, SDK is disconnected from Webex Connect. While in the disconnected state, incoming In-App messages are not received, however when the application comes to foreground again, SDK will establish a connection with the Webex Connect platform and allow messages to be received.

❗️

NOTE

This method will throw an error when In-App Messaging is not enabled for the app or a device is not registered with the SDK.

IMIconnectPlugin.connect(
    function(result) {
        console.log(result);
    },
    function(error) {
        console.log(error);
    }
);

3. Receive Messages

Incoming Push and In-App messages are received by registering a MessageListener implementation with IMIconnectPlugin.

Implement your message listener as per the below code samples:

IMIconnectPlugin.messageListener(

    function(messages) {

        var text = "";
        for (var i = 0; i < messages.length; i++) {
            text += messages[i].getMessage() + "<br>";
        }

        console.log(text);

    });

4. Listen for connection status events

Events are raised by the SDK whenever the connection status has changed. To receive these events in your application; implement and register a connectionStatusChangedListener.

IMIconnectPlugin.connectionStatusChangedListener(
    function(result) {
        console.log(result);
    },
    function(error) {
        console.log(error);
    });

5. Create a Thread

All In-App Messages within Webex Connect are grouped by threads. In order to publish messages, you must first create an ICThread object.

When responding to an incoming message, you can obtain the ICThread directly from the incoming message.

var thread = new ICThread();
thread.setTitle("MyTitle");
thread.setCategory("MyCategory");
IMIconnectPlugin.createThread(function(thread) {
    window.alert(thread.getTitle());
}, function(error) {
    console.log(error);
}, thread);

6. Publish a Message

Invoke publishMessage to publish a message to Webex Connect.

📘

NOTE

An ICThread object is obtained by calling the createThread method or from a received incoming message.

var message = new ICMessage();
message.setMessage("Test Message");
message.setThread(thread);
IMIconnectPlugin.publishMessage(function(icMessage) {
    console.log(JSON.stringify(icMessage.toJSON()));
}, function(error) {
    console.log(error);
}, message);

7. Disconnect from Webex Connect

(Optional)
This method is used to disconnect from Webex Connect. Once disconnected, incoming In-App messages will not be received.

❗️

NOTE

This method throws an exception when In-App Messaging is not enabled for the app.

IMIconnectPlugin.disconnect(
    function(result) {
        console.log(result);
    },
    function(error) {
        console.log(error);
    }
);

What’s Next

Now that you have an app with basic In-App messaging and Push Notification capabilities, refer to the complete Webex Connect Cordova Plugin documentation to know about the advanced capabilities.