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

Cordova iOS Setup

The quickstart guide contains a detailed step by step process of integrating the Cordova plugin in your iOS app. It also provides steps to configure an app asset corresponding to your app on IMIconnect platform.

Prerequisites

Component
Requirements

OS

iOS 8 or higher.

Software

  • Xcode 8.0 and above
  • IMIconnect iOS SDK

Accounts

Configuration Tasks

To use IMIconnect SDK for your Mobile Application,

  1. Cordova installation and iOS setup
  2. Setup APNs
  3. Add a Mobile Application
  4. Code Integration

Cordova Installation

  1. To setup the Cordova plugin in your machine, you are required to install npm and Node in your machine.
  2. Once you have npm installed, install the Cordova in your machine using the following command.
     $ npm install -g cordova
    
  3. Create a Cordova application by executing the command.
    $ cordova create myapp com.mycompany.myapp MyApp
    

In the command above, myApp is the directory name, MyApp is the application name and com.mycompany.myapp is the package name. For more details refer to this link.

Installing the Requirements for iOS

Xcode

  1. To continue with the application setup, install Xcode in your machine. If Xcode is not installed you can find the Xcode in two different ways.

    • From the App Store, available by searching for "Xcode" in the App Store application.
    • From Apple Developer Downloads, which requires registration as an Apple Developer.
  2. Once Xcode is installed, several command-line tools need to be enabled for Cordova to run. From the command line, run:

          $ xcode-select --install
    

Deployment Tools

The ios-deploy tools allow you to launch iOS apps from an iOS device. On the command-line, execute the following command to install ios-deploy.

   $ npm install -g ios-deploy

iOS Installation for Cordova

Add pinned version of the iOS platform and save the downloaded version to config.xml & package.json

$ cordova platform add ios

Download Cordova SDK

  1. Login to the IMIconnect platform with the URL provided to you.
  2. On the left menu, click TOOLS and select Downloads.
    The SDK Download page is displayed as shown below.
Tools - Download SDK

Tools - Download SDK

  1. Under DOWNLOAD CORE SDK tile, click the Cordova icon as shown below to download the Cordova SDK
Cordova SDK Download

Cordova SDK Download

Adding plug-in

  1. To add custom plug-in to the application; navigate to the cordova application folder(myApp) and executive the following command.
    $ cordova plugin add IMIconnectPlugin
    
    in the example above, IMIconnectPlugin is the plug-in** name.
  2. Use the following command to build the Cordova application.
    $ cordova build ios
    

Deploying to Simulator

To deploy your Cordova application in the iOS simulator

  1. Open the workspace file (../platforms/ios/MyApp.xcworkspace) in Xcode. or you can use the below command line to open the workspace file:
    $ open ./platforms/ios/MyApp.xcworkspace/
    
  2. After opening the workspace file, Make sure the MyApp project is selected in the left panel.
    Note: Refer Setup APNs to create p12 file using the same identifier.
    • After Creating the P12 file. In Application, switch on the PushNotifications from Capabilities tab on the main window.
    • Switch ON the Background Modes, and checkmark the 'Remote notifications' in the capabilities tab.
  3. On the main window, select General tab and provide the Bundle Identifier(you can change this as per your requirement) and Signing Details.
  4. Now give the following Framework status as optional in Linked Frameworks and Libraries section in the same General tab.
    • FileProvider.Framework
    • IOSurface.framework
    • UserNotificationUI.framework
    • UserNotifications.framework
    • IMIconnectNotificationServiceExtension.framework
  5. Remove IMIconnectNotificationServiceExtension.framework from Linked Frameworks and Libraries , and add it on Embedded Binaries
  6. In order to receive the notifications, enable the Bluetooth permission.
    Go to info tab and click the + icon anywhere on the displayed list. Enter the key as Privacy - Bluetooth Peripheral Usage Description and value as $(PRODUCT_NAME) Bluetooth Peripheral use.
  7. In order to receive Rich Push Notifications, add NotificationService Extension.
    a.Target on pressing "(+)" icon which is available on target section,
    b. Refer Add Notification service for adding extension Target.
  8. When adding Extension, you will notice a New Folder in your project hierarchy containing three new files NotificationService.h NotificationService.m and Info.plist**.
    • Add IMIconnectNotificationServiceExtension.framework manually in the new Folder, the file is available at plugin/src/ios/lib
    • In Info.Plist of your new notificationextension Target , add App Transport Security Setting Dictionary with Allow Arbitrary Loads; Bool value YES by selecting +.
  9. On the General Tab,->Linked Frameworks and Libraries, set "IMIconnectNotificationServiceExtension.framework" status as optional.
  10. Now create a Group Identifier, refer create-an-app-group section in Quickstart Guide for more information
  11. Switch ON the AppGroups, then checkmark your group identifier in the capabilities tab. from main project target, Extension Target as well.
  12. Finally, connect the mobile (device) to your machine to see the connected device on the Scheme menu.
  13. Click Run button from the same toolbar to the left of the Scheme to build, deploy, and executive the application on the connected device.
    Now you can see your application is running on the device.

