适用于 iOS 的 Amazon Connect Chat SDK

目录

关于

适用于 iOS 的 Amazon Connect Chat SDK 是一个 Swift 库，使您能够轻松地将 Amazon Connect Chat 直接集成到您的原生 iOS 应用程序中。Amazon Connect Chat SDK 帮助处理客户端聊天逻辑和后端通信，类似于 Amazon Connect ChatJS Library。该 SDK 封装了 Amazon Connect Participant Service API，并抽象了聊天会话和 WebSocket 的管理。这使您可以专注于用户界面和体验，同时依靠 Amazon Connect Chat SDK 与所有后端服务进行交互。这种方法仍然需要使用您自己的聊天后端来调用 Amazon Connect StartChatContact API 以启动联系。您可以从我们的 startChatContactAPI 示例中阅读有关如何快速设置 StartChatContact Lambda 的说明。

安装步骤

有三种选择可以将适用于 iOS 的 Amazon Connect Chat SDK 安装到您的 xCode 项目中

通过 Cocoapods 安装

在您的 Podfile 中

    * Reference the AmazonConnectChatIOS pod in your Podfile
    * target 'YourProject' do
            pod 'AmazonConnectChatIOS'
            ...
        end

然后在您项目的根目录中运行 pod install

通过 Swift Package Manager 安装

直接从 GitHub Releases 下载二进制文件

  1. 转到 适用于 iOS 的 Amazon Connect Chat SDK GitHub Releases 页面。
  2. 下载最新版本的 AmazonConnectChatIOS.xcframework。
  3. 如有必要，解压缩下载的文件。
  4. 将 AmazonConnectChatIOS.xcframework 拖放到您的 Xcode 项目中。

⚠️重要提示：在使用二进制文件时，请记住从 AWS IOS SDK 添加 'AWSCore' 和 'AWSConnectParticipant'。

如何导入 XCFramework

将 AmazonConnectChatIOS.xcframework 添加到您的项目后，您需要将其导入到您的代码中。以下是步骤

  1. 在您的 Swift 代码中导入框架: 
    import AmazonConnectChatIOS

通过遵循这些步骤，您可以使用 CocoaPods、Swift Package Manager 或通过直接添加 XCFramework 将适用于 iOS 的 Amazon Connect Chat SDK 集成到您的项目中。请务必按照每种方法的特定安装说明进行操作，以确保顺利完成设置过程。

入门指南

安装后，利用 Amazon Connect Chat SDK 的第一步是将库导入到您的文件中。接下来，让我们调用 StartChatContact API，并将响应详细信息传递到 SDK 的 ChatSession 对象中。这是一个关于如何在 Swift 中设置此设置的示例。作为参考，您可以访问 iOSChatExample demo 在 Amazon Connect Chat UI Examples GitHub 存储库中。

SDK 的大部分功能将通过 ChatSession 对象访问。为了在文件中使用此对象，我们必须首先通过以下方式导入 AmazonConnectChatIOS 库

import AmazonConnectChatIOS

接下来，我们可以创建一个 ChatManager 类，以帮助桥接 UI 和 SDK 通信。此类应负责管理与 ChatSession 对象的交互。我们可以将其添加为类属性，也可以使用 ChatSession.shared 直接引用它。

class ChatManager: ObservableObject {
    private var chatSession = ChatSession.shared

    ...

在使用 chatSession 对象之前，我们需要通过 GlobalConfig 对象为其设置配置。最重要的是，GlobalConfig 对象将用于设置您的 Connect 实例所在的 AWS 区域。以下是如何配置 ChatSession 对象的示例

init() {
    let globalConfig = GlobalConfig(region: .USEast1)
    self.chatSession = ChatSession.shared
    chatSession.configure(config: globalConfig)
    ...
}

从这里，您现在可以通过 ChatSession 对象与聊天进行交互。

如何接收消息

适用于 iOS 的 Amazon Connect Chat SDK 提供了两种接收消息的方法。

  1. 使用 ChatSession.onTranscriptUpdated
  1. 使用 ChatSession.onMessageReceived

API 列表

GlobalConfig

GlobalConfig 对象用于配置 AWS ConnectParticipant 客户端以及某些聊天行为。

GlobalConfig.init

GlobalConfig 对象的初始化程序接受 AWSRegionType、已启用的 Features 和 disableCSM 标志以禁用指标。

public struct GlobalConfig {
    public var region: AWSRegionType
    public var features: Features
    public var disableCsm: Bool

    public static var defaultRegion: AWSRegionType {
        return Constants.DEFAULT_REGION
    }

