UseDesk_SDK_Swift

This manual in other languages

Also available in Russian

Demo app

The "Example" folder of this repository contains a demo project that serves as an example of embedding the Usedesk chat SDK into a client application. You can use it to get acquainted with the basic functionality of the application and test the SDK.

Launching a demo project

To launch a demo project you need to:

Clone repository
Start terminal
Go to the Example folder of the cloned repository
Execute a command pod install

Adding a library to the project

CocoaPods

When you add an SDK to a project with CocoaPods, both GUI and non-GUI functionality is available. To install:

Add a Podfile entry to your application

pod 'UseDesk_SDK_Swift'

Run a command in the terminal pod update
Import library:

import UseDesk

Swift Package Manager (SPM)

The SDK implementation for installation using SPM is placed in a separate repository. Please note that GUI is not available when installing with SPM.

You may use an option with binary target in the SPM configuration.

Install xcodegen:
- brew install xcodegen
Generate xcodeproj:
- xcodegen generate
Install pods
- pod install
Build xcframework:

xcodebuild archive \
    -workspace UseDesk_SDK_Swift.xcworkspace \
    -scheme UseDesk_SDK_Swift \
    -destination="generic/platform=iOS" \
    -sdk iphoneos \
    -archivePath "build/UseDesk_SDK_Swift-ios" \
    SKIP_INSTALL=NO BUILD_LIBRARIES_FOR_DISTRIBUTION=YES \
&& \
xcodebuild archive \
    -workspace UseDesk_SDK_Swift.xcworkspace \
    -scheme UseDesk_SDK_Swift \
    -destination="simulator" \
    -sdk iphonesimulator \
    -archivePath "build/UseDesk_SDK_Swift-simulator" \
    SKIP_INSTALL=NO BUILD_LIBRARIES_FOR_DISTRIBUTION=YES

xcodebuild -create-xcframework \
    -archive build/UseDesk_SDK_Swift-ios.xcarchive \
    -archive build/UseDesk_SDK_Swift-simulator.xcarchive \
    -framework UseDesk_SDK_Swift.framework \
    -output build/UseDesk_SDK_Swift.xcframework

