Skip to content

Integration into iOS Mobile Applications

This article provides information about integrating Rox.Chat Mobile SDK version 3 into your iOS app.

Setup

CocoaPods

The Rox.Chat Mobile SDK is available via CocoaPods (repository). To install the SDK you need to add to your Podfile for the desired target:

pod 'RoxchatClientLibrary'

The use_frameworks! directive must be specified in the Podfile.

Example Application

To run the example, "clone" the repository and run the pod install command from the Example directory.

If you do not have CocoaPods installed, you must install them before doing so with the command in terminal:

sudo gem install cocoapods.

Usage

Unlike the web interface, the mobile application on Rox.Chat Mobile SDK does not check for available (online) operators. In other words, mobile chat always assumes that the operator call button is always in "online" status. Rox.Chat Mobile SDK always allows to start a chat, however, if there are no operators ready to answer in this chat, the client will be in the chat alone until such operator appears or the chat will be closed by timeout.

Rox.Chat supports connecting several different iOS mobile apps to Rox.Chat Server to a single customer account.

Rox.Chat Mobile SDK for iOS supports placement selection when creating a chat. We recommend always creating at least one separate placement for a mobile app. If there are multiple mobile apps, a minimum of one placement for each MP.

Chat interaction takes place within a session, which is created at the moment when the MF is about to offer a chat to the user. To work with it, the RoxchatSession object is used.

RoxchatSession

Using the library functionality starts with creating a session object. The Roxchat class method newSessionBuilder() returns an object of the SessionBuilder builder class (both classes and their methods are described in the Roxchat.swift file). Afterward, methods are called on the created SessionBuilder object to set the session parameters. After setting all the required parameters, the build() method is run on this object, which returns a RoxchatSession object.

Typical usage example:

let roxchatSession =
    try Roxchat.newSessionBuilder().set(accountName: ACCOUNT_NAME).set(location: LOCATION_NAME).build()

Where ACCOUNT_NAME is the name of your Roxchat account, and LOCATION_NAME is the name of the location to be used in the mobile application.

A description of all the parameters that can be set when creating a session, as well as errors that may occur during the process, can be found in the Roxchat.swift file. The only two parameters that are mandatory are account name and location.

Once a session is created, it must be started using the resume() method (since the session object is initially created suspended). If necessary, the session can be suspended (pause() method) and resumed (resume() method), as well as deactivated (destroy() method) - all these methods are described in the RoxchatSession.swift file.

MessageStream

All methods concerning the message stream are described in the MessageStream.swift file. To use these methods, a MessageStream object must be obtained. This is accomplished by the getStream() method of the RoxchatSession instance.

Examples of methods:

  • send(message:) to send a message,

  • rateOperatorWith(id:,byRating:) - rate an operator,

  • closeChat() (@available(*, deprecated)) - close chat.

MessageTracker

The new(messageTracker:) method of the MessageStream object creates an object of the MessageTracker class that can be used to control the flow of messages in the context of a client application. For example, the getNextMessages(byLimit:,completion:) method requests a specific number of messages from the message history.

A description of the methods of the MessageTracker instance can be found in the MessageTracker.swift file.

MessageListener

The MessageListener protocol describes methods to track changes in the message stream. A user application needs a class that implements the methods of this protocol: added(message:,after:), removed(message:), removedAllMessages(), changed(message:,to:). These methods are automatically called when a message is added, a message is deleted, all messages are deleted, and a message is modified, respectively.

Full descriptions of the methods can be found in the MessageListener.swift file.

Message

Methods of the MessageListener protocol operate on Message objects described in the Message.swift file. Using methods of Message class instances it is possible to get all necessary data about a particular message: unique message number (getID() method), message text (getText() method), information about attached file (getAttachment() method), etc.

All tools related to this class (methods for working with attachments, message types, etc.) are also described in the Message.swift file.

Additional Features

The Operator.swift file describes methods to get information about a particular operator. A specific operator object can be retrieved using the getCurrentOperator() method of the MessageStream object.

The RoxchatPushNotification.swift file describes methods for handling push notifications received from the Rox.Chat service. The object of a particular notification can be retrieved using the parse(remoteNotification:) method of the Roxchat class. The same class also has the isRoxchat(remoteNotification:) method, which allows you to easily find out whether a push notification was sent by the Rox.Chat service or some other service.

The FatalErrorHandler.swift file contains a description of the FatalErrorHandler protocol, whose methods can be implemented by a particular mobile application to track errors that occur during operation. All specific errors are described in the RoxchatError.swift file.

The MessageStream.swift file contains descriptions of additional protocols whose methods can be implemented by application classes to track certain specific events. For example, methods of the ChatStateListener protocol react to changes in the chat state (descriptions of possible chat states are available in the same file).

Push Notifications

To enable push notifications, you need to provide APNS certificates for your mobile applications. You can use one of the certificate sets at the same time: for development (dev) and for product (dist). They can be either the same or different (one certificate for both development and product versions). Each set consists of two files: cert (the certificate itself) and private_key (the private key to this certificate). It is also possible to disable both one and the other certificate set through account config settings. To place certificates on Rox.Chat server and change account config settings, please contact our support team.

Final names of certificate files:

ios_push_cert.dev.pem
ios_push_private_key.dev.pem
ios_push_cert.dist.pem
ios_push_private_key.dist.pem

To automatically process and display push notifications in iOS, your app must be aware of the possible types of notifications and the arguments sent to them (notifications).

The type of push notification is defined by the loc-key parameter.

Argument array values (loc-args parameter):

  • for "P.CR" - the array is empty;

  • for "P.OA" - operator name;

  • for "P.OF" - operator name, file name;

  • for "P.OM" - operator name, message text;

  • for "P.WM" - the array is empty.

Example of processing a notification using the Strings.localizable file:

"P.OM" = "Received a new message from %@: %@.".

Conclusion

The above described entities and their methods are all you need to work in a mobile application with Rox.Chat service, and even more. Not all the features of this library are described in this guide, so after implementing the necessary minimum in a particular application, it is recommended to familiarize yourself with the full list of protocols and methods in the library's public files.

Public interfaces, classes and methods are described in the files (in alphabetical order):

  • FatalErrorHandler.swift

  • Message.swift

  • MessageListener.swift

  • MessageStream.swift

  • MessageTracker.swift

  • Operator.swift

  • ProvidedAuthorizationTokenStateListener.swift

  • Roxchat.swift

  • RoxchatError.swift

  • RoxchatPushNotification.swift

  • RoxchatSession.swift

A description of each class, protocol, method, etc. can be found in handbook.

Additional Information

The Rox.Chat Mobile SDK uses the SQLite.swift and CryptoSwift libraries.

There is no need to install separate dependencies in Podfile.