Source: https://rox.chat/kb/mobile/sdk/ios-integration.html > This article provides information about integrating Rox.Chat Mobile SDK version 3 into your iOS app. # 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](https://github.com/roxchat/mobile-sdk-ios)). 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](https://rox.chat/kb/mobile/sdk/ios-sdk-handbook.html). ### Additional Information The **Rox.Chat Mobile SDK** uses the [SQLite.swift](https://github.com/stephencelis/SQLite.swift) and [CryptoSwift](https://github.com/krzyzanowskim/CryptoSwift) libraries. There is no need to install separate dependencies in `Podfile`.