Android SDK

Yêu cầu#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x và Jetpack Compose (SDK đi kèm Compose UI).
• JVM target 17.

SDK tự kéo về các phụ thuộc bắc cầu của nó (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) và khai báo quyền INTERNET trong manifest của nó — không cần thêm gì bằng tay.

Cài đặt#

Thư viện được phát hành lên Maven Central dưới dạng ai.respondo:respondo-sdk. Hãy đảm bảo mavenCentral() có trong danh sách repositories của bạn (mặc định đã có trong một dự án Android mới), rồi thêm phụ thuộc theo tọa độ.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("ai.respondo:respondo-sdk:0.1.0")
}

Khởi tạo#

Gọi Respondo.init một lần, gắn RespondoChatHost() một lần trong cây Compose của bạn, và mở cuộc hội thoại từ nút của riêng bạn.

import ai.respondo.sdk.Respondo
import ai.respondo.sdk.RespondoConfig
import ai.respondo.sdk.ui.RespondoChatHost

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Respondo.init(
            context = this,
            config = RespondoConfig(
                agentId = "<agent-uuid>",   // từ dashboard
                channelId = "<channel-uuid>", // tùy chọn
                // bỏ qua baseUrl -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // SDK hiển thị sheet khi trạng thái chat là OPEN
                }
            }
        }
    }
}

Mọi lệnh gọi đều đi qua singleton Respondo. Chúng có tính idempotent, an toàn từ bất kỳ luồng nào, và các lệnh gọi thực hiện trước khi init hoàn tất sẽ được đệm lại và phát lại.

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 bộ nhớ cục bộ, 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ủ.

import ai.respondo.sdk.RespondoIdentity

// 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: bỏ push token, thu hồi session, khởi tạo một khách ẩn danh mới.
Respondo.clearPushToken()
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 & callback#

Đọc trạng thái một cách phản ứng dưới dạng StateFlow (tuyệt vời cho Compose) hoặc theo kiểu mệnh lệnh qua RespondoListener (tuyệt vời cho huy hiệu trên biểu tượng ứng dụng).

// Phản ứng: số tin chưa đọc dưới dạng StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Mệnh lệnh: listener cho huy hiệu và phân tích.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

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ó. Truyền null để xóa nó; trên mỗi thay đổi, teaser chủ động được đánh giá lại cho màn hình mới.

Cùng tên này được so khớp với quy tắc màn hình của khảo sát bật lên, vì vậy hãy dùng định danh cố định như «Checkout» thay cho tiêu đề đã dịch. Quy tắc địa chỉ trang chỉ áp dụng trên trang web.

Respondo.setCurrentScreen("pricing")

Mở khảo sát từ mã#

Mở ngay một khảo sát bật lên đang chạy, dù người dùng ở màn hình nào, bỏ qua Show on, quy tắc màn hình, thời gian trên màn hình, sự kiện kích hoạt và đối tượng. Sao chép id trong trình chỉnh sửa khảo sát (Additional ways to share). Khảo sát mà người dùng đã trả lời sẽ không hiển thị lại.

Respondo.startSurvey("<survey-id>")

Bước tiếp theo#

Thiết lập Thông báo đẩy cho phản hồi ngoại tuyến của nhân viên và Xác minh danh tính cho người dùng đã đăng nhập. Toàn bộ bề mặt API, bộ bọc Fragment cho host XML, và xử lý sự cố được đề cập trong hướng dẫn bắt đầu của Android SDK; mã nguồn SDK được công khai trên GitHub.