Настройка SDK для iOS

Самый простой способ добавить библиотеки Chat2Desk в ваш проект Xcode – использование Cocoapods.

Старт с помощью Cocoapods

1. Установите CocoaPods (см. руководство по началу работы с CocoaPods).

2. Если у вас нет Podfile, создайте его, запустив pod init в каталоге проекта.

3. Добавьте зависимость Chat2Desk в Podfile.
   
   platform :ios, '9.0'

target 'SDK Demo' do
   use_frameworks!
   pod 'chat2desk_sdk'
end

4. Запустите команду pod install в каталоге проекта, чтобы установить SDK.

5. Откройте свой проект через только что созданный файл .xcworkspace.

Инициализация SDK

Для начала объявите Background modes. Перейдите к основному файлу вашего проекта, вкладке Singing & Capabilities, нажмите кнопку «+»  и выберите Background modes.

Теперь вы готовы создать экземпляр клиента Chat2Desk. Для этого импортируйте chat2desk_sdk в свой класс swift и создайте экземпляр IChat2Desk, как показано ниже:

let settings = Settings.init(
    authToken: "WIDGET_TOKEN",
    baseHost: "BASE_HOST",
    wsHost: "WS_HOST",
    storageHost: "STORAGE_HOST"
)
let chat2desk = Chat2Desk.Companion().create(settings: settings)

WIDGET_TOKEN, BASE_HOST, WS_HOST, STORAGE_HOST необходимо взять со страницы Настройки > Виджет + Онлайн-чат для конкретного подключенного канала.

Удаление SDK

Используйте метод IChat2Desk.close перед удалением экземпляра IChat2Desk для предотвращения утечек памяти.

Подключение и отключение

Используйте метод IChat2Desk.start для подключения к сервису и IChat2Desk.stop для отключения от него.

Отслеживать статус подключения можно через свойство watchConnectionStatus(): СFlow<ConnectionState>.

Обратитесь к этому примеру кода, чтобы понять, как это работает:

class SomeClass: ObservableObject {
    @Published public var connectionStatus: ConnectionState? = nil
    
    let chat2desk: Chat2Desk
    
    var connectionStatusWatcher: Closeable?
    
    init(chat2desk: Chat2Desk) {
        self.chat2desk = chat2desk
        
        connectionStatusWatcher = chat2desk.watchConnectionStatus().watch { status in
            self.connectionStatus = status
        }
    }
    
    func start() {
        Task {
            try await chat2desk.start()
        }
    }
    
    func stop() {
        Task {
            try await chat2desk.stop()
        }
    }
    
    deinit {
        connectionStatusWatcher?.close()
    }
}

Получение сообщений

Для работы с сообщениями необходимо, чтобы библиотека была подключена к сервису Chat2Desk.

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

Для получения списка сообщений необходимо использовать свойство watchMessages(): CFlow<[Message]>

chat2desk.watchMessages.watch { messages in
    print(messages)
}

Выгрузка сообщений с сервера

Для работы с сообщениями необходимо, чтобы библиотека была подключена к сервису Chat2Desk.

ВАЖНО: За раз СДК выгружает с сервера максимум 100 сообщений.

• chat2desk.fetchMessages() – получение списка последних сообщений. Выгружает 100 сообщений.
• chat2desk.fetchNewMessages() позволяет получить список новых сообщений. SDK загружает с сервера только те сообщения, которые были отправлены после последнего сообщения, полученного вашим устройством.
• chat2desk.fetchMessage(loadMore: true) – получение списка старых сообщений. В этом случае выгружаются с сервера сообщения старше первого, но не более чем 100 за раз.

Поиск сообщений

Есть два способа поиска сообщений: полнотекстовый и поиск через операторов. Оба способа позволяют искать сообщения по свойству Message.text и возвращают список сообщений [Message].

Полнотекстовый поиск

chat2desk.fullTextSearch(query: String): [Message]

Слова в запросе преобразуются в лексемы с помощью токенизатора по следующим правилам:

