AmazonConnectChatIOS 1.0.0

AmazonConnectChatIOS 1.0.0

×

由 Rajat Mittal 维护。

AmazonConnectChatIOS 1.0.0

  • 作者：
  • Michael Liao 和 Rajat Mittal

适用于 iOS 的 Amazon Connect Chat SDK

目录

关于

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

安装步骤

有三种方法可以将 Amazon Connect Chat SDK 安装到您的 xCode 项目中

  1. 通过 Cocoapods 安装

在您的 Podfile 中

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

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

  1. 通过 Swift 包管理器 安装

  2. 直接从 Amazon Connect Chat SDK for iOS 的 GitHub 发布页面下载二进制文件

开始使用

安装后，要利用 Amazon Connect Chat SDK，第一步是将库导入到您的文件中。第一步是调用 StartChatContact API，并将响应详情传递给 SDK 的 ChatSession 对象。以下是如何在 Swift 中设置此例子的示例。供参考，您可以访问 GitHub 仓库中的 iOSChatExample 演示，位于 Amazon Connect Chat UI 示例。

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

import AmazonConnectChatIOS

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

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

    ...

在使用chatSession对象之前，我们需要通过GlobalConfig对象设置其配置。最重要的是，GlobalConfig对象将用于设置你的Connect实例所在的地域。下面是配置ChatSession对象的示例

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

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

如何接收消息

Amazon Connect Chat SDK for iOS提供两种接收消息的方法。

  1. 使用ChatSession.onTranscriptUpdated
  • 此事件将在每次会话记录更新时返回整个会话记录。这将通过TranscriptItem数组返回会话记录。
  1. 使用ChatSession.onMessageReceived
  • 此事件将在WebSocket接收到的每条消息上返回。事件处理器将传递一个单个TranscriptItem。

API 列表

全局配置

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

GlobalConfig.init

GlobalConfig对象的初始化器接受AWSRegionType和启用Features。

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

    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) {
        self.region = region
        self.features = features
    }
}
  • region
    • 此属性用于设置ConnectParticipant客户端的地域。应将其设置为Connect实例的地域（例如.USEast1）。
    • 类型：AWSRegionType
  • features: Features
    • 此属性指定了某些功能的启用以及它们的配置。如果没有为此属性传递值，则聊天将使用默认值配置。有关详细信息，请参阅Features。
    • 类型：Features

更新配置

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

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

ChatSession API

ChatSession.configure

使用全局配置对象配置聊天服务。

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
}
  • chatDetails
    • 要连接的聊天会话的详细信息。从StartChatContact响应中提取ChatDetails数据。
    • 类型：ChatDetails
  • completion
    • 在完成连接操作时调用完成处理器。
    • 类型：(Result) -> Void

ChatSession.disconnect

断开当前聊天会话。

func disconnect(completion: @escaping (Result<Void, Error>) -> Void)
  • completion
    • 在完成断开操作时调用此完成处理器。
    • 类型：(Result) -> Void

ChatSession.sendMessage

在聊天会话中发送消息。

func sendMessage(contentType: ContentType, message: String, completion: @escaping (Result<Void, Error>) -> Void)
  • contentType
  • message
    • 要发送的消息。
    • 类型：String
  • completion
    • 在完成发送操作时调用此完成处理器。
    • 类型：(Result) -> Void

ChatSession.sendEvent

在聊天会话中发送事件。

func sendEvent(event: ContentType, content: String, completion: @escaping (Result<Void, Error>) -> Void)
  • event
  • content
    • 要发送的事件内容。
    • 类型：String
  • completion
    • 在完成发送操作时调用此完成处理器。
    • 类型：(Result) -> Void

ChatSession.sendMessageReceipt

为消息发送读收据。

func sendMessageReceipt(event: MessageReceiptType, messageId: String, completion: @escaping (Result<Void, Error>) -> Void)
  • event
    • 要发送的读收据类型（可以是.messageDelivered或.messageRead）
    • 类型：MessageReceiptType
    • 默认值：.messageRead
  • messageId
    • 要确认的消息ID。
    • 类型：String
  • completion
    • 在完成发送操作时调用此完成处理器。
    • 类型：(Result) -> Void

ChatSession.getTranscript

检索聊天会话记录。