iOS Local Setup

  1. Copy the following files to your project's plug-ins folder:
    AppDelegate+imiConnect.h
    AppDelegate+imiConnect.m
    IMIconnectPlugin.h
    MIconnectPlugin.m
    

Note:

Add other dependent frameworks files.

  1. Add a reference for this plugin to the plugins section in the config.xml file.
    <feature name="IMIconnectPlugin">
     <param name="ios-package" value="IMIconnectPlugin"/>
    </feature>
    

Setup APNs

This section will guide you through the configuration process for the Apple Push Notification service (APNs).

  1. Go to the Apple Developer Portal and login to your account.
  2. Proceed to Certificates, Identifiers & Profiles.
  3. Click Certificates -> All.
  4. Click the + button to add a new certificate.
  1. Select the Apple Push Notification service SSL (Sandbox & Production) option.
  1. Select your App ID from the drop-down list and click Continue.

Create Certificate Signing Request (CSR)

  1. Follow the on screen instructions to create a Certificate Signing Request.
  2. Click Continue.
  1. Click Choose File and select the certificate file that was created in the previous step.
  1. Click Generate.

Download, install & export the certificate


Once the APNs SSL certificate has been generated it must be downloaded, installed to your Keychain and exported as a .p12 file.

  1. Click Download to download the certificate.
  1. Open the certificate to install it to your Keychain.
  2. Within Keychain Access:
    • Select the login keychain and the category as My Certificates.
    • Locate and select the certificate.
    • Right-click and select Export <your certificate>.
    • Save the certificate as a .p12 file.

The exported .p12 file will be used later when configuring your app within IMIconnect.

Firebase Cloud Messaging

If you wish to use Firebase Cloud Messaging (FCM) please refer to the official FCM Guide and add GoogleService-Info.plist in your project.

Add a Mobile Application

The section guides you through the process of configuring your app within the IMIconnect portal.

  1. Login to your IMIconnect Portal using the URL provided to you when your tenant was created.
  2. Click Apps.
  3. Click CONFIGURE APP > MOBILE / WEB.
  1. Enter a name for your application and click NEXT.
  1. Select the Mobile platform and click NEXT.
  1. Select the iOS platform and click NEXT.
  2. The iOS platform specific features are displayed. Configure the options as per the table below:
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 app platforms. The settings you provide for one platform (e.g. iOS), also apply for all other platforms.

Transport protocols
Two transport protocols are available for establishing a connection with IMIconnect, Web Socket and MQTT. If connection fails on the primary protocol, it will fall back to the secondary protocol.

Security settings
Enable secured ports to ensure RTM connections are established over a secured protocol for better security.

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

Push messaging

If using APNs, select 'Apple Push Notification Service (APNs)' and configure the following:

  • Upload the APNs certificate generated in the previous section.
  • If the certificate is password protected, enter the password.
  • Select the Gateway (Production/Sandbox).

Set to Production when sending push to your production ready app. To target your development app set to Sandbox.

If using FCM, select 'Firebase Cloud Messaging (FCM)' and configure the following:

  • Enter the FCM API Key as generated in the preceding section.
  1. Click Save.
  2. Make a note of the Client Key that is displayed within the **Client Settings section. This key will be used while integrating the IMIconnect SDK within your application.
  3. Click Save.
  4. An overview screen appears with the newly created application profile and the corresponding App ID. Make a note of App Id for use during SDK integration.

Code Integration

Follow the steps below to integrate the IMIconnect SDK within your application:

a. Register a device
b. Receive messages
c. Connect to IMIconnect
d. Listen for connection status events
e. Fetch Topics
f. Subscribe to a Topic
g. Unsubscribe from a Topic
h. Create a Thread
i. Publish a Message
J. Disconnect from IMIconnect

a. Register a device


The user's device must be registered with the IMIconnect platform before other features can be used. 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.

The following snippet shows how to create and register a device profile.

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

Info:

In a real world scenario, you will typically want to register with IMIconnect after a user has successfully logged into your app.

If your solution uses provisioned customer profiles (a.k.a master profiles), you will need to call IMIconnect.updateDeviceProfileParam to link the device profile to the customer profile. You may do this after successful device registration.

See here for information on provisioning customer profiles.

b. Receive messages


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

The delegate also receives changes to the status of the In App messaging connection.

