Let's integrate our SDK in few minutes

Quick Start#
Download SDK Files
Download
warning

MirrorFly Chat SDK V1 is no longer supported as a new version is released. Check out our latest Chat SDK V2 here.

To migrate from MirrorFly Chat SDK V1 to V2 please follow the Migration guide steps.

Chat SDKs for iOS#

With CONTUS MirrorFly Chat SDK for iOS, you can easily add real-time chat features to your client app within 30 minutes.

Through our client SDK, you can initialize and configure chat into your app with minimal efforts.

Note : If you're looking for the fastest way to build your app’s UI with MirrorFly Chat SDKs, you can use our sample apps. To get our sample apps, click here

Getting Started#

Requirements#

The below are the requirements for chat SDK for iOS,

  • Xcode 14.1 or later
  • iOS 12.1 or later
  • Swift 5.0 or later

Things To Be Noted Before You Get Started#

SDK License Key#

To integrate MirrorFly Chat SDK into your app, you will need a SDK License Key. The MirrorFly server will use this license key to authenticate the SDK in your application.

To get the License Key,#

Step 1: Register here to get a MirrorFly User account. Registration is subject to verification and would take up to 24 hours.

Step 2: Login to your Account

Step 3: Get the License key from the application Info’ section

Step 4: Download the iOS SDK

license-key

Integrate the Chat SDK#

Since the SDKs were compiled into multiple XCFramework binary packages you need to start with SDK integration. Thus, you have to follow the below given steps,

Step 1: First extract the xcframework files from the downloaded zip file that is provided at the top of this guided documentation. Once extracted you get the following xcframeworks.

  • FlyCore.xcframework
  • FlyCommon.xcframework
  • FlyNetwork.xcframework
  • FlyDatabase.xcframework
  • FlyXmpp.xcframework
  • FlyTranslate.xcframework
  • FlyCall.xcframework

Frameworks

Step 2: Add all the extracted xcframeworks to your project.

Goto Project -> Target -> General -> Frameworks,libraries and Embedded Content -> Select Embed & Sign for all the Chat SDK's xcframeworks

EmbedAndSign

Step 3 : Now, disable the bitcodes for your project

Goto Project -> Build Settings -> Filter the term `Bitcode` -> and select No from the dropdown

Bitcode

Step 4: If you have not initiated any pods project before, then initiate the one. Now, add the required pods that are necessary for the SDK to execute the process perfectly.

pod 'libPhoneNumber-iOS', '0.9.15'
pod 'Alamofire', '5.5'
pod 'XMPPFramework/Swift'
pod 'SocketRocket'
pod 'Socket.IO-Client-Swift', '~> 15.2.0'
pod 'RealmSwift', '10.20.1'
pod 'GoogleWebRTC'

Step 5: Add the below given pod hook code block at the end of the pod file and thus, finally install the pods.

post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.1'
config.build_settings['ENABLE_BITCODE'] = 'NO'
config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'No'
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end

Podfile

Step 6: Now, enable all the below mentioned capabilities into your project.

Goto Project -> Target -> Signing & Capabilities -> Click + at the top left corner -> Search for the capabilities below
Capabilities
App Groups
Background Modes

Now, go to the background mode and enable the below given modes

Background Modes
Audio,Airplay, and Picture in Picture
Background fetch
Remote notifications

Capabilities

Configure the SDK server & Data#

Now, configure the server details in SDK and access the data globally using the AppDelegate class.

You can copy the license key from the 'Overview’ section in the Console dashboard.

let BASE_URL = "https://api-preprod-sandbox.mirrorfly.com/api/v1/"
let LICENSE_KEY = "xxxxxxxxxxxxxxxxxxxxxx"
let CONTAINER_ID = "xxxxxxxxxxxxxxxxxxxxxx"

Parameter Description#

FunctionParameter TypeDescription
CONTAINER_IDStringCreate App groups and assign the obtained group container id. SDK uses this string to create the path for the local storage.

Initialize ChatSDK#

To start using the sdk, there are a few basic pieces of data that must be made available for the SDKs to function perfectly.

Thus, we utilize the usage of the ChatSDK builder class making the data available for SDKs. Furthermore, in your project you must use the AppDelegate class within the didFinishLaunchingWithOptions method and also provide required data to build the ChatSDK Builder. Let's have a look at the example given below.

try? ChatSDK.Builder.setAppGroupContainerID(containerID: CONTAINER_ID)
.setLicenseKey(key: LICENSE_KEY)
.isTrialLicense(isTrial: true)
.setDomainBaseUrl(baseUrl: BASE_URL)
.buildAndInitialize()

AppDelegate

Chat Builder Function Description#

FunctionParameter TypeDescription
setAppGroupContainerIDStringPass group container id of the project that stores UserDefaults and Database
setLicenseKeyStringUsed to proceed with Registration
isTrialLicenseBoolIf the obtained license key is a trial license key - display the message as true else false
setDomainBaseUrlStringUrl required to make API calls
buildAndInitializen/aInitialize the chat configuration
caution

The base url must have Http/Https protocol which should be closed with a slash (/), or else will display an exception bug message.

