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

The IMIconnect Android SDK provides a messaging framework for Android mobile app developers to integrate IMIconnect’s Real Time and Push messaging services into their mobile applications. The SDK also supports monitoring of device events. These events are reported back to IMIconnect and stored against the customer’s profile. These events are useful before sending messages to your customers.

This quickstart guide explains all the necessary steps that are required to integrate the IMIconnect Android SDK with your Android application.

Prerequisites

The minimum requirements to use the IMIconnect SDK are:

Component
Requirement

Android Operating System

Android OS 4.0 (API Level 15) and above.

Note: In Android OS 6.0, feature permissions are disabled by default. For example, access to camera, contacts, GPS etc. are disabled. Your application should enable the access to all such features.

Software

Account

  • A valid Google account.
  • An active account on IMIconnect platform. To create an IMIconnect account, send an email to support@imiconnect.com.

Mobile Application

Add a Mobile Application on IMIconnect.

Google Push Notification

A Google Cloud Messaging (FCM) service for Push Notification.

Configuration Tasks

Create a Google API project for Push

To create Google API project, follow the below steps:

  1. Go to Google Firebase Console.
  2. Click CREATE NEW PROJECT.
  1. Add the following in the screen that appears:
    • Project name: Enter a name for your project.
    • Country/region: Select the country name.
  2. Click CREATE PROJECT.
  1. When the project is created, a dashboard screen appears. Click Add Firebase to your Android app .
  1. Enter the following in the Add Firebase to your Android app screen:
    • Package name: Enter your Android package name.
    • Debug signing certificate SHA-1 (optional): This is an optional field. Enter the your SHA-1 key for Dynamic Links, Invites, and Google Sign-In support in Auth.
  1. Click ADD APP. A config file google-services.json gets downloaded.
  2. Click CONTINUE.
  3. Click FINISH.
  4. Copy file google-services.json into your project's module folder, typically app/.
    The configurations of build.gradle are explained in the next section.
  1. Go to Project settings and click CLOUD MESSAGING and make a note of the Server key and Sender ID.
    The Server key and Sender ID (project number) are used when configuring an application in IMIconnect and AndroidManifest.xml file.

Add a Mobile Application


  1. From the IMIconnect menu, click Apps. The Application screen appears.
  2. Click CONFIGURE APPS > MOBILE / WEB.
  1. Enter the application name and click NEXT.
  1. Select the Mobile platform and click NEXT.
  1. Select the Android platform and click NEXT.
  2. The Android platform specific features are displayed. Enable the feature and configure appropriately:
Feature
Settings

Real-time messaging

Configure the following:

  • Push messaging feature
  • RTM Transport and Security settings

Note: The RTM Transport and Security settings are common for all the configured platforms of the app. If you set to one platform, the same is applied to all other platforms also.

Transport protocols
Two transport protocols are available for establishing RTM connection with IMIconnect. They are Web Socket and MQTT. You can configure them as primary and secondary. In case the connection is not established on primary protocol, it will fall back to secondary protocol.

Security settings
Enable secured ports to establish RTM connection on the secured port for MQTT and WebSocket as an extra layer of security.

Enable RTM payload encryption to encrypt the RTM payload in transit.

Push messaging

Configure Google Cloud Messaging API key.

Two factor authentication

Select the Sender ID through which an OTP (One Time Password) is sent.

Device attributes

To monitor different attributes such as Time Zone, IMEI, RAM, Location and so on.

  1. Click SAVE.
  2. Make a note of the Client Key. This key will be used while integrating IMIconnect SDK in your application.
  3. Click SAVE.

An overview screen will appear with the newly created application profile and the corresponding App ID.

Make a note of the App ID. This id will be used while integrating IMIconnect SDK in your application.

Configure IMIconnect Android SDK

To configure IMIconnect Android SDK in your application, follow these steps:

The IMIconnect SDK supports Android version 4.0 and above.

  1. Download and install Android Studio.
  2. From your IMIconnect menu, go to Tools > DOWNLOADS and download Android SDK.
  3. Unzip the SDK. Open Android Studio and create a new project or open an existing project.
  4. Right-click on your project folder and click Open Module Settings.
  1. Click the + button on the top to add a new module. A New Module screen appears.
  1. Under More Modules section, select Import JAR or .AAR package and click Next.
  1. Import the IMIconnect Android SDK module IMIconnectCore.aar from the extracted zip.
  1. Once the module is imported, add the module to the app dependencies.

Integrate IMIconnect SDK in your App

Follow the below steps to integrate IMIconnect Android SDK in your application:

  a. Configure Android Gradle
  b. Configure Android Manifest
  c. Configure Proguard Rules
  d. Initialize the SDK
  e. Register a User
  f. Connect to IMIconnect
  g. Receive Message from IMIconnect
  h. Fetch Topics
  i. Subscribe a Topic
  j. Unsubscribe from a Topic
  k. Publish a Message
  l. Disconnect from IMIconnect

a. Configure Android Gradle


Add the below dependency in build.gradle.