    // Initializes a new global configuration with optional custom settings or defaults
    public init(region: AWSRegionType = defaultRegion, features: Features = .defaultFeatures, disableCsm: Bool = false) {
        self.region = region
        self.features = features
        self.disableCsm = disableCsm
    }
}

更新配置

如果您已设置 GlobalConfig 对象或要更新配置，则可以调用 ChatSession.configure 以更新 config 对象。

let globalConfig = GlobalConfig(region: .USEast1)
chatSession.configure(config: globalConfig)

SDKLogger

SDKLogger 类负责将相关的运行时信息记录到控制台，这对于调试目的很有用。SDKLogger 将记录关键事件，例如建立连接或失败（例如无法发送消息）。

SDKLogger.configure

此 API 允许您使用自己的 SDKLoggerProtocol 实现来覆盖 SDK 的内置记录器。这在您想要存储日志以进行调试的情况下特别有用。将这些日志附加到在此项目中提交的问题将大大加快解决过程。

public static func configureLogger(_ logger: SDKLoggerProtocol) {
    SDKLogger.logger = logger
}

SDKLoggerProtocol

SDKLoggerProtocol 是用于 SDKLogger 的协议。用户可以使用实现 SDKLoggerProtocol 的任何类覆盖 SDKLogger。

public protocol SDKLoggerProtocol {
    func logVerbose(
        _ message: @autoclosure () -> String
    )
    func logInfo(
        _ message: @autoclosure () -> String
    )
    func logDebug(
        _ message: @autoclosure () -> String
    )
    func logFault(
        _ message: @autoclosure () -> String
    )
    func logError(
        _ message: @autoclosure () -> String
    )
}

ChatSession API

ChatSession.configure

使用 GlobalConfiguration 对象配置聊天服务。

func configure(config: GlobalConfig)

ChatSession.connect

尝试使用给定的详细信息连接到聊天会话。

func connect(chatDetails: ChatDetails, completion: @escaping (Result<Void, Error>) -> Void)

public struct ChatDetails {
    var contactId: String?
    var participantId: String?
    var participantToken: String
}

ChatSession.disconnect

断开当前聊天会话。

func disconnect(completion: @escaping (Result<Void, Error>) -> Void)

ChatSession.sendMessage

在聊天会话中发送消息。

func sendMessage(contentType: ContentType, message: String, completion: @escaping (Result<Void, Error>) -> Void)

ChatSession.sendEvent

在聊天会话中发送事件。

func sendEvent(event: ContentType, content: String, completion: @escaping (Result<Void, Error>) -> Void)

ChatSession.sendMessageReceipt

为消息发送已读回执。

func sendMessageReceipt(event: MessageReceiptType, messageId: String, completion: @escaping (Result<Void, Error>) -> Void)

ChatSession.getTranscript

检索聊天记录。

func getTranscript(scanDirection: AWSConnectParticipantScanDirection?, sortOrder: AWSConnectParticipantSortKey?, maxResults: NSNumber?, nextToken: String?, startPosition: AWSConnectParticipantStartPosition?, completion: @escaping (Result<TranscriptResponse, Error>) -> Void)

ChatSession.sendAttachment

在聊天会话中发送附件。

func sendAttachment(file: URL, completion: @escaping (Result<Void, Error>) -> Void)

ChatSession.downloadAttachment

给定附件 ID，将附件下载到应用程序的临时目录。

func downloadAttachment(attachmentId: String, filename: String, completion: @escaping (Result<URL, Error>) -> Void)

ChatSession.getAttachmentDownloadUrl

返回给定附件 ID 的下载 URL 链接。

func getAttachmentDownloadUrl(attachmentId: String, completion: @escaping (Result<URL, Error>) -> Void)

ChatSession.isChatSessionActive

返回一个布尔值，指示聊天会话是否仍然处于活动状态。

func isChatSessionActive() -> Bool

ChatSession 事件

ChatSession.onConnectionEstablished

连接建立时的回调。

var onConnectionEstablished: (() -> Void)? { get set }

ChatSession.onConnectionBroken

连接断开时的回调。

var onConnectionBroken: (() -> Void)? { get set }

ChatSession.onMessageReceived

接收到 WebSocket 消息时的回调。 请参阅 TranscriptItem。

var onMessageReceived: ((TranscriptItem) -> Void)? { get set }

ChatSession.onTranscriptUpdated

转录更新时的回调。 请参阅 TranscriptItem

var onTranscriptUpdated: (([TranscriptItem]) -> Void)? { get set }

ChatSession.onChatEnded

聊天结束时的回调。

var onChatEnded: (() -> Void)? { get set }

ChatSession.onDeepHeartbeatFailure

WebSocket 心跳丢失时的回调。

var onDeepHeartbeatFailure: (() -> Void)? { get set }

ChatSession.onConnectionReEstablished

连接重新建立时的回调。

var onConnectionReEstablished: (() -> Void)? { get set }

类和结构体

功能 (Features)

功能是用户可以选择启用、禁用或重新配置的可选聊天功能列表。

public struct Features {
    public var messageReceipts: MessageReceipts

