Skip to content

Latest commit

 

History

History
211 lines (155 loc) · 9.13 KB

README.md

File metadata and controls

211 lines (155 loc) · 9.13 KB

Amazon Connect Chat IOS Demo 📱

This is an example app on how to utilise AmazonConnectChatIOS SDK

Refer to #Specifications for details on compatibility, supported versions, and platforms.

Screen.Recording.2024-07-15.at.5.39.09.PM.mov

Reference:

Contents

Prerequisites

  • Create an Amazon Connect Instance [guide]

    • OR: enable chat experience for an existing Connect instance. [guide]

  • Create an Amazon Connect Contact Flow, ready to receive chat contacts. [guide]

  • Deploy a custom Amazon Connect Chat backend. Refer to this backend template

    • Deploy a StartChatContact template Lambda [CloudFormation Template]
    • Add the region, startChatEndPoint, contactFlowId, and instanceId to Config.swift.

  • (Optional) Setup interactive messages guide

    • If using above, make sure to deploy startChatContact template again with interactive message contactFlowId and update down the endpoints.

Local Development

Versions: Xcode 15, Swift 5
Download Xcode: https://developer.apple.com/xcode/

  1. Clone this repository: https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/

    $ git clone https://github.com/amazon-connect/amazon-connect-chat-ui-examples.git

  2. This examples uses SPM as dependency manager, once you open the .xcodeproj file make sure that all the required dependencies are added. More here

  3. Edit the Config file with your instance details as generated in Prerequisites

    Make sure you have iOS Simulator added Adding additional simulators

  4. Once everything looks okay, Run the app by clicking on ▶️ button on top left or hit Cmd + R.

Implementation

The first step to leveraging the Amazon Connect Chat SDK after installation is to import the library into your file. The first step is to call the StartChatContact API and pass the response details into the SDK’s ChatSession object. Here are some examples of how we would set this up in Swift. For reference, you can visit the iOSChatExample demo within the Amazon Connect Chat UI Examples GitHub repository.

Configuring and Using ChatSession in Your Project

The majority of the SDK's functionality will be accessed through the ChatSession object. In order to use this object in the file, we have to first import the AmazonConnectChatIOS library:

import AmazonConnectChatIOS

Next, we can create a ChatManager class that helps bridge UI and SDK communication. This class should be responsible for managing interactions with the ChatSession object. We can either add it as a class property or reference it directly using ChatSession.shared.

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

    ...

Before using the chatSession object, we need to set the config for it via the GlobalConfig object. Most importantly, the GlobalConfig object will be used to set the AWS region that your Connect instance lives in. Here is an example of how to configure the ChatSession object:

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

Creating Participant Connection

After calling StartChatContact, we can pass that information to self.chatSession.connect to call createParticipantConnection and begin the participant’s chat session.

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

    ...
    private func handleStartChatResponse(_ response: CreateStartChatResponse, completion: @escaping (Bool) -> Void) {
        DispatchQueue.main.async {
            let response = response.data.startChatResult
            self.participantToken = response.participantToken
            let chatDetails = ChatDetails(contactId: response.contactId, participantId: response.participantId, participantToken: response.participantToken)
            self.createParticipantConnection(usingSavedToken: false, chatDetails: chatDetails, completion: completion)
        }
    }
    
    private func createParticipantConnection(usingSavedToken: Bool, chatDetails: ChatDetails, completion: @escaping (Bool) -> Void) {
        self.chatSession.connect(chatDetails: chatDetails) { [weak self] result in
            switch result {
            case .success:
                // Handle success case
            case .failure(let error):
                // Handle error case
            }
        }
    }
    ...
}

Interacting with the Chat Session

After calling createParticipantConnection, the SDK will maintain the credentials needed to call any following Amazon Connect Participant Service APIs. Here are some examples of how to call some common Amazon Connect Participant Service APIs. For more in-depth documentation on all APIs, please visit the Amazon Connect Chat SDK for iOS GitHub page.

SendMessage

/// Sends a chat message with plain text content
func sendChatMessage(messageContent: String) {
    self.chatSession.sendMessage(contentType: .plainText, message: messageContent) { [weak self] result in
        self?.handleMessageSendResult(result)
    }
}

SendEvent

/// Sends an event to the chat session
func sendEvent(contentType: AmazonConnectChatIOS.ContentType, content: String = "") {
    self.chatSession.sendEvent(event: contentType, content: content) { [weak self] result in
        self?.handleEventSendResult(result)
    }
}

GetTranscript

/// Fetches the chat transcript
func fetchTranscript() {
    self.chatSession.getTranscript(scanDirection: .backward, sortOrder: .ascending, maxResults: 15, nextToken: nil, startPosition: nil) { [weak self] result in
        self?.handleFetchTranscriptResult(result)
    }
}

Disconnect

/// Disconnects the chat session
func disconnectChat() {
    self.chatSession.disconnect { [weak self] result in
        self?.handleChatDisconnectResult(result)
    }
}

Setting Up Chat Event Handlers

The ChatSession object also exposes handlers for common chat events for users to build on. Here is an example code block that demonstrates how you can register event handlers to chat events.

private func setupChatSessionHandlers(chatSession: ChatSessionProtocol) {
    self.chatSession.onConnectionEstablished = { [weak self] in
        // Handle established chat connection
    }
    
    self.chatSession.onMessageReceived = { [weak self] transcriptItem in
        // Handle incoming messages
    }
    
    self.chatSession.onTranscriptUpdated = { [weak self] transcript in
        // Handle transcript updates
    }
    
    self.chatSession.onChatEnded = { [weak self] in
        // Handle chat end
    }
    
    self.chatSession.onConnectionBroken = {
        // Handle lost connection
    }
}

Specifications

Technical Specifications

  • Language: Swift 5.x
  • Xcode : 15
  • iOS: iOS 16 and Higher (⚠️ Required)
  • Frameworks:
    • SwiftUI: For UI components and layout.
    • AsyncImage: For loading images asynchronously.
  • Networking: Utilizing URLSession for network calls to fetch images and send/receive messages.
  • Markdown Parsing: AttributedString for rendering markdown text.

Code Quality

  • MV Architecture: Separation of concerns between the view, model.
  • Reusable Components: Modular design with reusable views and components.
  • Error Handling: Comprehensive error handling for networking and data persistence.
  • Memory Management: Use of @ObservedObject and @State to manage the lifecycle of data objects.