• Токены могут состоять только из символов ASCII и дополнения Latin-1 (западные языки). Все остальные символы считаются пробелами.
• Слова, разделенные дефисом (-), разделяются на два токена. Например, full-text разделяется на full и text.
• Токены не чувствительны к диакритическим знакам и регистру.

Вы можете искать целое слово или фразу или ограничить результаты с помощью следующих символов:

• Исключите результаты для слова, поставив перед ним дефис «-». Например, fiction -science включает все результаты поиска по слову fiction и исключает те, которые содержат слово science.
• Вы можете указать префиксы, поставив символ * в конце слова. Например, fict* будет включать все результаты поиска для fiction и fictitious. Пока SDK не поддерживает поиск по суффиксам.

Поиск через операторы

chat2desk.searchByQuery(query: String, options: SearchOptions?): [Message]

SearchOptions.init(
  /**
    * Оператор поиска
    */
  operator: QueryStringOperator.contains, 
  /**
    * Чувствительность к регистру.
    * Только для символов ASCII и Latin-1 (западные языки)
    */
  caseSensitivity: false
)

enum QueryStringOperator {
    case beginswith
    case contains
    case endswith
    case like
    case equal
    case notequal
}

В настройках поиска можно указать оператора, с помощью которого будет осуществлен поиск сообщений.
 

Оператор	Описание
beginswith	Выражает true, если левое строковое выражение начинается с правого строкового выражения. Это похоже на contains, но совпадает только в том случае, если правое строковое выражение находится в начале левого строкового выражения.
contains	Выражает true, если правое строковое выражение встречается в любом месте левого строкового выражения.
endswith	Выражает true, если левое строковое выражение заканчивается правым строковым выражением. Это похоже на contains, но совпадает только в том случае, если левое строковое выражение находится в самом конце правого строкового выражения.
like	Выражает true, если левое строковое выражение совпадает с правым строковым выражением wildcard. Строковое выражение с подстановочным знаком - это строка, в которой используются обычные символы с двумя специальными символами подстановочного знака: символ * соответствует нулю или более любых символов. Подстановочный знак ? соответствует любому символу. Например, строка с подстановочным символом «d?g» соответствует словам «dog», «dig» и «dug», но не «ding», «dg» или «a dog».
equal	Выражает true, если левая строка лексикографически равна правой.
notequal	Выражает true, если левая строка не является лексикографически равной правой строке.

Отправка сообщений

Для работы с сообщениями необходимо, чтобы библиотека была подключена к сервису Chat2Desk.

1. Отправить сообщение: sendMessage(msg: String)

   chat2desk.sendMessage(msg: txt)

2. Отправить сообщение с вложением: sendMessage(msg: String, attachedFile: AttachedFile). Для отправки вложения создайте экземпляр класса AttachedFile и передайте его в метод.

   let attachedFile = AttachedFile.Companion().fromURL(url: url, originalName: originalName, mimeType: mimeType, fileSize: fileSize)
chat2desk.sendMessage(msg: txt, attachedFile: attachedFile)

3. Переотправить сообщение: resendMessage(message: Message).

   chat2desk.resendMessage(message: message)

Отправка информации о клиенте

Сервис позволяет отправить информацию о клиенте. По умолчанию доступны два поля name и phone.

chat2desk.sendClientParams(name: String, phone: String)

Также сервис передает список кастомных полей, определенных в компании customFields: CFlow<[CustomField]>.

var fields: [CustomField] = []

chat2desk.watchCustomFields().watch { customFields in
    self.fields = customFields?.compactMap({ $0 as? CustomField }) ?? []
}
let fieldSet: [KotlinInt: String] = [KotlinInt(value: self.fields[0].id): "value"]

Task {
  try await chat2desk.sendClientParams(name: "name", phone: "phone", fieldSet: fieldSet)
}

Остальные настройки

• Информация об операторе operator: CFlow<Operator?>

chat2desk.watchOperator().watch { operator in
  print(operator)
}

• Получение ошибок error: CFlow<Throwable?>

Демо

Swift SDK Demo – демонстрирует базовый функционал SDK.