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

iOS Quickstart Guide

The IMIconnect iOS SDK provides a messaging framework that enables app developers to integrate IMIconnect’s In-App and Push messaging services within their mobile applications.

Optional monitoring of device attributes allows change events to be reported back to the IMIconnect platform and values stored against the customer’s profile. These events may then be used to enrich user engagement through the triggering of rules and flows to send messages that may be more relevant to the user.

This Quickstart guide explains all the necessary steps that are required to integrate the IMIconnect iOS SDK within an application.

Prerequisites

The minimum requirements to use the IMIconnect SDK are:

Component
Requirements

OS

iOS 8 or higher.

Software

  • Xcode 8.0 and above
  • IMIconnect iOS SDK

Accounts

Configuration Tasks

Complete the following tasks to use IMIconnect SDK for your Mobile Application:

  1. Project Setup
  2. Setup APNs
  3. Add a Mobile Application
  4. Code Integration.

Project Setup

This section provides the steps necessary for adding and configuring the IMIconnect SDK within your XCode project.

  1. From the IMIconnect Portal menu, go to Tools > Downloads to download the iOS SDK.
  2. Unzip the SDK and drag-drop the IMIconnectCoreSDK.framework file into your XCode project.
  3. Select Create groups and Copy if needed in the prompt that appears.
  4. Select your project within the navigator. Click the General tab and add the IMIconnectCoreSDK.framework to the Embedded Binaries section.
Embedded Binaries

Embedded Binaries

  1. Click the Build Settings tab and add the flag –ObjC to the Other Linker Flags setting.
  2. Click the Build Phases tab and click the + button.
  3. Select the **New Run Script Phase" option.
  4. Copy and paste the contents of the strip-frameworks.sh that is contained within the SDK zip.
Run Phase Script

Run Phase Script

  1. Add Custom iOS Target Properties to your project:
    a. Select your project within the Project Navigator.
    b. Click Info.
    c. Click the (+) that appears when you hover the mouse over any line within the list.
    d. Add the following keys:
    • Required Background Modes
      • App downloads content from the network
      • App downloads content in response to push notifications.
      • App registers for location updates

        From iOS 10 onwards, you must also add the following key and provide a relevant description:
        • Privacy - Bluetooth Peripheral Usage Description

Bluetooth Usage Description

Users will see the Bluetooth Usage Description only if you enable Bluetooth monitoring.

To use location services or geofences, add the following keys and provide relevant descriptions:

  • Privacy - Location Always and When In Use Usage Description
  • Privacy - Location Always Usage Description
  • Privacy - Location When In Use Usage Description

Location Services

To enable location services regardless of whether your app is in use, add the first two keys.
To enable location services only when your app is in use, add the 3rd key.

  1. Enable push notifications:
    a. Click your project within the File Navigator.
    b. Click Targets > Capabilities.
    c. Switch on the Push Notifications option.

Swift Project Setup

This section is only relevant to Swift enabled projects, skip this section if you do not use Swift.

Projects that use Swift require a bridging header to expose the SDK APIs to the Swift code.

  1. Click File > New.
  2. Within the Source section, select Header File and click Next.
Choose a Template

Choose a Template

  1. Name it as {Your project name}-Bridging-Header.h.
Save As Dialog

Save As Dialog

  1. Select your project within the File Explorer
  2. Select your app target in the Build Settings tab and search for Bridging Header.
  3. In the Swift Compiler – General, locate the Objective-C Bridging Header key and add the location of the bridging header file.
Swift Compiler - General

Swift Compiler - General

  1. Open your bridging header and add the following code:
#import "IMIconnectCoreSDK/IMIconnectCoreSDK.h"

The IMIconnect SDK APIs will now be accessible from your Swift code.

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.
iOS Certificates

iOS Certificates

  1. Select the Apple Push Notification service SSL (Sandbox & Production) option.
New Push Certificate

New Push Certificate

  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.
Keychain Access

Keychain Access

P12 File Export

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), 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 New App > Mobile / Web.
Configure New App

Configure New App

  1. Enter a name for your application.

  2. Hover over the iOS platform and click Configure.
    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.
Configure iOS Push Notifications

Configure iOS Push Notifications

  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.
    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. Create IMIconnectConfiguration.plist
b. Configure the App Delegate
c. Register a device
d. Receive messages
e. Connect to IMIconnect
f. Listen for connection status events
g. Fetch Topics
h. Subscribe to a Topic
i. Unsubscribe from a Topic
j. Create a Thread
k. Publish a Message
l. Disconnect from IMIconnect

Create IMIconnectConfiguration.plist

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>

Ensure you set the appId and clientKey values to those that you generated earlier in this guide.

Configure the App Delegate

The SDK provides the ICAppDelegate class which contains a lot of the boilerplate code that is required for a working SDK integration. It is highly recommended that you inherit from this class from your own app delegate, if this is not possible then you may instantiate an instance of the class and chain calls from your app delegate to the ICAppDelegate.

  1. Open your AppDelegate.h file.
  2. Change your AppDelegate class to inherit from ICAppDelegate.
@interface AppDelegate : ICAppDelegate //Inherit from ICAppDelegate

@end

When using inheritance, ensure that you call through to the super implementation if you override any of the AppDelegate methods. If you do not, the SDK may not function as intended!

If you do not wish to, or cannot, use inheritance:

  1. Create an instance of ICAppDelegate within your AppDelegate class.
  2. Invoke the corresponding ICAppDelegate methods from your AppDelegate methods as per the following list:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

