Skip to content

README_RU.md

Latest commit

 

History

History
executable file
·
304 lines (245 loc) · 27.7 KB

README_RU.md

File metadata and controls

executable file
·
304 lines (245 loc) · 27.7 KB
Raw

UseDesk_SDK_Swift

https://img.shields.io/cocoapods/v/UseDesk_SDK_Swift.svg?style=flat-square

Демонстрационное приложение

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

Запуск демонстрационного проекта

Для запуска тестового проекта нужно:

  • Клонировать репозиторий
  • Запустить терминал
  • Перейти в директорию Example скачанного репозитория
  • Выполнить команду pod install

Добавление библиотеки в проект

CocoaPods

При добавлении в проект SDK с помощью CocoaPods доступно использование функциональности как с GUI, так и без него. Для установки:

  • Добавьте запись в Podfile вашего приложения
pod 'UseDesk_SDK_Swift'
  • Выполните команду в терминале pod update
  • Подключите библиотеку
import UseDesk

Swift Package Manager (SPM)

Реализация SDK для установки с помощью SPM вынесена в отдельный репозиторий. Обращаем внимание, что использование GUI при установке через SPM недоступно.

Инициализация Чата или Чата с Базой знаний с использованием графического интерфейса (GUI)

Параметры, используемые в конфигурации SDK с GUI

Где * — обязательный параметр

Переменная Тип Описание
CompanyID* String Идентификатор компании в Юздеске
Как найти ID компании
ChannelID* String Идентификатор канала чата, через который в Юздеск будут поступать обращения из приложения
Как создать и настроить канал
Url* String Адрес сервера для работы с чатами SDK
Стандартное значение: pubsubsec.usedesk.ru
Если вы используете коробочную версию Юздеска на собственном сервере, то этот параметр у вас может отличаться. Уточните актуальный адрес у поддержки — support@usedesk.ru
Port String Порт сервера для работы с чатами SDK
Стандартное значение: 443
UrlAPI* String URL для работы с API
Стандартное значение: secure.usedesk.ru/uapi
Если вы используете коробочную версию Юздеска на собственном сервере, то этот параметр у вас будет отличаться. Уточните актуальный адрес у поддержки — support@usedesk.ru
API_token String Ключ для доступа к API Юздеска
Как получить API ключ
UrlToSendFile String Адрес для отправки файлов
Стандартное значение: https://secure.usedesk.ru/uapi/v1/send_file
KnowledgeBaseID String Идентификатор базы знаний
Как создать Базу знаний
Если ID не указан, база знаний не используется
KnowledgeBaseSectionId String Идентификатор раздела базы знаний
Данный идентификатор можно найди в URL раздела вашей Базы знаний
При указании этого параметра при открытии базы знаний будет открыт указанный раздел
knowledgeBaseCategoryId String Идентификатор категории базы знаний
Данный идентификатор можно найди в URL категории вашей Базы знаний
При указании этого параметра при открытии базы знаний будет открыта указанная категория
knowledgeBaseArticleId String Идентификатор статьи базы знаний
Данный идентификатор можно найди в URL статьи вашей Базы знаний
При указании этого параметра при открытии базы знаний будет открыта указанная статья
isReturnToParentFromKnowledgeBase Bool Флаг, задающий поведение кнопки «Назад» в базе знаний, если указана отдельная категория, раздел или статья
Значение по-умолчанию: false
Если указан true, то при нажатии на кнопку назад будет закрываться вся база знаний
Name String Имя клиента
Email String Почта клиента
Phone String Телефон клиента
Avatar Data? Изображение аватара клиента
AvatarUrl URL? URL изображения аватара клиента
Приоритет имеет параметр Avatar
Token String Подпись, однозначно идентифицирующая пользователя и его чат
Токен выдается в коллбэке после инициализации чата и привязывается к связке почта-телефон-имя пользователя.
Для идентификации различных пользователей на одном устройстве вы должны хранить и передавать полученный токен в метод инициализации
AdditionalId String Дополнительный идентификатор клиента
Note String Текст заметки
AdditionalFields [Int : String] Массив дополнительный полей запроса
Формат: id : "значение"
Для текстовых полей значение - строка, для списка - строка с точно совпадающим значением списка, для флага - строка false или true
AdditionalNestedFields [[Int : String]] Массив дополнительных полей типа вложенный список
Каждый подмассив представляет один вложенный список.
Формат вложенного списка: [id1: "значение", id2 : "значение", id3 : "значение"], где id1, id2, id3 — идентификаторы значений по уровням вложенности
NameOperator String Имя оператора
Если указано, то вместо имени агента в переписке будет отображаться указанная строка
NameChat String Название чата
Отображается в шапке
FirstMessage String Автоматическое сообщение
Отправится сразу после инициализации от имени клиента
CountMessagesOnInit Int Количество загружаемых сообщений при открытии чата
При открытии чата загружается указанное количество сообщений. По мере прокрутки чата подгружается по 20 сообщений
LocaleIdentifier String Идентификатор языка
Доступные языки: русский (ru), английский (en), португальский (pt), испанский (es).
Если переданный идентификатор не поддерживается, будет использоваться русский язык
CustomLocale [String : String] Свой словарь переводов
Если SDK нужно показывать на языке, который мы не поддерживаем, можно самостоятельно создать словарь переводов и использовать его
Storage UDStorage Хранилище, поддерживающее протокол UDStorage
Для каждого отдельного чата нужно передавать свое отдельное хранилище
isCacheMessagesWithFile Bool Флаг сохранения сообщений с файлами в кэше
Стандартное значение: true
Если указан true, то файлы сохраняются в кэше. Если false, то файлы не сохраняются в кэш
isSaveTokensInUserDefaults Bool Флаг сохранения токена пользователя в UserDefaults приложения
Стандартное значение: true
Если указан true, то токен будет храниться в текущем устройстве. Недостатки такого подхода — при переустановке приложения, смене устройства или платформы доступ к переписке будет утрачен.
Для сохранения доступа к переписке клиента с других устройств и платформ, токен необходимо хранить в вашей системе и передавать его при инициализации. В этом случае нужно использовать значение параметра false
isPresentDefaultControllers Bool Флаг автоматического отображения контроллера в указанном родительском контроллере
Стандартное значение: true
PresentIn UIViewController Контроллер, в котором нужно открывать SDK

