Skip to content

Latest commit

 

History

History
347 lines (287 loc) · 19.8 KB

README.md

File metadata and controls

347 lines (287 loc) · 19.8 KB
Raw

UseDesk_SDK_Swift

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

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.

  1. Install xcodegen:
    • brew install xcodegen
  2. Generate xcodeproj:
    • xcodegen generate
  3. Install pods
    • pod install
  4. 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

  1. Archive xcframework:

    • cd build && zip -r UseDesk_SDK_Swift.zip UseDesk_SDK_Swift/*

  2. 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