# Интеграция в мобильные приложения iOS (v3)

В данной статье приведена информация об интеграции **Webim Mobile SDK** версии 3 в ваше iOS-приложение.

!!! Warning "Важно"
    Интеграция Webim Mobile SDK для iOS рассчитана на нативные приложения. Использование SDK в проектах на *Flutter/React Native* или в *WebView/PWA* не поддерживается и не гарантируется.

!!! Note "N.B."
    При использовании **Webim Mobile SDK** без готового виджета отображение и обработка ссылок в интерфейсе чата выполняются на стороне приложения.

## Установка

[Информация о выпусках (Release notes)](https://webim.ru/kb/mobile/sdk/v-3-0/ios-release-notes.html).

### CocoaPods

**Webim Mobile SDK** доступен с помощью технологии **CocoaPods** ([репозиторий](https://github.com/webim/webim-client-sdk-ios)). Чтобы установить SDK необходимо добавить в ваш `Podfile` для нужного `target`:

```
pod ‘WebimMobileSDK’
```

В `Podfile` должна быть указана директива `use_frameworks!`.


### Carthage

**Webim Mobile SDK** доступен также и с помощью `Carthage`. Строка для добавления в `Cartfile`:

```
github «webim/webim-client-sdk-ios» ~> 3.9.0
```

3.9.0 – это минимальная версия, поддерживающая `Carthage`. Вы также можете использовать и более новые версии.

### Swift Package Manager

    1. Выберите File > Swift Packages > Add Package Dependency;

    1. Введите https://github.com/webim/webim-client-sdk-ios в диалоговом окне "Choose Package Repository";

    На следующей странице укажите нужную версию `webim-client-sdk-ios`;

    1. После проверки совместимости зависимостей добавьте библиотеку "WebimMobileSDK" в проект.


### Objective-C

Интегрируете **Webim Mobile SDK** в Objective-C-приложение? Попробуйте нашу обертку – [`WebimClientLibraryWrapper`](https://github.com/webim/webim-client-sdk-ios-wrapper).

---

## Пример приложения

Чтобы запустить пример, «склонируйте» репозиторий и выполните команду `pod install` из директории `Example`.

Если у вас не установлен `CocoaPods`, перед этим необходимо их установить командой в терминале:

`sudo gem install cocoapods`

## Использование

В отличие от веб-интерфейса, мобильное приложение на **Webim Mobile SDK** не проверяет наличие доступных (онлайн) операторов. Иными словами, мобильный чат всегда исходит из того, что кнопка вызова оператора всегда находится в статусе «онлайн». **Webim Mobile SDK** всегда позволяет начать чат, однако, если отсутствуют операторы, готовые ответить в этом чате, то клиент будет находиться в чате один до тех пор, пока такой оператор появится или чат будет закрыт по тайм-ауту.

**Webim** поддерживает подключение к **Webim Server** нескольких разных мобильных приложений на iOS к одной учетной записи заказчика.

**Webim Mobile SDK для iOS** поддерживает выбор размещения при создании чата. Мы рекомендуем всегда создавать как минимум одно отдельное размещение для мобильного приложения. Если мобильных приложений несколько, минимум одно размещение для каждого МП.

Взаимодействие с чатом проходит в рамках сессии, которая создается в тот момент, когда МП собирается предложить пользователю чат. Для работы с ней используется объект `WebimSession`.

### `WebimSession`

Использование функционала библиотеки начинается с создания объекта сессии.
Метод класса **Webim** `newSessionBuilder()` возвращает объект класса-строителя `SessionBuilder` (оба класса и их методы описаны в файле `Webim.swift`). После, на созданном объекте `SessionBuilder` вызываются методы, задающие параметры сессии. После задания всех необходимых параметров на этом объекте запускается метод `build()`, который возвращает объект `WebimSession`.

Типичный пример использования:

```
let webimSession =
    try Webim.newSessionBuilder().set(accountName: ACCOUNT_NAME).set(location: LOCATION_NAME).build()
```

Где `ACCOUNT_NAME` – название вашего аккаунта в системе **Webim**, а `LOCATION_NAME` – название размещения, которое необходимо использовать в мобильном приложении.

Описание всех параметров, которые можно задать при создании сессии, а также ошибок, которые могут возникать в процессе, можно найти в файле `Webim.swift`. Обязательными из параметров являются только два – имя аккаунта и размещение.

После создании сессии, ее необходимо запустить методом `resume()` (т. к. объект сессии изначально создается приостановленным).
При необходимости сессию можно приостанавливать (метод `pause()`) и возобновлять (метод `resume()`), а также деактивировать (метод `destroy()`) – все эти методы описаны в файле `WebimSession.swift`.

### `MessageStream`

Все методы, касающиеся потока сообщений, описаны в файле `MessageStream.swift`.
Для использования этих методов необходимо получить объект `MessageStream`. Это достигается методом `getStream()` экземпляра `WebimSession`.

Примеры методов:

  * `send(message:)` – отправить сообщение,

  * `rateOperatorWith(id:byRating:)` – оценить оператора.

### `MessageTracker`

Метод `newMessageTracker(messageListener:)` объекта `MessageStream` создает объект класса `MessageTracker`, с помощью которого можно управлять потоком сообщений в контексте приложения клиента.
Например, метод `getNextMessages(byLimit:completion:)` запрашивает определенное количество сообщений из истории сообщений.

Описание методов экземпляра `MessageTracker` можно найти в файле `MessageTracker.swift`.

### `MessageListener`

Протокол `MessageListener` описывает методы, позволяющие отследить изменения в потоке сообщений. В пользовательском приложении необходим класс, который реализует методы данного протокола: `added(message:after:)`, `removed(message:)`, `removedAllMessages()`, `changed(message:to:)`. Эти методы автоматически вызываются при добавлении сообщения, удаления сообщения, удаления всех сообщений и изменении сообщения, соответственно.

Полные описания методов можно найти в файле `MessageListener.swift`.


### `Message`

Методы протокола `MessageListener` оперируют объектами `Message`, описанном в файле `Message.swift`.
С помощью методов экземпляров класса `Message` можно получить все необходимые данные о конкретном сообщении: уникальный номер сообщения (метод `getID()`), текст сообщения (метод `getText()`), информацию о вложенном файле (метод `getAttachment()`) и т. д.

!!! Note "N.B."
    Фотографии, сделанные на iOS-устройстве в форматах **HEIC/HEIF**, перед отправкой конвертируются Webim Mobile SDK для iOS в формат `jpeg`. Это связано с тем, что сервис Webim и интерфейс оператора не поддерживают отображение файлов в форматах **HEIC/HEIF**, даже если соответствующие расширения добавлены в `allowed_upload_file_types` на стороне сервера. В системе всегда хранится и отображается уже сконвертированный `jpeg`-файл, исходный **HEIC/HEIF** в Webim не загружается.

Все связанные с этим классом инструменты (методы для работы с вложениями, типы сообщений и пр.) также описаны в файле `Message.swift`.

### Дополнительные возможности

В файле `Operator.swift` описаны методы для получения информации о том или ином операторе. Конкретный объект оператора можно получить методом `getCurrentOperator()` объекта `MessageStream`.

В файле `WebimPushNotification.swift` описаны методы для работы с push-уведомлениями, получаемыми от сервиса **Webim**.
Объект конкретного уведомления можно получить методом `parse(remoteNotification:)` класса **Webim**. У этого же класса также имеется метод `isWebim(remoteNotification:)`, который позволяет легко узнать, было ли отправлено push-уведомление сервисом **Webim** или каким-либо другим сервисом.

В файле `FatalErrorHandler.swift` имеется описание протокола `FatalErrorHandler`, методы которого могут быть реализованы конкретным мобильным приложением для отслеживания возникающих в процессе работы ошибок. Все конкретные ошибки описаны в файле `WebimError.swift`.

В файле `MessageStream.swift` имеются описания дополнительных протоколов, методы которых могут реализовывать классы приложения для отслеживания тех или иных специфических событий. Например, методы протокола `ChatStateListener` реагируют на изменения состояния чата (описания возможных состояний чата имеются в этом же файле).

### Push-уведомления

Для включения push-уведомлений необходимо предоставить APNS-сертификаты ваших мобильных приложений. При этом одновременно можно использовать один из комплектов сертификатов: для разработки (`dev`) и для продуктива (`dist`). Они могут как совпадать, так и отличаться (один сертификат и для версии для разработчиков, так и для продуктивной версии). Каждый комплект состоит из двух файлов: `cert` (собственно сертификат) и `private_key` (приватный ключ к данному сертификату). Возможно также отключение как одного, так и другого комплекта сертификатов через настройки `account config`. Для размещения сертификатов на сервере **Webim** и изменения настроек `account config` свяжитесь, пожалуйста, с нашей службой поддержки.

Итоговые имена файлов сертификатов:

```
ios_push_cert.dev.pem
ios_push_private_key.dev.pem
ios_push_cert.dist.pem
ios_push_private_key.dist.pem
```
#### Бейдж приложения (iOS)

Значение `badge` в push-уведомлениях для iOS управляется параметром account config `sending_unread_messages_to_ios`.

  * По умолчанию параметр выключен — в `badge` отправляется `1` (как раньше).

  * При включении параметра в `badge` отправляется количество непрочитанных сообщений.

Параметр серверный; изменения в коде SDK не требуются. Применимо только к iOS.

Для автоматической обработки и отображения push-уведомлений в iOS, ваше приложение должно быть осведомлено о возможных типах уведомлений и присылаемых в них (уведомлениях) аргументах.

Тип push-уведомления определяется параметром `loc-key`. Список возможных типов и их особенности описаны в статье [Push-уведомления](https://webim.ru/kb/mobile/push-notifications/).

Значения массива аргументов (параметр `loc-args`):

  * для «`P.CR`» – массив пустой;

  * для «`P.OA`» – имя оператора;

  * для «`P.OF`» – имя оператора, название файла;

  * для «`P.OM`» – имя оператора, текст сообщения;

  * для «`P.RO`» – массив пустой;

  * для «`P.WM`» – массив пустой.

Пример обработки уведомления с помощью файла `Strings.localizable`:

`«P.OM» = «Получено новое сообщение от %@: %@.»`

---

## Заключение

Описанные выше сущности и их методы – это все, что необходимо для работы в мобильном приложении с сервисом **Webim**, и даже больше.
В данном руководстве описаны не все возможности данной библиотеки, поэтому после реализации в конкретном приложении необходимого минимума рекомендуется ознакомиться с полным перечнем протоколов и методов в публичных файлах библиотеки.

Публичные интерфейсы, классы и методы описаны в файлах (в алфавитном порядке):

  * `Department.swift`

  * `FatalErrorHandler.swift`

  * `Message.swift`

  * `MessageListener.swift`

  * `MessageStream.swift`

  * `MessageTracker.swift`

  * `NewMessageListener.swift`

  * `NotFatalErrorHandler.swift`

  * `Operator.swift`

  * `ProvidedAuthorizationTokenStateListener.swift`

  * `ServerSettings.swift`

  * `Survey.swift`

  * `UploadedFile.swift`

  * `Visitor.swift`

  * `Webim.swift`

  * `WebimAlert.swift`

  * `WebimError.swift`

  * `WebimLogger.swift`

  * `WebimNotFatalError.swift`

  * `WebimPushNotification.swift`

  * `WebimRemoteNotification.swift`

  * `WebimSession.swift`

Описание каждого класса, протокола, метода и т.д. можно найти в [справочнике](https://webim.ru/kb/mobile/sdk/v-3-0/ios-sdk-handbook.html).

### Дополнительная Информация

**Webim Mobile SDK** использует библиотеку [SQLite.swift](https://github.com/stephencelis/SQLite.swift).

Устанавливать отдельные зависимости в `Podfile` не нужно.

---

Источник: https://webim.ru/kb/mobile/sdk/v-3-0/ios-integration.html