Инициализация чата и чата вместе с Базой знаний (GUI)

Не производите инициализацию библиотеки в методе viewDidLoad()

let usedesk = UseDeskSDK()
usedesk.start(
    withCompanyID: "1234567", 
    chanelId: "1234", 
    url: "pubsubsec.usedesk.ru", 
    port: "443",
    urlAPI: "secure.usedesk.ru", 
    api_token: "143ed59g90ef093s",
    urlToSendFile: "https://secure.usedesk.ru/uapi/v1/send_file", 
    knowledgeBaseID: "12", 
    knowledgeBaseSectionId: "0",
    knowledgeBaseCategoryId: "0",
    knowledgeBaseArticleId: "0",
    isReturnToParentFromKnowledgeBase: true,
    name: "Name", 
    email: "lolo@yandex.ru", 
    phone: "89000000000", 
    avatar: avatarData,
    token: "Token", 
    additional_id: "additional_id",
    note: "Note text", 
    additionalFields: [1 : "value"], 
    additionalNestedFields: [[1 : "value1", 2 : "value2", 3 : "value3"]],
    nameOperator: "NameOperator", 
    nameChat: "NameChat", 
    firstMessage: "message",
    сountMessagesOnInit: 30,
    localeIdentifier: "en", 
    customLocale: customLocaleDictionary, 
    storage: UDStorage(),
    isCacheMessagesWithFile: false,
    isSaveTokensInUserDefaults: true, 
    isPresentDefaultControllers: true, 
    presentIn: self,
    connectionStatus: { success, feedbackStatus, token in },
    errorStatus: { udError, description in }
)

Параметры, которые возвращает блок

СonnectionStatus

Тип Описание
Bool Успешность подключения к чату
UDFeedbackStatus Статус показа формы обратной связи
String Токен пользователя

ErrorStatus

Тип Описание
UDError Задокументированый тип ошибки
String? Описание ошибки

Инициализация Базы знаний без использования чата с использованием графического интерфейса (GUI)

SDK предоставляет реализовать в вашем приложении Базу знаний без встраивания чата.

