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

TITLE:

Core

DESCRIPTION:

BODY:

This interface has two classes that handles the SDK initialization and registration. The classes are:

IMIconnect

This class contains the methods to initialize the SDK and register a user. When integrating the SDK into your app, it is mandatory to use this class to initialize the SDK. With exception to the Authentication module, it is also necessary to register a user before other features are used.

startup


This method is used to initialize the SDK. It reads the configuration from the file IMIconnectConfiguration.plist. You can pass an error in parameter, which will be set if any error occurs during the startup process. You need not use this method if you are using the [ICAppDelegate didFinishLaunchingWithOptions:] method.

  Syntax: + (BOOL)startup:(NSError **)error;

  Parameters:

Parameter
Type
Description

error

NSError

Specifies the error description.

startupWithConfig


This method is used to initialize the SDK using the provided configuration options. You can pass an error in parameter, which will be set if something wrong occurs during the startup process.

  Syntax: + (BOOL)startupWithConfig:(ICConfig *)config error:(NSError **)error;

  Parameters:

Parameter
Type
Description

config

Refer to ICConfig class.

error

NSError

Specifies the error description.

  Example:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ICConfig *config = [[ICConfig alloc] initWithClientKey:@"<Your client key>" forAppId:@"<Your App Id>"];
    NSError *error;
    [IMIconnect startupWithConfig:config error:&error];
    if (error != nil)
    {
        NSLog(@"Start up failed. Error: %@",error.localizedDescription);
    }
  	[super application:application didFinishLaunchingWithOptions:options]
    return YES;
}

shutdown


This method is used to cleanup the SDK, freeing all internal object instances. Invoking this method will stop the SDK features from functioning as such Real Time Messages and Push notifications.

Usage of this method is not required unless there are a few limited cases where you may wish to use it; for example, if you are only using the Authentication or Monitoring features.

registerWithDeviceProfile


This method registers the device profile with the SDK. This method causes profile details to be sent to the IMIconnect platform. Once a profile is registered, all further SDK calls take place in the context of that profile.

  Syntax: (void)registerWithDeviceProfile:(ICDeviceProfile *)deviceProfile completionHandler:(void (^)(NSDictionary *response,NSError *error))completionHandler

ICDeviceProfile *deviceProfile = [[ICDeviceProfile alloc]
initWithDeviceId: [ICDeviceProfile defaultDeviceID]];
[IMIconnect registerWithDeviceProfile:deviceProfile
completionHandler:^(NSDictionary*response, NSError *error)
{
		//Handle the response
}];

deviceProfile


This method retrieves the current registered device profile.

  Syntax: + (ICDeviceProfile *)deviceProfile

isRegistered


This method is used to check whether the user is currently registered with IMIconnect. This method returns true if the user is registered, else false is returned.

  Syntax: + (BOOL)isRegistered;

setPolicyPollingInterval


This method is used to set the interval at which the SDK will poll policy updates in minutes. To prevent adverse affects on battery or CPU usage a minimum interval of 30 minutes is enforced. To disable polling, set the value to 0. If Real Time Messaging or Push is enabled, this value will not be used.

  Syntax: +(void)setPolicyPollingInterval:(NSTimeInterval)interval;

  Parameters:

Parameter
Type
Description

interval

NSTimeInterval

Specifies the time in minutes after which policy updates will happen.

policyPollingInterval


This method is used to get the current policy polling interval, in minutes.

  Syntax: +(NSTimeInterval)policyPollingInterval;

updateDeviceProfileParam


This method updates the device profile parameter identified by ICDeviceProfileParam with a new value.

  Syntax: + (void)updateDeviceProfileParam:(ICDeviceProfileParam)deviceProfileParam withValue:(NSString *)value completionHandler:(void (^)(NSDictionary *response,NSError *error))completionHandler

IMIconnect updateDeviceProfileParam:ICDeviceProfileParamCustomerId
													wirhValue:@"myCustomerId"
                 completionHandler:^(NSDictionary *response,NSError *error)
{
	//Handle the response
}];

