Moxtra Chat SDK for iOS

Use the Moxtra Chat SDK module to add rich collaboration to your app.

What features you will get with the SDK:

  • Ability to do one-on-one and/or group chats
  • Share files
  • Layer visual & voice annotations on top of files
  • Conduct real-time meetings

Lets get started by using a sample app "Moxie Chat". In this tutorial, you will learn how to integrate the Moxtra Chat SDK in your app.

The diagram below explains how the sample app "Moxie Chat" will interact with Moxtra.

App Architecture

Setup

Asynchronous programming

You should have some basic knowledge of asynchronous programming. In short, if you found the API has success or failure as parameter then you will not get result immediately after you call the API. You should wait for the callback and decide the next action.

Register

Before proceeding further, ensure you have registered your app with Moxtra.

Clone the sample project from github

Please clone the sample project MoxieChat from here:

git clone https://github.com/Moxtra/moxtra-chat-ios-sample.git

Step 0: Create an empty project

Make sure you have Xcode installed properly. The Xcode will guide you to install the iOS SDK if you don't have one.

You can create an empty project using Xcode

Step 1: Add the Moxtra SDK module

After creating the empty project, it's time to add the Moxtra Chat SDK module to it.

Download the iOS Chat SDK before navigating to the next steps.

Unzip the downloaded file and add the ChatSDK.framework and ChatSDKResource.bundle into your Xcode project by dragging them into your Project Navigator

Step 2: Add dependency libraries and frameworks

The Moxtra SDK additionally depends on the following libraries and frameworks, which must be added to the project and linked with the application target.

  • libc++.dylib
  • libxml2.2.dylib
  • libz.dylib
Moxtra iOS SDK

Step 3: Configure Background Modes

Enable the "Audio and AirPlay" option under "Background Modes", this is to have the meet session running in the background mode when the user minimize the app.

Enable the "Voice over IP", so you can join a meet with voice over IP.

And enable "Remote notifications" to keep your app up to the latest.

Moxtra iOS SDK

You can also verify the info.plist to confirm the background mode is set for audio.

Build your application to make sure there are no errors and if there are no errors you are ready to start the integration.

Step 4: Configure App info.plist

Transport Security

Add these keys to your info.plist.

Moxtra iOS SDK

User Privacy

Moxtra needs to use the device's microphone and camera to meet or take pictures to upload, so you should add these privacy to your info.plist

Moxtra iOS SDK

Step 5: Configure "Other Linker Flags"

An impedance mismatch between UNIX static libraries and the dynamic nature of Objective-C can cause category methods in static libraries to not be linked into an app, resulting in "selector not recognized" exceptions when the methods aren't found at runtime.

So you should add '-ObjC' to your app's 'Other Linker Flags'

Moxtra iOS SDK

Step 6: Initialize Moxtra SDK

To access the Moxtra APIs import the header file "Moxtra.h".

#import <ChatSDK/MXChatSDK.h>

Initialize the Moxtra SDK before calling any methods by setting your client id and client secret. We recommend you to encode the Client ID and Client Secret Key.

APP_BASE_DOMAIN should be set based on the environment:

  • "www.moxtra.com" for production environment
  • "sandbox.moxtra.com" for sandbox environment
// Fill in the App Client ID and Client Secret Key received from the app registration step from Moxtra
NSString *APP_CLIENT_ID = @"Your client id";
NSString *APP_CLIENT_SECRET = @"Your client secret";
NSString *APP_BASE_DOMAIN = @"Server domain";
NSString *YOUR_UNIQUE_ID = @"Your unique id";
NSString *YOUR_ORG_ID = @"Your org id";

// Initialize Moxtra SDK and link account with unique id and org id
[[MXChatClient sharedInstance] linkWithUniqueID: YOUR_UNIQUE_ID orgID: YOUR_ORG_ID clientID: APP_CLIENT_ID clientSecret: APP_CLIENT_SECRET baseDomain: APP_BASE_DOMAIN completionHandler:^(NSError * _Nullable error) {
    if (handler)
    {
        handler(error);
    }
}];

After the user has successfully logged out from your app, unlink the Moxtra account.

[[MXChatClient sharedInstance] unlink];

Step 7: Set delegate

The Moxtra Chat SDK defines several delegate methods (MXChatClientDelegate protocol) that you need set delegate to handle those callbacks.

[MXChatClient sharedInstance].delegate = self;

Step 8: Show the chat list

Two scenarios need to be considered when showing the chat list:

  • Initializing the chat list when a user opens your app
  • Updating the user of any updates to the chats when the user is inside the chat list UI of your app.

When a user opens the chat list UI, you can call the following API to get all the chats:

//In interface:
@property (nonatomic, weak) MXChatListModel *chatListModel;

//Get chats where you need
self.chatListModel = [[MXChatListModel alloc] init]

After getting a list of all chat sessions, you have to listen for changes so the UI can be updated automatically.


- (void)chatListModel:(MXChatListModel *)chatListModel didCreateChats:(NSArray *)createdChats
{
    if (createdChats)
    {
        [self.chatList insertObjects:createdChats atIndexes:[NSIndexSet indexSetWithIndex:0]];
        [self.tableView reloadData];
    }
}