IMIconnectPlugin.messageListener(

    function(messages) {

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

        console.log(text);

    });

c. Connect to IMIconnect


To use In-App Messaging you must establish a connection with the IMIconnect platform by invoking the connect method.

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.

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

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

d. 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);
    });

e. Fetch Topics


IMIconnect supports Topic based messaging, use the fetchTopics method to retrieve a list of topics configured for your application. You can subscribe users, or publish messages to those topics.

Info:

Topics can be configured by an Admin in admin console of IMIconnect.

IMIconnectPlugin.fetchTopics(function(topics) {
    var text = "";
    for (var i = 0; i < topics.length; i++) {
        text += topics[i].getName() + "<br>";
    }
    window.alert(text)

}, function(error) {
    console.log(error);
}, {
    "offset": 0
});

f. Subscribe to a topic


Invoke the subscribe method to subscribe the current user to a topic.

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

g. Unsubscribe from a topic


Invoke the unsubscribeTopic method to unsubscribe the current user from a topic.

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

Invoke the subscribe method to subscribe the current user to a topic.

h. 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);

i. Publish a message


Invoke publishMessage to publish a message to IMIconnect.

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

j. Disconnect from IMIconnect


This method is used to disconnect from IMIconnect. Once disconnected, incoming In-App messages will not be received.

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

Conclusion

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

Rich Notification Support

Note:

This section is only required if you intend to use rich notifications.

Rich notifications allow media, such as large images, to be displayed within the notification centre.

Add dependancies

  1. Drag-drop the IMIconnectNotificationServiceExtension.framework file into your XCode project.
  2. Select Create groups and Copy if needed in the prompt that appears.
  3. Click your project within the navigator and select your App Target. Click the General tab and add the IMIconnectNotificationServiceExtension.framework to the Embedded Binaries section.
  4. Under the Capabilities tab, find and switch on "Keychain Sharing", and add a Keychain Group key (com.myappdomain.myappname). Use your application bundleIdentifier for Unique key.
  5. Replicate the same for the extension target. Ensure that the Keychain Group key is the same for both - the app and the extension.
Keychain Sharing

Keychain Sharing

Create an App Group

  1. From the Apple Developer Portal, click Certificates, Identifiers and Profiles.
  2. In the Identifiers section, select App Groups; click on the '+' button.
Add App Groups

Add App Groups

  1. Enter details in the fields - description of the group and unique identifier. Click on Continue.
Register an App Group

Register an App Group

  1. Click on Register and Done.
Confirm App Group

Confirm App Group

Create a Notification Service Extension

  1. Within XCode, click your project within the Project Navigator.
  2. Within the Targets section, click the '+' button.
Add Target

Add Target

  1. Within the Application Extension section, select Notification Service Extension and click Next.
Notification Service Extension

Notification Service Extension

  1. Enter a name and click Finish.
  2. Click Activate.
Activate Push Notification Service Extension

Activate Push Notification Service Extension

  1. You should now see a new folder in your project hierarchy containing three new files -
    NotificationService.h, NotificationService.m, and Info.plist.
Folder Hierarchy

Folder Hierarchy

  1. Click your project within the Project Navigator.
  2. Select your notification service extension target.
  3. Click the Capabilities tab.
  4. Switch on the App Group and click on the app group that you created earlier.

Repeat steps 9 and 10 for your main application target.

Select Notification Service Extension Target

Select Notification Service Extension Target

  1. Select the Build Phases tab for the Notification Service Extension and in the Link Binary with Libraries section, add IMIconnectNotificationServiceExtension.framework.
  1. Remove the default code that was generated for NotificationService, leave only the class definition.
  2. Change your NotificationService to inherit from ICNotificationService.
//Within NotificationService.h

#import <UserNotifications/UserNotifications.h>

#import <IMIconnectNotificationServiceExtension/IMIconnectNotificationServiceExtension.h>

@interface NotificationService : ICNotificationService

@end


//Within NotifcationService.m
#import "NotificationService.h"
  
@interface NotificationService ()


@end

@implementation NotificationService



@end
import UserNotifications

class NotificationService: ICNotificationService
{
    
}
  1. If you have added IMIconnectConfiguration.plist:
    a. Add a new key: groupIdentifier and add the group identifier of the project.
    b. Add this file to your Notification Service Extension target.
Add New Key

Add New Key

Add File to Notification Service Extension target

Add File to Notification Service Extension target

  1. If you are not using IMIconnectConfiguration.plist open NotificationService.m and override the getter to return your app group identifier.
#import "NotificationService.h"

@implementation NotificationService
- (NSString *)groupIdentifier
{
return @"<Your app group identifier>";
}

@end

Cordova iOS Setup


Suggested Edits are limited on API Reference Pages

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