deviceProfile


This method retrieves the deviceId used by IMIconnect APIs.

  Syntax: + (ICDeviceProfile *)deviceProfile

Method (Deprecated)
New Method
Description

  +(NSString *)deviceId

  +(ICDeviceProfile *)deviceProfile

Retrieves the deviceId used by IMIconnect APIs.

removeDeviceProfileParam


This method removes the device profile parameter identified by ICDeviceProfileParam with a new value.

  Syntax: + (void)removeDeviceProfileParam:(ICDeviceProfileParam)completionHandler:(void (^)(NSDictionary *response,NSError *error))completionHandler

[IMIconnect removeDeviceProfileParam:ICDeviceProfileParamUserId
									completionHandler:^(NSDictionary *response, NSError *error)
{
	//Handle the response
}];

unregister


This method unregisters the current device profile.

  Syntax: + (void)unregister:(void (^)(NSError *error))completionHandler

sdkVersion


This method retrieves the SDK version number.

  Syntax: + (NSString *)sdkVersion;

  Return Value: Returns the SDK version number.

setSecurityToken


This method is used to set security token to provide better access control for user-centric resources. This method allows developers to specify the Security Token that the SDK will pass to the Gateway API calls.

  Syntax: + (void)setSecurityToken:(NSString *)token;

  Parameters:

Parameter
Type
Description

token

String

Specifies the token which is generated from jwttoken API.

  Example:

        TokenRequest *tokenRequest = [TokenRequest new]; 
        [tokenRequest requestTokenWithUserId:userId 
                                       appId:appId 
                                   expiresIn:self.expirationTime 
                           completionHandler:^(NSString *token, NSError *error) 
         { 
             if (token != nil) 
             { 
                 [IMIconnect setSecurityToken:token]; 
             } 
             if (completionHandler != nil) 
             { 
                 completionHandler(token,error); 
             } 
         }]; 

setSecurityTokenErrorDelegate


This method allows developers to register an object which implements the SecurityTokenExceptionListener interface to listen for Security Token related exceptions which occur from internal (indirect) Gateway API calls.

  Syntax:
+ (void)setSecurityTokenErrorDelegate(id<ICSecurityTokenErrorDelegate>)delegate;

  Example:

[IMIconnect setSecurityTokenErrorDelegate:self]; 

ICDeviceProfile

ICDeviceProfile is a class that gathers information about the back-end device profile. An ICDeviceProfile instance should be instantiated to register a device profile.
The developer can choose to register the device profile with a deviceId only or with a deviceId and an appUserId. User can generate a unique/own device ID or can choose the defaultDeviceId provided by the SDK.
If the user chooses to register a device profile with the deviceId only, the backend will automatically generate an appUserId. The current device profile is accessible via the IMIconnect class.

Property
Description

Indicates if the app user ID has been generated by the system.

Methods
Description

(instancetype)initWithDeviceId:(NSString *)deviceId

Instantiates an ICDeviceProfile with a deviceId.

(instancetype)initWithDeviceId:(NSString *)

deviceId appUserId:(NSString *)appUserId

Instantiates an ICDeviceProfile with a deviceId and an appUserId.

(NSString *)defaultDeviceId

Retrieves the default device ID based on the vendor ID of the device.

ICConfig

This class holds the configuration information that is used to initialize the SDK.

Property
Description

Specifies the app id of the app created in IMIconnect.

Specifies the client key of the app created in IMIconnect.

@property (nonatomic, readonly) NSString *groupIdentifier;

The app group identifier. This group identifier is used to retrieve information between the CoreSDK and the NotificationServiceExtension.

initWithClientKey:withappid:


This method is used to initialize an ICConfig instance with an appId and clientKey.

  Syntax: - (instancetype)initWithClientKey:(NSString *)clientKey forAppId:(NSString *)appId;

  Parameters:

Parameter
Type
Description

appId

NSString

Specifies the app id that is created in IMIconnect.

clientKey

NSString