- (void)chatListModel:(MXChatListModel *)chatListModel didUpdateChats:(NSArray *)updatedChats
{
    [self.tableView reloadData];
}

- (void)chatListModel:(MXChatListModel *)chatListModel didDeleteChats:(NSArray *)deletedChats
{
    if (deletedChats)
    {
        [self.chatList removeObjectsInArray:deletedChats];
        [self.tableView reloadData];
    }
}

Step 9: Start a new chat

In the sample app, you now have an empty chat list.

You have to build the UI to select other users to create a group chat by calling the "createChatWithTopic:" API. On successful creation of the chat, we return the MXChat instance, and you can init a MXChatViewController with this MXChat instance to launch the chat UI in your app.

[self.chatListModel createChatWithTopic:@"Chat topic" completionHandler:^(NSError * _Nullable error, MXChatItem * _Nullable chatItem) {
    if (error)
    {
        /*Handler error*/
    }
    if (chatItem)
    {
        MXChatViewController *chatViewController = [[MXChatViewController alloc] initWithChatItem: chatItem];
        [self.navigationController pushViewController:chatViewController animated:YES];
    }
}];

You can also select another user to create a individual chat by calling the "startIndividualChatWithUniqueId" API in MXChatSession, which can initliaze from a MXChat instance.

Step 10: Open an existing chat

To open an existing chat from the chat list UI, implement the following code snippet:

//Get a chat from list
    //For example:
    MXChat *chat = self.chatLiseModel.chats[indexPath.row];
    MXChatViewController *chatViewController = [[MXChatViewController alloc] initWithChat:chat];
    [self.navigationController pushViewController:chatViewController animated:YES];

Step 11: Start a meet

With Moxtra Chat SDK, you can easily start an audio/video meeting with a few lines of code. You can aslo share your screen and annotate documents inside the meeting.

To start a meeting outside the Chat UI, use the following code snippet:

//Initliaze MXMeetListModel
self.meetListModel = [[MXMeetListModel alloc] init];
[self.meetListModel startMeetWithTopic:@"Meeting topic" completionHandler:^(NSError * _Nullable error, MXMeetSession *_Nullable meetSession) {
    if (error)
    {
        /*Handle error*/
    }
    if (meetSession != nil)
    {
       //Just call "presentMeetWindow" to show meet window in your App.
        [meetSession presentMeetWindow];
    }
}];

Step 12: Join a meet

Invited users should be able to join a meeting. Use this code snippet to implement the join meeting functionality.

[self.meetListModel joinMeetWithMeetId:@"Meet id" completionHandler:^(NSError * _Nullable error, MXMeetSession * _Nullable meetSession) {
    if (error)
    {
        /*Handle error*/
    }
    else
    {
        //Just call "presentMeetWindow" to show meet window in your App.
        [meetSession presentMeetWindow];
    }
}];

Step 13: Delete Chat

Every chat that is created is a persistent chat. Chat messages are saved over time, so new and old chat members can see all the chat history at any time.

If you have a chat that is no longer required, then it can be deleted. Use this code snippet to implement the Delete Chat functionality.

//Get the chat you want to delete
//For example:
MXChat *chat = self.chatListModel.chats[indexPath.row];
self.chatListModel deleteOrLeaveChat:chat withCompletionHandler:^(NSError * _Nullable error) {
    if (error)
    {
        /*Handle error*/
    }
    else
    {
        /*Handle success*/
    }
}];

Step 14: Enable notifications

To configure push notification, you will first need to export your production certificate from Apple iOS Push Services. Upload the certificate and private key files to the app configuration in Moxtra. If your certificate is password protected make sure to provide the same when you upload the certificate.

Register Notification

You will use "registerNotificationDeviceToken" api to register the device in your app delegate "didRegisterForRemoteNotificationsWithDeviceToken".

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
    [MXChatClient sharedInstance] registerNotificationDeviceToken:token
}

Next step is to handle the push notification received from the Apple Push Notification Service. You will call "isMoxtraRemoteNotification" in your app delegate "didReceiveRemoteNotification" to check whether this notification from Moxtra. If it is, then call "fetchItemWithRemoteNotification" to get notification detail and handle it.

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler
{
    if ([[MXChatClient sharedInstance] isMoxtraRemoteNotification:userInfo])
    {
        //Handle notifications from Moxtra
        [[MXChatClient sharedInstance] fetchItemWithRemoteNotification:userInfo completionHandler:^(NSError * _Nullable error, id _Nullable item) {
            if ([item isKindOfClass:[MXChatItem class]])
            {

            }
            else if ([item isKindOfClass:[MXMeetItem class]])
            {

            }
        }];
    }
    else
    {
        //Handle other notifications
    }
}

Download Chat SDK

To build your own implementation use the Moxtra iOS Chat SDK.

Current Stable Version - V 4.4.6 (May 2nd 2018)

API Reference

This tutorial covers only a few APIs. For a full list of APIs, please refer to our Android Chat SDK: API Reference Guide.

Current Stable Version - V 4.4.6 (May 2nd 2018)