- (void)applicationDidEnterBackground:(UIApplication *)application 

- (void)applicationWillEnterForeground:(UIApplication *)application

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^ (UIBackgroundFetchResult))completionHandler

-(void)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^ (UIBackgroundFetchResult))completionHandler

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error

//For iOS 8 & 9 Support

- (void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings

- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification (NSDictionary *)userInfo completionHandler:(void (^)(void))completionHandler

- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forLocalNotification (UILocalNotification *)notification completionHandler:(void (^)(void))completionHandler

- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification (NSDictionary *)userInfo withResponseInfo:(NSDictionary *)responseInfo completionHandler:(void (^)(void))completionHandler

- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forLocalNotification (UILocalNotification *)notification withResponseInfo:(NSDictionary *)responseInfo completionHandler:(void (^)(void))completionHandler

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo

When using call chaining you must do so for all methods list above. Failure to do so may prevent the SDK from functioning as intended!

The remainder of this guide assumes your AppDelegate inherits from ICAppDelegate.

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

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

if (![IMIconnect isRegistered])
{
  //Instantiate a device profile, this example uses a default device id implementation, but you may use an alternative.
  ICDeviceProfile *deviceProfile = [[ICDeviceProfile alloc] initWithDeviceId:[ICDeviceProfile defaultDeviceId] appUserId:"YOUR_USER_ID"];
  
  [IMIconnect registerWithDeviceProfile:deviceProfile completionHandler:^(NSDictionary *response, NSError *error)
    {
      if (error == nil)
      {
        //Device was registered successfully
      }
      else
      {
        //Device registration failed, query error for reason information
      }
    }];
}

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.

Receive messages

Incoming Push and In App messages are received by implementing the ICMessagingDelegate protocol.

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

#import "ICMessaging.h"    
@interface MyMessagingDelegate : NSObject <ICMessagingDelegate>
    
@end 
  
@implementation MyMessagingDelegate  

-(id)init
{
  if (self = [super init])
  {
    [ICMessaging shared].delegate = self;
  }
    
  return self;
}

- (void)didReceiveMessage:(ICMessage *)message 
{ 
	//Invoked as new messages are received  
}  

- (void)didChangeConnectionStatus:(ICConnectionStatus)connectionStatus 
{
	//Invoked when the status of the In App Messaging connection changes.
}   

@end

The remaining steps are only relevant if you wish to use In-App Messaging, otherwise, you may skip to here.

Connect to IMIconnect

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

NSError *error;

[[ICMessaging shared] connect:&error];

if(error) 
{
  NSLog(@"%@",error.localizedDescription);
}

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.

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 the didChangeConnectionStatus method of the ICMessagingDelegate protocol.

#import "ICMessaging.h"    
@interface MyMessagingDelegate : NSObject <ICMessagingDelegate>
    
@end 
  
@implementation MyMessagingDelegate  

- (void)didChangeConnectionStatus:(ICConnectionStatus)connectionStatus 
{
	//Invoked when the status of the In App Messaging connection changes.
}   

@end

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.

Topics can be configured by an Admin user within the IMIconnect portal.

[[ICMessaging shared] fetchTopics:offset completionHandler:^(NSArray *topics, BOOL hasMoreTopics, NSError *error){  
  if (error)  {    
    //Failed to fetch topics  
  }  
  else  {    
    //Topics fetched successfully  
  }
}
]; 

Subscribe to a topic

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

[[ICMessaging shared] subscribeTopic:topicId completionHandler:^(NSError *error){  
  if (error)  {    
    //Failed to subscribe to topic  
  }  
  else  {    
    //Topic subscription successful  
  } 
}
];

Unsubscribe from a topic

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

[[ICMessaging shared] unsubscribeTopic:topicId completionHandler:^(NSError *error){  
  if (error)  {    
    //Failed to unsubscribe from topic  
  }  
  else  {    
    //Unsubscribe from topic successful  
  }
}
]; 

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

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.

ICThread *newThread = [ICThread new];
newThread.title = @“This is a new thread”;

[[ICMessaging shared] createThread:newThread
                     completionHandler:^(ICThread *thread, NSError *error)
{
  if (thread == nil)
  {
    NSLog(@“Error when creating a thread”,error.description);
  }
  else
  {
    NSLog(@“A thread has been created with the threadId: %@”,thread.threadId);
  }
}];

Publish a message

Invoke publishMessage to publish a message to IMIconnect.

ICMessage * icMessage = [ICMessage new];
icMessage.message = @ "My message";
icMessage.thread = thread;

[[ICMessaging shared] publishMessage: icMessage
    completionHandler: ^ (NSError * error) 
{
  if (error) 
  {
    NSLog(@ "Publication failed. Reason: %@", error.localizedDescription);
  } 
  else 
  {
    NSLog(@ "Publication succeeded.");
  }
}];

Disconnect from IMIconnect

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

NSError * error;
[[ICMessaging shared] disconnect: & error];

if (error) 
{
  NSLog(@ "Disconnection failed. Reason: %@", error.localizedDescription);
} 
else 
{
  NSLog(@ "Disconnection succeeded.");
}

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

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

Add Dependencies

  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 the 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 Continue.
Register an App Group

Register an App Group

  1. Click 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.
Link Binary with Libraries

Link Binary with Libraries

  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

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