    // Provides default Features configuration
    public static var defaultFeatures: Features {
        return Features(messageReceipts: .defaultReceipts)
    }

    public init(messageReceipts: MessageReceipts = .defaultReceipts) {
        self.messageReceipts = messageReceipts
    }
}

Features 的默认值将包含所有包含功能的默认值。

消息回执 (Message Receipts)

此功能启用对消息使用 Read（已读）和 Delivered（已送达）回执。 用于指示座席是否已阅读客户端发送的文本，反之亦然。

public struct MessageReceipts {
    public var shouldSendMessageReceipts: Bool
    public var throttleTime: Double
    
    // Provides default MessageReceipts configuration
    public static var defaultReceipts: MessageReceipts {
        return MessageReceipts(shouldSendMessageReceipts: true, throttleTime: Constants.MESSAGE_RECEIPT_THROTTLE_TIME)
    }
    
    public init(shouldSendMessageReceipts: Bool, throttleTime: Double) {
        self.shouldSendMessageReceipts = shouldSendMessageReceipts
        self.throttleTime = throttleTime
    }
}

ChatDetails

public struct ChatDetails {
    var contactId: String?
    var participantId: String?
    var participantToken: String
}

ContentType

ContentType 描述通过 WebSocket 传递的事件和消息的类型。

public enum ContentType: String {
    case typing = "application/vnd.amazonaws.connect.event.typing"
    case connectionAcknowledged = "application/vnd.amazonaws.connect.event.connection.acknowledged"
    case messageDelivered = "application/vnd.amazonaws.connect.event.message.delivered"
    case messageRead = "application/vnd.amazonaws.connect.event.message.read"
    case metaData = "application/vnd.amazonaws.connect.event.message.metadata"
    case joined = "application/vnd.amazonaws.connect.event.participant.joined"
    case left = "application/vnd.amazonaws.connect.event.participant.left"
    case ended = "application/vnd.amazonaws.connect.event.chat.ended"
    case plainText = "text/plain"
    case richText = "text/markdown"
    case interactiveText = "application/vnd.amazonaws.connect.message.interactive"
}

MessageReceiptType

MessageReceiptType 是 ContentType 的一个子集，用于消息回执相关事件。

public enum MessageReceiptType: String {
    case messageDelivered = "application/vnd.amazonaws.connect.event.message.delivered"
    case messageRead = "application/vnd.amazonaws.connect.event.message.read"
}

TranscriptResponse

public class TranscriptResponse: Equatable {
    public let initialContactId: String
    public let nextToken: String
    public var transcript: [TranscriptItem]
}

TranscriptItem

这是转录中所有可渲染消息的基类。

public class TranscriptItem: TranscriptItemProtocol {
    public var id: String
    public var timeStamp: String
    public var contentType: String
    public var serializedContent: [String: Any]?

Message (继承自 TranscriptItem)

TranscriptItem 的 Message 类型保留给机器人、联络流程或其他参与者发送的所有消息。 这包括交互式消息、附件和纯文本消息。

public class Message: TranscriptItem, MessageProtocol {
    public var participant: String
    public var text: String
    public var messageDirection: MessageDirection?
    public var attachmentId: String?
    public var displayName: String?
    @Published public var metadata: (any MetadataProtocol)?
}

Event (继承自 TranscriptItem)

TranscriptItem 的 Event 类型用于通过 WebSocket 传递的事件。 有关可能的事件列表，请参见 ContentType。

public class Event: TranscriptItem, EventProtocol {
    public var participant: String?
    public var text: String?
    public var displayName: String?
    public var eventDirection: MessageDirection?
}

Metadata (继承自 TranscriptItem)

Metadata 事件用于接收给定消息的附加数据，例如消息回执状态。

public class Metadata: TranscriptItem, MetadataProtocol {
    @Published public var status: MessageStatus?
    @Published public var eventDirection: MessageDirection?

安全

有关更多信息，请参见 CONTRIBUTING。

许可证

本项目采用 Apache-2.0 许可证。