Specifies the client key that is created in IMIconnect.

  Example:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ICConfig *config = [[ICConfig alloc] initWithClientKey:@"<Your client key>" forAppId:@"<Your App Id>"];
    NSError *error;
    [IMIconnect startupWithConfig:config error:&error];
    if (error != nil)
    {
        NSLog(@"Start up failed. Error: %@",error.localizedDescription);
    }
    return YES;
}

initWithClientKey:withappid:groupIdentifier

This method is used to initialize an ICConfig instance with an appId, a clientKey and a group identifier.

  Syntax: - (instancetype)initWithAppId:(NSString *)appId clientKey:(NSString *)clientKey groupIdentifier:(NSString *)groupIdentifier;

  Parameters:

Parameter
Type
Description

Appid

NSString

clientKey

NSString

groupidentifier

NSString

ICLogger

setLogType


This method sets the log options for the logger.

  Syntax: + (void)setLogType:(ICLogType)logType forLogTarget:(ICLogTarget)logTarget

  Parameters:

Parameter
Type
Description

logType

ICLogType

The type of logs that will be logged.

target

ICLogTarget

The target on which the logs will be displayed/recorded.

setRetentionDuration


This method sets the retention duration of the logs. The logs will be kept during that duration and will be automatically purged after.

  Syntax: + (void)setRetentionDuration:(NSInteger)days

  Parameters:

Parameter
Type
Description

days

Integer

The number of days after which the logs will be purged.

logPath


This method retrieves the directory path where the logs are stored.

  Syntax: + (NSString *)logPath

  Return Value: Returns the directory path where the logs are stored.

ICMessage

Parameter
Description

Informs if the message is an outgoing message

Used to retrieve title of a message.

Identifies the message transaction within the IMIconnect platform

The content of the message. Usually, this is the text that is displayed to the end user.

The thread related to the message

The message status

The userId of the message.

The date when the message has been submitted.

The date when the message has been delivered

The date when the message has been read.

The date when the message has been created.

The channel on which the message was received (Push or RTM)

The channel on which the message was received (Push or RTM)

Any attachments which are or have to be attached to the message

The category of message. The category will be used by the SDK to create an interactive notification. It will be nil if the message is basic.

Any supplementary data that was sent as part of the message payload.
This format of this data is controlled by the IMIconnect platform and enables certain standard features su as interactive messages.

Any custom, developer specified, data that was sent or to be sent as part of the message payload.

isOutgoing


This method is used to check whether a message is outgoing or not.

  Syntax: @property (nonatomic, readonly) BOOL isOutgoing

title


This method is used to retrieve the title of a message.

  Syntax: @property (nonatomic, readonly) NSString *title

transactionId


This method is used to retrieve the transaction id of the message

  Syntax: @property (nonatomic, readonly) NSString *transactionId;

message


The content of the message. Usually this is the text that is displayed to end users.

  Syntax: @property (nonatomic) NSString *message;

thread


The thread related to the message

  Syntax: @property (nonatomic) ICThread *thread;

status


The message status.

  Syntax: @property (nonatomic) ICMessageStatus status;

userId


The userId of the message.

  Syntax: @property (nonatomic, readonly) NSString *userId;

submittedAt


The date when the message has been submitted

  Syntax: @property (nonatomic, readonly) NSDate *submittedAt;

deliveredAt


The date on which the message is delivered

  Syntax: @property (nonatomic, readonly) NSDate *deliveredAt; Description:

readAt


The date when the message has been read

  Syntax: @property (nonatomic, readonly) NSDate *readAt;

createdAt


The date when the message is created

  Syntax: @property (nonatomic, readonly) NSDate *createdAt;

ICMessageChannel


The channel on which the message was received (Push or RTM)

  Syntax: @property (nonatomic, readonly) ICMessageChannel channel;

CMessageType


The type of the message

  Syntax: @property (nonatomic, readonly) ICMessageType type;

attachments


Any attachments which are or have to be attached to the message

  Syntax: @property (nonatomic) NSMutableArray *attachments;

category