В выбранный метод, помимо остальный обязательных параметров, можно передать идентификатор раздела, категории или статьи. При этом после инициализации SDK откроется указанный раздел, категория или статья, из которой можно будет вернуться назад в соответстие с иерархией Базы знаний. Если одновременно указать идентификатор раздела, категории и(или) статьи, то мы покажем самую глубокую сущность.

Параметры, используемые в конфигурации SDK с GUI

Где * — обязательный параметр

Переменная Тип Описание
UrlAPI* String URL для работы с API
Стандартное значение: secure.usedesk.ru/uapi
Если вы используете коробочную версию Юздеска на собственном сервере, то этот параметр у вас будет отличаться. Уточните актуальный адрес у поддержки — support@usedesk.ru
API_token* String Ключ для доступа к API Юздеска
Как получить API ключ
KnowledgeBaseID* String Идентификатор базы знаний
Как создать Базу знаний
Если ID не указан, база знаний не используется
KnowledgeBaseSectionId String Идентификатор раздела базы знаний
Данный айди можно найди в ссылка на раздел
При указании этого параметра при открытии базы знаний будет открыт раздел с указанным айди
knowledgeBaseCategoryId String Идентификатор категории базы знаний
Данный айди можно найди в ссылка на категорию
При указании этого параметра при открытии базы знаний будет открыта категория с указанным айди
knowledgeBaseArticleId String Идентификатор статьи базы знаний
Данный айди можно найди в ссылка на статью
При указании этого параметра при открытии базы знаний будет открыта статья с указанным айди
isReturnToParentFromKnowledgeBase Bool Флаг, задающий поведение кнопки «Назад» в базе знаний, если указана отдельная категория, раздел или статья
Значение по-умолчанию: false
Если указан true, то при нажатии на кнопку назад будет закрываться вся база знаний
Name String Имя клиента
Email String Почта клиента
Phone String Телефон клиента
LocaleIdentifier String Идентификатор языка
Доступные языки: русский (ru), английский (en), португальский (pt), испанский (es).
Если переданный идентификатор не поддерживается, будет использоваться русский язык
CustomLocale [String : String] Свой словарь переводов
Если SDK нужно показывать на языке, который мы не поддерживаем, можно самостоятельно создать словарь переводов и использовать его
isPresentDefaultControllers Bool Флаг автоматического отображения контроллера в указанном родительском контроллере
Стандартное значение: true
PresentIn UIViewController Контроллер, в котором нужно открывать SDK

Инициализация SDK только с базой знаний с GUI

let usedesk = UseDeskSDK()
usedesk.startKnowledgeBase(
    urlAPI: "pubsubsec.usedesk.ru", 
    api_token: "143ed59g90ef093s",
    knowledgeBaseID: "12", 
    knowledgeBaseSectionId: "0",
    knowledgeBaseCategoryId: "0",
    knowledgeBaseArticleId: "0",
    isReturnToParentFromKnowledgeBase: true,
    name: "Name", 
    email: "lolo@yandex.ru", 
    phone: "89000000000", 
    localeIdentifier: "en", 
    customLocale: customLocaleDictionary, 
    isPresentDefaultControllers: true, 
    presentIn: self,
    connectionStatus: { success in },
    errorStatus: { udError, description in }
)

Параметры, которые возвращает блок

СonnectionStatus

Тип Описание
Bool Успешность открытия базы знаний

ErrorStatus

Тип Описание
UDError Задокументированый тип ошибки
String? Описание ошибки

Инициализация SDK без графического интерфейса (GUI)

Параметры, используемые в конфигурации SDK без GUI

Где * — обязательный параметр

