iOS SDK

Yêu cầu#

• iOS 15.0+ (điểm neo sheet tinh hơn trên iOS 16+, với dự phòng hệ thống bên dưới).
• Swift 5.9+.
• Không có phụ thuộc bên thứ ba — chỉ Foundation, Swift Concurrency, SwiftUI và UIKit.

Bạn phụ thuộc vào sản phẩm RespondoSDK, sản phẩm này re-export RespondoCore đa nền tảng.

Cài đặt#

Thêm gói bằng Swift Package Manager. Trong Xcode: File → Add Package Dependencies… và nhập https://github.com/respondo-app/sdk-ios, hoặc khai báo nó trong Package.swift của riêng bạn, rồi phụ thuộc vào sản phẩm RespondoSDK.

dependencies: [
    .package(url: "https://github.com/respondo-app/sdk-ios", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RespondoSDK", package: "sdk-ios")
        ]
    )
]

Sau đó import nó trong mã:

import RespondoSDK

Khởi tạo#

Khởi tạo một lần khi khởi chạy, rồi gọi Respondo.open() ở bất cứ đâu. Phương thức vòng đời là initialize (từ init được ngôn ngữ giữ làm từ khóa).

import SwiftUI
import RespondoSDK

@main
struct MyApp: App {
    init() {
        Respondo.initialize(
            RespondoConfig(
                agentId: "<agent-uuid>",
                channelId: "<channel-uuid>"
                // baseUrl nil -> https://api.respondo.ai
            )
        )
    }

    var body: some Scene {
        WindowGroup {
            Button("Support") { Respondo.open() }
        }
    }
}

Mặt tiền Respondo an toàn với luồng. Các lệnh gọi thực hiện ngay sau initialize được xếp hàng và áp dụng một khi init bất đồng bộ hoàn tất.

Nhận diện người dùng#

Theo mặc định mọi khách truy cập đều ẩn danh. Trong lần khởi chạy đầu tiên, SDK tạo một visitor_id ổn định và giữ nó trong keychain, nhờ đó một người dùng quay lại tìm thấy cuộc hội thoại của họ. Không có API key nào cần nhúng — mỗi cuộc hội thoại được bảo vệ bởi một session token theo từng cuộc hội thoại mà backend đúc ra và trượt về phía trước sau mỗi tin nhắn, nhờ đó một khách ẩn danh không bao giờ phải xác thực lại.

Gọi identify một khi người dùng của bạn đã đăng nhập. Điều này gắn danh tính thực của họ để lịch sử theo họ qua các thiết bị và lần cài lại, và tên cùng email của họ hiển thị bên cạnh cuộc hội thoại trong hộp thư của bạn thay vì một khách ẩn danh.

userHash là một chữ ký mà backend của bạn tính từ identity_secret của agent — HMAC-SHA256(secret, userId) (hoặc email khi không có userId), mã hóa dưới dạng hex chữ thường. Secret chứng minh danh tính là xác thực, nên nó chỉ được sống trên backend của bạn và không bao giờ được đóng gói trong ứng dụng. Xem trang Xác minh danh tính để biết công thức đầy đủ và các ví dụ phía máy chủ.

// userHash đến từ backend của bạn (HMAC-SHA256 trên userId) —
// đừng bao giờ tính nó trong ứng dụng.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// Khi đăng xuất: thu hồi session và khởi tạo một khách ẩn danh mới.
Respondo.reset()

Nếu hash bị thiếu hoặc sai, không có ngoại lệ nào được ném ra: backend âm thầm giữ khách truy cập ẩn danh, cuộc hội thoại vẫn hoạt động, và bạn chỉ đơn giản mất liên kết đa thiết bị cho đến khi cung cấp một hash hợp lệ. Việc xác minh chỉ chạy khi agent có identity_secret được đặt — hãy để trống trong quá trình phát triển và userId / email được chấp nhận nguyên trạng.

Observable & delegate#

Đọc trạng thái dưới dạng getter đồng bộ, các AsyncStream phản ứng, hoặc thông qua một RespondoDelegate. Stream và callback delegate đến trên main actor.

// Stream phản ứng của số tin chưa đọc.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Delegate cho huy hiệu và dự phòng deep-link.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Theo dõi màn hình#

Báo cáo màn hình hiện tại trên mỗi lần điều hướng để teaser chủ động và nhắm mục tiêu cấp trang có thể khớp với nó (static func setCurrentScreen(_ name: String?)). Truyền nil để xóa nó; trên mỗi thay đổi, teaser chủ động được đánh giá lại cho màn hình mới.

Respondo.setCurrentScreen("pricing")

Bước tiếp theo#

Thiết lập Thông báo đẩy và Xác minh danh tính. Bộ bọc UIKit RespondoChatViewController, toàn bộ bề mặt delegate, và xử lý sự cố được đề cập trong hướng dẫn bắt đầu của iOS SDK; mã nguồn SDK được công khai trên GitHub.