Archive xcframework:
- cd build && zip -r UseDesk_SDK_Swift.zip UseDesk_SDK_Swift/*
Use binary target in Package.swift:

.binaryTarget(
    name: "UseDesk_SDK_Swift",
    path: "path/to/some/UseDesk_SDK_Swift.zip",
    checksum: "The checksum of the ZIP archive that contains the XCFramework."
),

Initializing a Chat or Knowledge Base with Chat using the GUI

Parameters used in the configuration SDK with GUI

Where * — required parameter

Parameter	Type	Description
CompanyID*	String	Company ID in Usedesk How to find a company ID
ChannelID*	String	ID of the chat channel through which messages from the application will be placed at Usedesk How to create and set up a channel
Url*	String	Server URL for SDK chats By default: `pubsubsec.usedesk.ru` If you use server version of Usedesk on your own server, value may be different for you. Check with support for valid URL — [email protected]
Port	String	Server port for SDK chats By default: `443`
UrlAPI*	String	URL to work with Usedesk API By default: `secure.usedesk.ru/uapi` If you use server version of Usedesk on your own server, value may be different for you. Check with support for valid URL — [email protected]
API_token	String	Usedesk API Token How to get API Token
UrlToSendFile	String	URL for sending files By default: `https://secure.usedesk.ru/uapi/v1/send_file`
KnowledgeBaseID	String	Knowledge Base ID How to create a Knowledge Base If ID is not provided, Knowledge Base will not be used
KnowledgeBaseSectionId	String	Knowledge Base section ID This ID can be found in the URL of your Knowledge Base section If this parameter is specified, the specified section will be opened when opening the knowledge base
knowledgeBaseCategoryId	String	Knowledge Base category ID This ID can be found in the URL of your Knowledge Base category If this parameter is specified, the specified category will be opened when opening the knowledge base
knowledgeBaseArticleId	String	Knowledge Base article ID This ID can be found in the URL of your Knowledge Base article If this parameter is specified, the specified article will be opened when opening the knowledge base
isReturnToParentFromKnowledgeBase	Bool	Flag which specifies the behaviour of the “Back” button of Knowledge Base if an individual category, section or article is specified Default value: `false` If `true`, pressing the “Back” button will close the entire Knowledge Base
Name	String	Client name
Email	String	Client email
Phone	String	Client phone
Avatar	Data?	Client avatar
AvatarUrl	URL?	URL of client avatar image Avatar parameter has higher priority
Token	String	A unique token that uniquely identifies the user and his conversation The token is provided in the callback after the initialization of the chat and is linked to the mail-phone-user name. To identify different users on the same device, you must store and pass the received token to the initialization method
AdditionalId	String	Additional customer ID
Note	String	Text of note
AdditionalFields	Int : String	Array of ticket additional fields Format: `id : "value"` For text fields the value is a string, for a list the value is a string with the exact list value, for a flag the value is a string `false` or `true`
AdditionalNestedFields	Int : String	Array of additional fields of nested list type Each subarray represents one nested list. Format of nested list: `[id1: "value", id2 : "value", id3 : "value"]`, where `id1`, `id2`, `id3` — value identifiers by nesting levels
NameOperator	String	Name of agent If specified, the string will be displayed instead of the agent's name in the conversation
NameChat	String	Chat name Displays in the header
FirstMessage	String	Automatic message Sent immediately after initialization on behalf of the client
CountMessagesOnInit	Int	Number of loaded messages when starting the chat When client open a chat, a specified number of messages are loaded. As client scrolls chat, 20 more messages are loaded
LocaleIdentifier	String	Language Identifier Available languages: Russian (`ru`), English (`en`), Portugiese (`pt`), Spanish (`es`). If passed identifier is not supported, the Russian language will be used
CustomLocale	String : String	Your own translation dictionary If the SDK needs to be displayed in a language we do not support, you can create a translation dictionary yourself and use it
Storage	UDStorage	Storage that supports UDStorage protocol Each individual chat must be given its own separate storage
isCacheMessagesWithFile	Bool	Flag to store messages with files in cache By default: `true` If `true`, files will be stored in the cache. If `false`, files won't be stored in the cache
isSaveTokensInUserDefaults	Bool	Flag to store user token in UserDefaults of the application By default: `true` If `true`, the token will be stored in the current device. The disadvantages of this approach are that if you reinstall the application, change device or platform, access to your correspondence will be lost. To preserve access to client conversations from other devices and platforms, the token must be stored on your system and transferred during initialization. In this case, you must use the value of the parameter `false`
isPresentDefaultControllers	Bool	The flag of automatic display of the controller in the specified parent controller By default: `true`
PresentIn	UIViewController	Controller in which the SDK must be opened

Initializing chat and chat with the Knowledge Base (GUI)

Do not initialize the library in the viewDidLoad() method

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: "[email protected]", 
    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 }
)

Parameters returned by the block

СonnectionStatus

Type	Description
Bool	Successful connection to the chat
UDFeedbackStatus	Feedback form display status
String	User token

ErrorStatus

Type	Description
UDError	Documented error type
String?	Error description

Initializing the Knowledge Base without chat using the GUI

The SDK allows you to implement the Knowledge Base in your application without embedding chat.

In the selected method, in addition to the other required parameters, you can pass the identifier of the section, category or article. In this case, after SDK initialization, the specified section, category or article will open, from which you can go back according to the hierarchy of the Knowledge Base. If you specify the identifier of the section, category and/or article at the same time, we will show the deepest entity.

Parameters used in SDK configuration with GUI

Where * — required parameter

Parameter	Type	Description
UrlAPI*	String	URL to work with Usedesk API By default: `secure.usedesk.ru/uapi` If you use server version of Usedesk on your own server, value may be different for you. Check with support for valid URL — [email protected]
API_token	String	Usedesk API Token How to get API Token
KnowledgeBaseID	String	Knowledge Base ID How to create a Knowledge Base If ID is not provided, Knowledge Base will not be used
KnowledgeBaseSectionId	String	Knowledge Base section ID This ID can be found in the URL of your Knowledge Base section If this parameter is specified, the specified section will be opened when opening the knowledge base
knowledgeBaseCategoryId	String	Knowledge Base category ID This ID can be found in the URL of your Knowledge Base category If this parameter is specified, the specified category will be opened when opening the knowledge base
knowledgeBaseArticleId	String	Knowledge Base article ID This ID can be found in the URL of your Knowledge Base article If this parameter is specified, the specified article will be opened when opening the knowledge base
isReturnToParentFromKnowledgeBase	Bool	Flag which specifies the behaviour of the “Back” button of Knowledge Base if an individual category, section or article is specified Default value: `false` If `true`, pressing the “Back” button will close the entire Knowledge Base
Name	String	Client name
Email	String	Client email
Phone	String	Client phone
LocaleIdentifier	String	Language Identifier Available languages: Russian (`ru`), English (`en`), Portugiese (`pt`), Spanish (`es`). If passed identifier is not supported, the Russian language will be used
CustomLocale	String : String	Your own translation dictionary If the SDK needs to be displayed in a language we do not support, you can create a translation dictionary yourself and use it
isPresentDefaultControllers	Bool	The flag of automatic display of the controller in the specified parent controller By default: `true`
PresentIn	UIViewController	Controller in which the SDK must be opened

Initializing the SDK with the GUI, Knowledge Base only

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: "[email protected]", 
    phone: "89000000000", 
    localeIdentifier: "en", 
    customLocale: customLocaleDictionary, 
    isPresentDefaultControllers: true, 
    presentIn: self,
    connectionStatus: { success in },
    errorStatus: { udError, description in }
)

Parameters returned by the block

СonnectionStatus

Type	Description
Bool	The success of opening a Knowledge Base

ErrorStatus

Type	Description
Bool	Successful connection to the chat
UDFeedbackStatus	Feedback form display status

Initializing SDK without GUI

Parameters used in the SDK configuration without GUI

Where * — required parameter

Parameter	Type	Description
CompanyID*	String	Company ID in Usedesk How to find a company ID
ChannelID*	String	ID of the chat channel through which messages from the application will be placed at Usedesk How to create and set up a channel
Url*	String	Server URL for SDK chats By default: `pubsubsec.usedesk.ru` If you use server version of Usedesk on your own server, value may be different for you. Check with support for valid URL — [email protected]
Port	String	Server port for SDK chats By default: `443`
UrlAPI*	String	URL to work with Usedesk API By default: `secure.usedesk.ru/uapi` If you use server version of Usedesk on your own server, value may be different for you. Check with support for valid URL — [email protected]
API_token	String	Usedesk API Token How to get API Token
UrlToSendFile	String	URL for sending files By default: `https://secure.usedesk.ru/uapi/v1/send_file`
KnowledgeBaseID	String	Knowledge Base ID How to create a Knowledge Base If ID is not provided, Knowledge Base will not be used
Name	String	Client name
Email	String	Client email
Phone	String	Client phone
Avatar	Data?	Client avatar
AvatarUrl	URL?	URL of client avatar image Avatar parameter has higher priority
Token	String	A unique token that uniquely identifies the user and his conversation The token is provided in the callback after the initialization of the chat and is linked to the mail-phone-user name. To identify different users on the same device, you must store and pass the received token to the initialization method
AdditionalId	String	Additional customer ID
Note	String	Text of note
AdditionalFields	Int : String	Array of ticket additional fields Format: `id : "value"` For text fields the value is a string, for a list the value is a string with the exact list value, for a flag the value is a string `false` or `true`
AdditionalNestedFields	Int : String	Array of additional fields of nested list type Each subarray represents one nested list. Format of nested list: `[id1: "value", id2 : "value", id3 : "value"]`, where `id1`, `id2`, `id3` — value identifiers by nesting levels
FirstMessage	String	Automatic message Sent immediately after initialization on behalf of the client
CountMessagesOnInit	Int	Number of loaded messages when starting the chat When client open a chat, a specified number of messages are loaded. As client scrolls chat, 20 more messages are loaded
LocaleIdentifier	String	Language Identifier Available languages: Russian (`ru`), English (`en`), Portugiese (`pt`), Spanish (`es`). If passed identifier is not supported, the Russian language will be used
CustomLocale	String : String	Your own translation dictionary If the SDK needs to be displayed in a language we do not support, you can create a translation dictionary yourself and use it
isSaveTokensInUserDefaults	Bool	Flag to store user token in UserDefaults of the application By default: `true` If `true`, the token will be stored in the current device. The disadvantages of this approach are that if you reinstall the application, change device or platform, access to your correspondence will be lost. To preserve access to client conversations from other devices and platforms, the token must be stored on your system and transferred during initialization. In this case, you must use the value of the parameter `false`

Initializing SDK without a 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: "[email protected]", 
    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 }
)

Parameters returned by the block

СonnectionStatus

Type	Description
Bool	Successful connection to the chat
UDFeedbackStatus	Feedback form display status
String	User token

ErrorStatus

Type	Description
UDError	Documented error type
String?	Error description

Documentation

Methods for working with the SDK, customization of elements, and errors are described in our documentation: http://sdk.usedocs.com

Authors

Sergey, [email protected]

Maksim, [email protected]

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 149 Commits
.swiftpm/xcode/package.xcworkspace		.swiftpm/xcode/package.xcworkspace
Core		Core
Example		Example
UseDesk		UseDesk
.gitignore		.gitignore
Info.plist		Info.plist
LICENSE		LICENSE
Podfile		Podfile
PrivacyInfo.xcprivacy		PrivacyInfo.xcprivacy
README.md		README.md
README_RU.md		README_RU.md
UseDesk_SDK_Swift-UseDesk-Bridging-Header.h		UseDesk_SDK_Swift-UseDesk-Bridging-Header.h
UseDesk_SDK_Swift.podspec		UseDesk_SDK_Swift.podspec
_Pods.xcodeproj		_Pods.xcodeproj
project.yml		project.yml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

UseDesk_SDK_Swift

This manual in other languages

Demo app

Launching a demo project

Adding a library to the project

CocoaPods

Swift Package Manager (SPM)

Initializing a Chat or Knowledge Base with Chat using the GUI

Parameters used in the configuration SDK with GUI

Initializing chat and chat with the Knowledge Base (GUI)

Parameters returned by the block

Initializing the Knowledge Base without chat using the GUI

Parameters used in SDK configuration with GUI

Initializing the SDK with the GUI, Knowledge Base only

Parameters returned by the block

Initializing SDK without GUI

Parameters used in the SDK configuration without GUI

Initializing SDK without a GUI

Parameters returned by the block

Documentation

Authors

License

About

Releases 60

Contributors 3

Languages

License

usedesk/UseDeskSwift

Folders and files

Latest commit

History

Repository files navigation

UseDesk_SDK_Swift

This manual in other languages

Demo app

Launching a demo project

Adding a library to the project

CocoaPods

Swift Package Manager (SPM)

Initializing a Chat or Knowledge Base with Chat using the GUI

Parameters used in the configuration SDK with GUI

Initializing chat and chat with the Knowledge Base (GUI)

Parameters returned by the block

Initializing the Knowledge Base without chat using the GUI

Parameters used in SDK configuration with GUI

Initializing the SDK with the GUI, Knowledge Base only

Parameters returned by the block

Initializing SDK without GUI

Parameters used in the SDK configuration without GUI

Initializing SDK without a GUI

Parameters returned by the block

Documentation

Authors

License

About

Resources

License

Stars

Watchers

Forks

Releases 60

Contributors 3

Languages