The category of message. The category will be used by the SDK to create an interactive notification. It will be nil if the message is basic.

  Syntax: @property (nonatomic, readonly) NSString *category;

extras


Any supplementary data that was sent as part of the message payload.
This format of this data is controlled by the IMIconnect platform and enables certain standard features such as interactive messages.

  Syntax: @property (nonatomic, readonly) NSDictionary *extras;

customTags


Any custom, developer specified, data that was sent or to be sent as part of the message payload

  Syntax: @property (nonatomic) NSMutableDictionary *customTags;

initWithData


Creates an instance of an ICMessage based on data

Syntax: - (instancetype)initWithData:(NSData *)data

  Parameters:

Parameter
Type
Description

data

NSData

Data from which an ICMessage is created

   Return Value: Returns an instance of ICMessage

initWithDictionary


Creates an instance of an ICMessage based on a dictionary

Syntax: - (instancetype)initWithDictionary:(NSDictionary *)dictionary

  Parameters:

Parameter
Type
Description

dictionary

NSDictionary

The dictionary from which an ICMessage is created

   Return Value: Returns an instance of ICMessage

data


Creates data from an ICMessage

Syntax: - (NSData *)data

Return Value: Returns data containing the ICMessage

dictionary


Creates dictionary from an ICMessage

Syntax: - (NSDictionary *)dictionary

Return Value: Returns a dictionary containing the ICMessage

ICAttachment

This class exposes data relating to attachments that are received through RTM or Push, also used to attach media and location to outgoing RTM messages.

Parameter
Description

The type of content of the attachment.

contentType


This property is used to get the content type of the attachment such as image, video, audio or location.

  Syntax: @property (nonatomic) NSString *contentType

ICMediaAttachment

This class exposes data relating to media file attachments that are received through RTM or Push, also used to attach media files to outgoing RTM messages.

Parameter
Description

Used to define media attachment.

Used to get the size of the media in bytes.

Used to get the URL for media attachment.

mediaId


This method is used for media attachment.

  Syntax: @property (nonatomic) NSString *mediaId

size


This method is used to get the size of the media in bytes.

  Syntax: @property (nonatomic, readonly) long size

URL


This method is used to get the URL for media attachment.

  Syntax: @property (nonatomic, readonly) NSURL *url

ICAudioAttachment

This class exposes data relating to Audio file attachments that are received through RTM or Push, also used to attach Audio files to outgoing RTM messages.

Parameter
Description

Used to get the duration of the audio files.

duration


  • This method is used to get the duration of the applicable audio files.

  Syntax: @property (nonatomic) long duration

ICImageAttachment

This class exposes data relating to Audio file attachments that are received through RTM or Push, also used to attach Audio files to outgoing RTM messages.

Parameter
Description

Used to preview thumbnail as an UIImage.

preview


This method is used to preview thumbnail as an UIImage.

  Syntax: @property (nonatomic) UIImage *preview

ICVideoAttachment

This class exposes data relating to Video file attachments that are received through RTM or Push, also used to attach video files to outgoing RTM messages.

Parameter
Description

Used to get the video preview (thumbnail) as a bitmap.

Used to get the duration of the video files.

preview


This method is used to get the video preview thumbnail as a bitmap.

  Syntax: @property (nonatomic) UIImage *preview

duration


This method is used to get the duration of the applicable video files.

  Syntax: @property (nonatomic) long duration

ICLocationAttachment

This class exposes data relating to location attachments that are received through RTM or Push, also used to send location to outgoing RTM messages.

Parameter
Description

Used to get the latitude of the location passed in message.

Used to get the longitude of the location passed in message.

latitude


This method is used to get the latitude of the location passed in message.

  Syntax: @property (nonatomic) double latitude

longitude


This method is used to get the longitude of the location passed in message.

  Syntax: @property (nonatomic) double longitude

ICTopic

This class exposes Push or Real Time Messaging topic data that is used to publish outgoing messages or subscribe to receive incoming messages.

Parameter
Description

Used to get date on which the topic is created.

Used to get topic Id.

Used to get the topic name.