Переменная Тип Описание
CompanyID* String Идентификатор компании в Юздеске
Как найти ID компании
ChannelID* String Идентификатор канала чата, через который в Юздеск будут поступать обращения из приложения
Как создать и настроить канал
Url* String Адрес сервера для работы с чатами SDK
Стандартное значение: pubsubsec.usedesk.ru
Если вы используете коробочную версию Юздеска на собственном сервере, то этот параметр у вас может отличаться. Уточните актуальный адрес у поддержки — support@usedesk.ru
Port String Порт сервера для работы с чатами SDK
Стандартное значение: 443
UrlAPI* String URL для работы с API
Стандартное значение: secure.usedesk.ru/uapi
Если вы используете коробочную версию Юздеска на собственном сервере, то этот параметр у вас будет отличаться. Уточните актуальный адрес у поддержки — support@usedesk.ru
API_token String Ключ для доступа к API Юздеска
Как получить API ключ
KnowledgeBaseID String Идентификатор базы знаний
Как создать Базу знаний
Если ID не указан, база знаний не используется
UrlToSendFile String Адрес для отправки файлов
Стандартное значение: https://secure.usedesk.ru/uapi/v1/send_file
Name String Имя клиента
Email String Почта клиента
Phone String Телефон клиента
Avatar Data? Изображение аватара клиента
AvatarUrl URL? URL изображения аватара клиента
Приоритет имеет параметр Avatar
Token String Подпись, однозначно идентифицирующая пользователя и его чат
Токен выдается в коллбэке после инициализации чата и привязывается к связке почта-телефон-имя пользователя.
Для идентификации различных пользователей на одном устройстве вы должны хранить и передавать полученный токен в метод инициализации
AdditionalId String Дополнительный идентификатор клиента
Note String Текст заметки
AdditionalFields [Int : String] Массив дополнительный полей запроса
Формат: id : "значение"
Для текстовых полей значение - строка, для списка - строка с точно совпадающим значением списка, для флага - строка false или true
AdditionalNestedFields [[Int : String]] Массив дополнительных полей типа вложенный список
Каждый подмассив представляет один вложенный список.
Формат вложенного списка: [id1: "значение", id2 : "значение", id3 : "значение"], где id1, id2, id3 — идентификаторы значений по уровням вложенности
FirstMessage String Автоматическое сообщение
Отправится сразу после инициализации от имени клиента
CountMessagesOnInit Int Количество загружаемых сообщений при открытии чата
При открытии чата загружается указанное количество сообщений. По мере прокрутки чата подгружается по 20 сообщений
LocaleIdentifier String Идентификатор языка
Доступные языки: русский (ru), английский (en), португальский (pt), испанский (es).
Если переданный идентификатор не поддерживается, будет использоваться русский язык
CustomLocale [String : String] Свой словарь переводов
Если SDK нужно показывать на языке, который мы не поддерживаем, можно самостоятельно создать словарь переводов и использовать его
isSaveTokensInUserDefaults Bool Флаг сохранения токена пользователя в UserDefaults приложения
Стандартное значение: true
Если указан true, то токен будет храниться в текущем устройстве. Недостатки такого подхода — при переустановке приложения, смене устройства или платформы доступ к переписке будет утрачен.
Для сохранения доступа к переписке клиента с других устройств и платформ, токен необходимо хранить в вашей системе и передавать его при инициализации. В этом случае нужно использовать значение параметра false

Инициализация SDK без GUI

let usedesk = UseDeskSDK()
usedesk.startWithoutGUICompanyID(
    companyID: "1234567",
    chanelId: "1234", 
    url: "pubsubsec.usedesk.ru", 
    port: "443",
    urlAPI: "secure.usedesk.ru", 
    api_token: "143ed59g90ef093s",
    urlToSendFile: "https://secure.usedesk.ru/uapi/v1/send_file", 
    knowledgeBaseID: "12",
    name: "Name", 
    email: "lolo@yandex.ru", 
    phone: "89000000000", 
    avatar: avatarData,
    token: "Token", 
    additional_id: "additional_id",
    note: "Note text", 
    additionalFields: [1 : "value"], 
    additionalNestedFields: [[1 : "value1", 2 : "value2", 3 : "value3"]], 
    firstMessage: "message",
    сountMessagesOnInit: 30,
    localeIdentifier: "en", 
    customLocale: customLocaleDictionary,
    isSaveTokensInUserDefaults: true,
    connectionStatus: { success, feedbackStatus, token in },
    errorStatus: { udError, description in }
)

Параметры, которые возвращает блок

СonnectionStatus

Тип Описание
Bool Успешность подключения к чату
UDFeedbackStatus Статус показа формы обратной связи
String Токен пользователя

ErrorStatus

Тип Описание
UDError Задокументированый тип ошибки
String? Описание ошибки

Документация

Методы для работы с SDK, кастомизация элементов, а также ошибки описаны в нашей документации: http://sdk.usedocs.ru

Авторы

Сергей, kon.sergius@gmail.com

Максим, ixotdog@gmail.com

License

UseDesk_SDK_Swift is available under the MIT license. See the LICENSE file for more info