func getTranscript(scanDirection: AWSConnectParticipantScanDirection?, sortOrder: AWSConnectParticipantSortKey?, maxResults: NSNumber?, nextToken: String?, startPosition: AWSConnectParticipantStartPosition?, completion: @escaping (Result<TranscriptResponse, Error>) -> Void)
  • scanDirection
    • 扫描会话记录的方向。
    • 类型：AWSConnectParticipantScanDirection? (字符串：'FORWARD' | 'BACKWARD'）
    • 默认值：BACKWARD
  • sortOrder
    • 排序会话记录的顺序。
    • 类型：AWSConnectParticipantSortKey? (字符串：'DESCENDING | 'ASCENDING'）
    • 默认值：ASCENDING
  • maxResults
    • 检索的最大结果数。
    • 类型: NSNumber?
    • 默认值: 15
  • nextToken
    • 类型：String
    • 下一个结果集的令牌。
  • startPosition
    • 转录的开始位置。
    • 类型: AWSConnectParticipantStartPosition?。参见 StartPosition
  • completion
    • 当转录检索完成时调用的完成处理程序。
    • 类型: (Result<TranscriptResponse, Error>) -> Void

ChatSession.sendAttachment

在聊天会话中发送附件。

func sendAttachment(file: URL, completion: @escaping (Result<Void, Error>) -> Void)
  • file
    • 要附加的文件的URL。
    • 类型: URL
  • completion
    • 在完成发送操作时调用此完成处理器。
    • 类型：(Result) -> Void

ChatSession.downloadAttachment

根据附件ID将附件下载到应用的临时目录。

func downloadAttachment(attachmentId: String, filename: String, completion: @escaping (Result<URL, Error>) -> Void)
  • attachmentId
    • 要下载的附件的ID。
    • 类型：String
  • filename
    • 保存附件的文件名。
    • 类型：String
  • completion
    • 下载操作完成后调用的完成处理程序。
    • 类型: (Result<URL, Error>) -> Void

ChatSession.getAttachmentDownloadUrl

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

func getAttachmentDownloadUrl(attachmentId: String, completion: @escaping (Result<URL, Error>) -> Void)
  • attachmentId
    • 附件的ID。
    • 类型：String
  • completion
    • 当URL检索完成时调用的完成处理程序。
    • 类型: (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 }

类和结构

功能

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

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
    }
}

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

消息收条

此功能启用对消息使用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
    }
}
  • shouldSendMessageReceipts
    • 类型: Bool
    • 这是控制从客户端发送消息收条标志的标志。请注意，这不会阻止从代理端发送消息收条事件。
    • 默认值: true
  • throttleTime
    • 类型: Double
    • 用于确定在触发事件之前多长时间对消息收条事件进行节流。我们建议在每个事件之前至少有一些节流时间，以减少不必要的网络请求。
    • 默认值: 5.0

聊天详情

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

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]
}
  • initialContactId
    • 这是聊天联系人的ID
    • 类型：String
  • nextToken
  • transcript

TranscriptItem

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

public class TranscriptItem: TranscriptItemProtocol {
    public var id: String
    public var timeStamp: String
    public var contentType: String
    public var serializedContent: [String: Any]?
  • id
    • 消息的 id。在每个转录的消息中都是唯一的。
    • 类型：String
  • timeStamp
    • 消息或事件被发送的时间。采用 ISO 8601 格式（例如 yyyy-MM-ddThh:mm:ss.SSSZ 或 2019-11-08T02:41:28.172Z）
    • 类型：String
  • contentType
    • 消息的类型
    • 类型：String（参见 ContentType）
  • serializedContent
    • 接收到的 WebSocket 消息的原始 JSON 格式
    • 类型：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)?
}
  • participant
    • 这是消息发送者的参与者角色（例如 AGENT）
    • 类型：String
  • text
    • 这是消息的文本内容
    • 类型：String
  • messageDirection
    • 这是消息的方向
    • 类型：MessageDirection（Outgoing | Incoming | Common）
  • attachmentId
    • 这是附件的 id。只有当此消息包含附件时才定义。
    • 类型：String
  • displayName
    • 这是消息的显示名称
    • 类型：String
  • metadata
    • 这是与消息关联的元数据。
    • 类型：Metadata

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?
}
  • participant
    • 这是消息发送者的参与者角色（例如 AGENT）
    • 类型：String?
  • text
    • 这是事件的文本内容
    • 类型：String?
  • displayName
    • 这是事件的显示名称
    • 类型：String
  • eventDirection
    • 这是事件的方向
    • 类型：eventDirection（Outgoing | Incoming | Common）

Metadata（扩展自 TranscriptItem）

Metadata 事件用于接收有关特定消息的额外数据，例如消息读取状态。

public class Metadata: TranscriptItem, MetadataProtocol {
    @Published public var status: MessageStatus?
    @Published public var eventDirection: MessageDirection?
  • status
    • 这是事件的接收状态。
    • 类型：MessageStatus（'Read' | 'Delivered'）
  • eventDirection
    • 这是元数据事件的方向。
    • 类型：eventDirection（Outgoing | Incoming | Common）

安全

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

许可

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