implementation 'com.google.firebase:firebase-messaging:11.0.0'
implementation 'com.google.android.gms:play-services-location:11.0.0'
implementation 'org.eclipse.jetty:jetty-websocket:8.1.17.v20150415'
implementation 'com.firebase:firebase-jobdispatcher:0.8.5'

For database encryption, add the below dependency to build.gradle. Refer ICMessgeStore

api 'net.zetetic:android-database-sqlcipher:3.5.7@aar'

IMIconnect Android SDK uses Firebase Messaging 11.0.0. You should check the user device Google Play Services version before calling IMIconnect.register and prompt them to update their services if the version is less than 11.0.0.

b. Configure Android Manifest


The IMIconnect SDK uses AndroidManifest.xml for configuring IMIconnect services.

In your project, open AndroidManifest.xml file and replace the following values in the sample below with that of the values obtained during Application profile creation in the Add a Mobile Application section:

For the SDK to function correctly, you have to add the following permissions to your app's AndroidManifest.xml file. Some permission are optional and need to be included only if you use specific features, refer the comments below for further details.

<!-- PERMISSIONS -->
<!-- REQUIRED for connecting to IMIconnect -->
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

<!-- OPTIONAL add this permission if you need to get device and user details -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.GET_ACCOUNTS"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- REQUIRED to receive push notification -->
<permission
   android:name="YOUR_APP_PACKAGE_NAME.permission.C2D_MESSAGE"
   android:protectionLevel="signature"/>

<uses-permission android:name="YOUR_APP_PACKAGE_NAME.permission.C2D_MESSAGE"/>
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE"/>

<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>
           <!-- OPTIONAL add this scheme, host values for deep link action  -->
           <data
               android:host="command"
               android:scheme="@string/app_id"/>

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

   <!-- MANDATORY: Register your receiver which inherits from ICMessagingReceiver in order to receive incoming RTM and Push messages -->
   <receiver
       android:name="YOUR_MESSAGE_RECEIVER_NAME"
       android:enabled="true"
       android:exported="false"
       android:permission="com.imimobile.connect.core.permission.PUSH_PERMISSION">
       <intent-filter>
           <action android:name="com.google.android.c2dm.intent.REGISTRATION"/>
           <action android:name="com.imimobile.connect.core.rtmevent"/>
           <action android:name="com.imimobile.connect.core.notification.click"/>
           <action android:name="com.imimobile.connect.core.intent.notification.RECEIVE"/>
       </intent-filter>
   </receiver>

   <!-- Meta data needed for application identification -->
   <!-- Add the app id generated from IMIconnect -->
   <meta-data
       android:name="appid"
       android:value="@string/app_id"/>

   <!-- Add the client key generated from IMIconnect -->
   <meta-data
       android:name="clientkey"
       android:value="@string/client_key"/>

   <!-- Meta data needed for your Google FCM Project number -->
   <meta-data
       android:name="projectnumber"
       android:value="@string/project_number"/>
  
</application>

The below strings.xml file is referred by AndroidManifest.xml file.
Provide appropriate values for the below keys:

  • appid - The App ID that is generated by IMIconnect for your application.
  • client_key- The clientkey that is generated by IMIconnect for your application.
  • project_number - The FCM Project number that is generated in the Create a Google API Project section.
<resources>
    
    <string name="app_id">APP ID</string>
    <string name="client_key">Client key</string>
    <string name="project_number">FCM project number"</string>

</resources>

c. Configure Proguard Rules

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

-dontwarn org.eclipse.jetty.**

d. Initialize the SDK


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 MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Initialize the IMIconnect SDK , reads the configuration from app manifest
        try {
            IMIconnect.startup(this);
        } catch (ICException e) {
            e.printStackTrace();
        }
    }
}

e. Register a User


A user id is a customer id that is used in the app. To create a user id click here.

To register a user, invoke IMIconnect.register(String userId) method, passing the id of a user that is provisioned in IMIconnect.

IMIconnect.register(new ICDeviceProfile(ICDeviceProfile.getDefaultDeviceId()), new ICRegistrationCallback()
{
   @Override
   public void onRegistrationComplete(final Bundle bundle, final ICException exception)
   {
      if (exception != null) {
         Log.e("Registration", "Registration failed! Reason:" + exception.toString());
      } else {
         Log.d("Registration", "Registration succeeded!");
      }
   }
});
IMIconnect.register(new ICDeviceProfile(ICDeviceProfile.getDefaultDeviceId(),enteredUserId), new ICRegistrationCallback()
{
   @Override
   public void onRegistrationComplete(final Bundle bundle, final ICException exception)
   {
      if (exception != null) {
         Log.e("Registration", "Registration failed! Reason:" + exception.toString());
      } else {
         Log.d("Registration", "Registration succeeded!");
      }
   }
});

Registering Notification channel for Android O and above

Starting in Android 8.0 (API level 26), all notifications must be assigned to a channel else notifications will not appear.

By categorizing notifications into channels, users can disable specific notification channels for the app. Instead of disabling all the notifications users have the choice to control the visual and auditory options for each channel—all from the Android system settings. Users can also long-press a notification to change behaviors for the associated channel.

Sample code to register Notification channel:

public class MyApplication extends Application {
   @Override
   public void onCreate() {
      super.onCreate();
      // Initialize the IMIconnect SDK , reads the configuration from app manifest
      try {
         IMIconnect.startup(this);
      } catch (ICException e) {
         e.printStackTrace();
      }

      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
         // Provide your channel name & description that can be seen by User. 
         CharSequence name = getString(R.string.channel_name);
         String description = getString(R.string.channel_description);

         int importance = NotificationManager.IMPORTANCE_DEFAULT;
         NotificationChannel channel = new NotificationChannel(ICConstants.DEFAULT_CHANNEL_ID, name, importance);
         channel.setDescription(description);
         // Register the channel with the system
         NotificationManager notificationManager =
               (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
         notificationManager.createNotificationChannel(channel);
      }

   }
}

f. Connect to IMIconnect


To use Real Time Messaging you must establish a connection with IMIconnect platform. Invoke connect method to send (publish) and receive Real Time messages.

This method throws an exception when Real Time Messaging is not enabled for the app.

ICMessaging messaging = ICMessaging.getInstance();
      try
      {
         messaging.connect();
      }
      catch (ICException e)
      {
         Log.e("Connect", e.toString());
      }

g. Receive Message from IMIconnect


Incoming messages and connection events are raised through a receiver. To receive these events in your application, create a receiver class extending ICMessagingReceiver and override the methods to get messages and connection status.

public class MyReceiver extends ICMessagingReceiver {
    @Override
    protected void onMessageReceived(final Context context, final ICMessage message) {
        Log.d("MessageReceived", message.getMessage());
    }

    @Override
    protected void onConnectionStatusChanged(final Context context, final ICConnectionStatus status, final ICException e) {
        Log.d("ConnectionStatusChanged", "Status : " + status.toString());
        if (e != null) {
            Log.e("ConnectionStatusChanged", e.toString());
        }
    }
}

h. Fetch Topics


Incoming messages are received by subscribing to topics. Use the method fetchTopics to retrieve a list of topics to your application. You can subscribe or publish messages to those topics.

  • You application will receive messages that you have subscribed.
  • Topics can be configured by an Admin in admin console of IMIconnect.
  • The SDK automatically subscribes to a special "user" topic, to enable delivery of messages direct to a specific user.
ICMessaging.getInstance().fetchTopics(0, new ICFetchTopicsCallback()
{
   @Override
   public void onFetchTopicsComplete(final ICTopic[] topics, final boolean hasMoreData, final ICException exception)
   {
      if (exception != null)
      {
         Log.e("fetchTopics", "fetchTopics failed! Reason:" + exception.toString());
         return;
      }
      Log.e("fetchTopics", "fetchTopics success:");

   }
});

i. Subscribe a Topic


Invoke subscribe method to start receiving Real Time and Push messages for a specific topic.

 String topicId = "TEST";
 ICMessaging messaging = ICMessaging.getInstance();
 messaging.subscribeTopic(topicId, new ICSubscribeTopicCallback() {
     @Override
     public void onSubscribeTopicComplete(final String topicId, final ICException exception) {
         if (exception != null) {
             Log.e("SubscribeTopic", exception.toString());
         } else {
             Log.d("SubscribeTopic", "Subscribed Sucessfully");
         }
     }
 });

j. Unsubscribe from a Topic


Invoke unsubscribeTopic method to stop receiving Real Time or Push messages on a topic.

String topicId = "TEST";
ICMessaging messaging = ICMessaging.getInstance();
messaging.unsubscribeTopic(topicId, new ICUnsubscribeTopicCallback() {
    @Override
    public void onUnsubscribeTopicComplete(final String topicId, final ICException exception) {
        if (exception != null) {
            Log.e("UnsubscribeTopic", exception.toString());
        } else {
            Log.d("UnsubscribeTopic", "Unsubscribed Sucessfully");
        }
    }
});

k. Publish a Message


Invoke publishMessage to publish messages to IMIconnect on the topics that your application has write permission.

Note:

ICThread object comes from the createThread API or an incoming message.

ICMessage message = new ICMessage();
  message.setMessage("Test message");
  message.setThread(yourThreadObj);

  ICMessaging messaging = ICMessaging.getInstance();
  messaging.publishMessage(message, new ICPublishMessageCallback()
  {
   @Override
   public void onPublishMessageComplete(final ICMessage message, final ICException exception)
   {
    if (exception != null)
    {
     Log.e("PublishMessage", exception.toString());
    }
    else
    {
     Log.d("PublishMessage", "Published Sucessfully");
    }
   }
  });

l. Disconnect from IMIconnect


This method is used to disconnect from IMIconnect. Once disconnected, Real Time messages will not be published or received.

This method throws an exception when Real Time Messaging is not enabled for the app.

 ICMessaging messaging = ICMessaging.getInstance();
 try {
     messaging.disconnect();
 } catch (ICException e) {
     Log.e("Disconnect", e.toString());
 }

End Results

Now you have completed your app integration with IMIconnect. Once you build your app and distribute, your app users can send and receive messages.

Quickstart Guide