Registration#

The below method should be called to register a new user. This method will take care of both Sandbox mode registration as well as Live mode registration based on isTrialLicense provided in the ChatSDK.Builder class.

info

Unless you logged out of a session, make sure that you have called the Registration method only once in an application

Note: While registration, the below registerApiService method will accept the additional params required for notification processing on server and IS_FORCE_REGISTER as an optional param for maintaining sessions and USER_TYPE as an optional param to provide type of user.

  • APNS_DEVICE_TOKEN
  • VOIP_TOKEN
  • IS_EXPORT
try! ChatManager.registerApiService(for: USER_IDENTIFIER ) { isSuccess, flyError, flyData in
var data = flyData
if isSuccess {
// This is your Password
guard let password = data["password"] as? String else{
return
}
// This is your Username
guard let username = data["username"] as? String else{
return
}
}else{
let error = data.getMessage()
print("#chatSDK \(error)")
}
}
ArgumentTypeDescription
USER_IDENTIFIERStringUnique Id to Register the User. We accept only the AlphaNumeric String
APNS_DEVICE_TOKENStringToken to register APNS device (optional)
VOIP_DEVICE_TOKENStringToken to register VoIP device (optional)
IS_EXPORTBooltrue for production(apns certificate) builds and false for sandbox(apns certificate)builds
IS_FORCE_REGISTERBooldefault value true provide true to force the logout of the old session If the registered user has reached the maximum no of multi-sessions or provide false to allow registration till the maximum no of multi-sessions
USER_TYPEStringType of the user (optional)
CALLBACKFlyCompletionHandlerFlyCompletionHandler is implemented and expressed as lambda expression

To know more about FlyCompletionHandler click here

caution

If IS_FORCE_REGISTER is false, and it reached the maximum no of multi-sessions then registration will not succeed it will throw a 405 exception, Either IS_FORCE_REGISTER should be true or one of the existing session need to be logged out to continue registration.

info

Save your own contact details in DB after registration. Your contact detail will be used while sending group messages. Call below method to save your own contact details,

ContactManager.shared.saveTempContact(userId: "OUR OWN JID" , name: "OUR NAME")

To generate a unique user id, you must pass the username in the method String userJID = FlyUtils.getJid(USERNAME)

Connect to the Chat Server#

Whenever you are planning to send a message using the Chat SDK, first you have to establish a connection to the chat server using the below given method.

ChatManager.connect()

Disconnect Chat Server#

Use the below given method to disconnect from the chat server call.

ChatManager.disconnect()

Observe Connection Events#

The connection status can be observed and tracked by confirming the ConnectionEventDelegate. To do that you need to set ‘delegate’ in your ViewController's viewDidAppear method like below.

ChatManager.shared.connectionDelegate = self

Once the ConnectionEventDelegate has been set, you will be able to receive the connection status in the delegate method as mentioned below. Learn more about this method @ ConnectionEventDelegate.

func onConnected() {
// Navigate to Conversation screen
}

Terminology#

The below given are some of the common keyword/terminologies used in the Chat SDK with description

KeywordDescription
userID/userBareIDUnique ID assigned for each user Ex: 12345678 (any alphanumeric). The below characters is not allowed in userId: U+0022 (") U+0026 (&) U+0027 (') U+002F (/) U+003A (:) U+003C (<) U+003E (>) U+0040 (@) userID should follow below specification: https://xmpp.org/extensions/xep-0106.html
userJid (or) JIDuserID+@+domain of the chat server Ex. 12345678@xmpp.chatsystem.dev.contus.us
groupID/groupBareIDUnique ID assigned for each group Ex: group123456 (any alphanumeric). GroupJID = groupID +@mix.+domain of the chat server Ex: group123456@mix.xmpp.mirrorfly.dev.contus.us`
info

SDK here provides the built-in functions to prepare the JID and Group JID.

Send a One-to-One Message#

The below method is used to send a text message from one user to another.

Note: To generate a unique user id, you must call the other user's username in the method String userJID = FlyUtils.getJid(USERNAME)

FlyMessenger.sendTextMessage(TO_JID, TEXT) { isSuccess,error,chatMessage in
if isSuccess {
// Update the UI
}else{
// Handle the error
}
}
ArgumentTypeDescription
TO_JIDStringjid of the end user
TEXTStringSpecifies the text message that needs to be sent
REPLY_MESSAGE_IDStringProvides the Message ID of replied message or else generates an empty string (optional)
CALLBACKSendMessageListenercallback to observe the action status

Receive a One-to-One Message#

Set the delegate in your ViewController's viewDidAppear method using below syntax and confirm the MessageEventsDelegate class, this will enable you to see other incoming messages and related events.

ChatManager.shared.messageEventsDelegate = self

Once the delegate has been set, we will be able to receive the incoming message in the method mentioned below.To know more about other methods in MessageEventsDelegate kindly visit MessageEvent Delegate

To know more about other methods visit MessageEvent Delegate class,

func onMessageReceived(message: ChatMessage, chatJid: String) {
// Message received from chatJid, content is message.messageTextContent
}