createdAt


This method is used to get date on which the topic is created.

  Syntax: @property (nonatomic, readonly) NSDate *createdAt

topicId


This method is used to get topic Id.

  Syntax: @property (nonatomic, readonly) NSString *topicId

  Return Value: Returns the ID for the topic.

name


This method is used to get the topic name.

  Syntax: @property (nonatomic, readonly) NSString *name

getTitle


This method is used to get the topic title.

  Syntax: public String getTitle()

  Return Value: Returns the topic title.

group


This method is used to get the topic’s group.

  Syntax: @property (nonatomic, readonly) NSString *group

isSubscribed


This method is used to verify whether the current user is subscribed to the topic.

  Syntax: @property (nonatomic, readonly) BOOL isSubscribed

desc


This method is used to get topic description.

  Syntax: @property (nonatomic, readonly) NSString *desc

  Return Type: Returns description of a topic.

ICMediaFileManager

This class manages the media file upload and download.

isProcessing


This method is used to informs if the manager is currently downloading or uploading a file.

  Syntax: + (BOOL)isProcessing

  Return Type: Returns a YES if the manager is currently downloading or uploading files, else returns a NO.

uploadFileFromLocation


This method is used to upload a file to connect platform.

  Syntax: + (void)uploadFileFromLocation:(NSURL *)location progressHandler:(void(^)(NSUInteger bytesWritten, long long totalBytesWritten, long long totalBytesExpectedToWrite))progressHandler completionHandler:(void(^)(NSString *mediaId, NSError *error))completionHandler

  Parameters:

Parameter
Type
Description

location

URL

The URL of the local file.

progressHandler

Integer

A progress handler that inform on the current progress of the upload.

completionHandler

String

A completionHandler that will be call once the file is uploaded with the associated mediaId.

isFileUploadingFromLocation


This method is used to check if the manager is currently uploading a file.

  Syntax: + (BOOL)isFileUploadingFromLocation:(NSURL *)location

  Return Type: Returns a YES if the file is currently being uploaded, else returns a NO.

  Parameters:

Parameter
Type
Description

location

URL

The local URL of the file.

downloadFileAtURL


This method is used to download a file from a URL. This method may retrieve a file locally if already downloaded or may queue the completionHandler if the file associated to the URL is already being downloaded.

  Syntax: + (void)downloadFileAtURL:(NSURL *)url completionHandler:(void(^)(NSData *contentOfFile, NSURL *filePath, NSError *error))completionHandler

  Parameters:

Parameter
Type
Description

url

URL

The URL of the file to be download.

completionHandler

Error

Will be called once the file is downloaded.

isFileDownloadingAtURL


This method is used to check if the manager is currently downloading a file at a URL.

  Syntax: + (BOOL)isFileDownloadingAtURL:(NSURL *)url

  Return Value: Returns a YES if the file is currently being downloaded, else returns a NO.

  Parameters:

Parameters
Type
Description

URL

URL

The URL of the file that will be checked.

contentOfFileForURL


This method is used to retrieve the content of a file associated to a URL.

  Syntax: + (void)contentOfFileForURL:(NSURL *)url completionHandler:(void(^)(NSData *contentOfFile))completionHandler

  Parameters:

Parameter
Type
Description

url

URL

The URL associated to the content.

completionHandler

Data

A completion that will be called with the content if the content exists, nil otherwise.

filePathForURL


This method is used to retrieve the filePath where the content of the file at the passed URL is stored.

  Syntax: + (NSURL *)filePathForURL:(NSURL *)url

  Return Value: Returns the filePath where the content is locally located.

  Parameters:

Parameter
Type
Description

url

URL

The URL where the content has been retrieved.

fileExistsForURL


This method is used to check if a file exists for a URL.

  Syntax: + (void)contentOfFileForURL:(NSURL *)url completionHandler:(void(^)(NSData *contentOfFile))completionHandler

  Return Value: Returns a YES if the file exists, else returns a NO.

  Parameters:

Parameter
Type
Description

url

URL

The URL to be checked.