IMIconnect Developer Hub

Welcome to the IMIconnect Developer Hub. You'll find all the resources to help you get started with IMIconnect quickly. We are here to support you if you get stuck. Let's jump right in!

Get Started

Quickstart Guide

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

Prerequisites

Add IMIconnect Cordova Plugin

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

$ cordova plugin add <local plugin dir>

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 a p12 file. Follow this link
  4. After Creating the P12 file, in Application, switch on the PushNotifications from Capabilities tab on main window.
  1. Switch ON the Background Modes, and checkmark the 'Remote notifications' in the capabilities tab.
  1. On the main window, select General tab and provide the Bundle Identifier(you can change this as per your requirement) and Signing Details.
  1. Set the status of the following Frameworks as optional in Linked Frameworks and Libraries section in the same General tab:
    1. FileProvider.Framework
    2. IOSurface.framework
    3. UserNotificationUI.framework
    4. UserNotifications.framework
    5. IMIconnectNotificationServiceExtension.framework
  1. Remove IMIconnectNotificationServiceExtension.framework from Linked Frameworks and Libraries, and add it on Embedded Binaries
  2. In order to receive Rich Push Notifications, Press "(+)" icon which is available on target section and add NotificationService Extension in order to receive Rich Push Notifications.
  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.
    1. Add IMIconnectNotificationServiceExtension.framework (available at plugin/src/ios/lib) manually in the new Folder.
    2. In Info.Plist of your new notificationextension Target , add App Transport Security Setting Dictionary with Allow Arbitrary Loads; Bool value YES by selecting +.
  2. In General Tab->Linked Frameworks and Libraries, set the status of IMIconnectNotificationServiceExtension.framework as optional.
  3. Create a Group Identifier. Refer create-an-app-group section in Quickstart Guide for more information
  4. Switch ON the AppGroups, then checkmark your group identifier in the capabilities tab. from main project target as well as from Extension Target.

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. Within your Xcode project, create a new plist file named IMIconnectConfiguration.plist and copy the following snippet into the file.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>appId</key>
	<string>Your Application ID</string>
	<key>clientKey</key>
	<string>Your Client Key</string>
  <key>groupIdentifier</key>
  <string>Your Group Identifier</string>
</dict>
</plist>
  1. Start the SDK in your AppDelegate class by using the sample code below.

NOTE

Import IMIconnectPlugin in AppDelegate.m file by including: #import "IMIconnectPlugin.h"

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    self.viewController = [[MainViewController alloc] init];

    [ICMessaging shared].messageStore = [[ICDefaultMessageStore alloc] initWithPassword:@"testPassword"];

    IMIconnectPlugin *pushHandler = [self.viewController getCommandInstance:@"IMIconnectPlugin"];
    pushHandler.password = @"setYourPassword";
    
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

  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 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 the appId and clientKey in string.xml which is available in android/res/values/string.xml, as shown below
<string name="app_id">YOUR APPID</string>
 <string name="client_key">YOUR CLIENT KEY</string>
  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.

-dontwarn org.eclipse.jetty.**
-dontwarn com.google.firebase.messaging.FirebaseMessaging
-keep class net.sqlcipher.** { *; }
-keep class net.sqlcipher.database.* { *; }
  1. Now that the application is ready, create the .apk file to test the application by executing the following command.

$ cordova build android

Plugin Initialization

Android

The SDK must be initialized before attempting to use any of its features. The SDK initialization should be done from your Application.onCreate method. If your app does not have an Application class you should create one.

public class YOUR_APP_NAME extends IMIconnectApplication {
    @Override
    public void onCreate() {
        super.onCreate();  // Call to super.onCreate() will initialize the IMIconnect SDK , reads the configuration from app manifest
    }
   
    // Password to generate encryption key for secure preferences
    @Override
    protected String getPassword()
    {
        return "YOUR_PASSWORD";
    }
}

Add your application class in AndroidManifest.xml file

<application
   android:name="YOUR_APP_NAME"
   android:allowBackup="true"
   android:label="@string/app_name"
   android:theme="@style/AppTheme">
   <activity
       android:name="YOUR_ACTIVITY_NAME"
       android:label="@string/app_name">
       <intent-filter>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
        
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
       </intent-filter>
       
    </activity>

</application>

Code Integration

1. Register

In order to use the features provided by IMIconnect SDK, 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 a 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 IMIconnect

To use In-App Messaging you must establish a connection with the IMIconnect 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 IMIconnect and user registration is done, the App Developer can establish a connection between the app and IMIconnect platform by calling the connect method appropriately. This enables the messages sent from IMIconnect to be received on the app. When the application is running in the background, SDK is disconnected from IMIconnect. 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 IMIconnect 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 IMIconnect 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 IMIconnect.

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 IMIconnect

(Optional)
This method is used to disconnect from IMIconnect. 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 IMIconnect Cordova Plugin documentation to know about the advanced capabilities.

Cordova Plugin Documentation

Quickstart Guide


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.