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:

Configuration 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. Click your project within the navigator. Click the General tab and add the IMIconnectCoreSDK.framework to the Embedded Binaries section.

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

9. Add Custom iOS Target Properties to your project:
   a. Click 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

📘

Optional

Users will only see the Bluetooth Usage Description 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

📘

To enable location services regardless of whether your app is in use, add the first two keys.

To enable location services only when you app is in use, add the 3rd key.

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

3. Name it as {Your project name}-Bridging-Header.h.

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

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

5. Select the Apple Push Notification service SSL (Sandbox & Production) option.

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

3. Click Choose File and select the certificate file that was created in the previous step.

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

2. Open the certificate to install it to your Keychain.
3. Within Keychain Access:
   • Select the login keychain and the category as My Certificates.
   • Locate and select the certificate.
   • Right-click and select Export .
   • 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.

4. Enter a name for your application and click NEXT.

4. Select the Mobile platform and click NEXT.

5. Select the iOS platform and click NEXT.
6. The iOS platform specific features are displayed. Configure the options as per the table below:

7. Click Save.
8. 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.
9. Click Save.
10. 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

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

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

c. Register a device

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

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.

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

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

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

g. 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  
  }
}
];

h. 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  
  } 
}
];

i. 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 the current user to a topic.

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

k. 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.");
  }
}];

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

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.

3. Enter details in the fields - description of the group and unique identifier. Click on Continue.

4. Click on Register and Done.

Create a Notification Service Extension

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

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

4. Enter a name and click Finish.
5. Click Activate.

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

7. Click your project within the Project Navigator.
8. Select your notification service extension target.
9. Click the Capabilities tab.
10. 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.

11. Select the Build Phases tab for the Notification Service Extension and in the Link Binary with Libraries section, add IMIconnectNotificationServiceExtension.framework.

12. Remove the default code that was generated for NotificationService, leave only the class definition.
13. Change your NotificationService to inherit from 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
{
    
}

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

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