Skip to main content
Hai bộ SDK Android và iOS đưa đúng khung chat của kênh Live Chat vào ứng dụng của bạn. Cả hai đều là lớp bọc mỏng quanh một WebView, không khai báo thư viện phụ thuộc nào, và nhận đúng ba tham số; mọi thứ còn lại lấy từ cấu hình trên Console.
SDK dùng chung cấu hình với widget web. Hãy cấu hình kênh Web widget trước theo hướng dẫn ở Kênh Live Chat, rồi lấy connectionKey từ thẻ Config.

Ba tham số khởi tạo

appOrigin phải giữ nguyên phần đường dẫn /chat-widget. Nếu chỉ đưa tên miền gốc, WebView sẽ tải ứng dụng nằm ở gốc và khung chat hiện ra trắng.
Khác với website, SDK di động không đọc Ngôn ngữ mặc định trên Console. Bỏ trống locale thì khung chat luôn hiển thị tiếng Việt. Hãy truyền ngôn ngữ của thiết bị vào locale để ứng dụng nói đúng thứ tiếng khách hàng đang dùng.

Yêu cầu tối thiểu

Nhận gói cài đặt SDK

Chúng tôi bàn giao SDK dưới dạng gói cài đặt, không qua kho công cộng. Bạn nhận hai tệp nén, mỗi tệp cho một nền tảng - chỉ cần lấy tệp tương ứng với nền tảng bạn phát triển.

fpt-agent-chat-1.0.0-android.zip

Giải nén rồi chép thư mục android/maven trong đó vào dự án của bạn, ví dụ vào libs/fpt-agent-chat/maven. Tệp android/chat-1.0.0.aar nằm cạnh là bản rời, dùng khi dự án của bạn không thêm được kho Maven.

fpt-agent-chat-1.0.0-ios.zip

Giải nén rồi kéo ios/FptAgentChat.xcframework vào target của bạn.
Trên macOS hãy giải nén bằng Finder hoặc lệnh unzip, và không nén lại thư mục đã giải nén. .xcframework là một bundle; nén lại bằng công cụ khác có thể làm hỏng liên kết bên trong và Xcode sẽ báo lỗi khó hiểu.
Mỗi tệp nén đã kèm sẵn một tệp README.md ghi đầy đủ các bước cho riêng nền tảng đó.

Khai báo thư viện - Android

Khai báo thư viện - iOS

Kéo ios/FptAgentChat.xcframework vào target, rồi kiểm tra nó đã nằm trong mục Frameworks, Libraries, and Embedded Content với chế độ Embed & Sign.

Android

Mở khung chat toàn màn hình

Nhúng khung chat vào màn hình có sẵn

Bắt buộc khi bạn tự nhúng FptChatView

FptChatActivity đã nối sẵn hộp thoại chọn tệp. Nếu bạn đặt FptChatView vào màn hình của mình thì phải tự nối: không nối thì nút ghim tệp bấm vào không có phản ứng, và vì lời gọi lại bị bỏ lửng nên lần bấm thứ hai cũng không phản ứng nốt.
Activity chứa FptChatView còn cần android:windowSoftInputMode="adjustResize" trong AndroidManifest.xml, nếu không bàn phím sẽ che ô soạn tin. FptChatActivity đã có sẵn thuộc tính này.

Xử lý nút quay lại

Vòng đời

Gọi đủ cả ba phương thức vòng đời. Bỏ release() thì WebView vẫn sống sau khi màn hình đóng và gây rò rỉ bộ nhớ.

iOS

Bắt buộc: hai khóa trong Info.plist

Khung chat cho phép khách hàng gửi tệp đính kèm và chat.allow_attachments mặc định bật, nên đây là đường đi mặc định chứ không phải trường hợp hiếm. Nếu Info.plist thiếu NSPhotoLibraryUsageDescription hoặc NSCameraUsageDescription, hệ điều hành sẽ đóng ứng dụng của bạn ngay khi khách hàng bấm nút ghim tệp - không phải báo lỗi mà là thoát ứng dụng. Hãy khai cả hai, bằng câu chữ người dùng đọc được.

Mở khung chat toàn màn hình

Nhúng khung chat vào màn hình có sẵn

Mở liên kết ngoài

Điều hướng lùi trong WebView

Những điều cần nhớ

Cấu hình nằm trên Console

Màu sắc, lời chào, câu gợi ý và chính sách đính kèm đều lấy từ thẻ Customize widget. Sửa trên Console là ứng dụng đổi theo ngay, không cần phát hành bản mới.

Ngôn ngữ phải truyền tay

Đây là khác biệt duy nhất so với web. Hãy lấy ngôn ngữ hệ thống của thiết bị và truyền vào locale.

Một kênh, nhiều điểm chạm

Website và ứng dụng di động dùng chung một connectionKey, nên hội thoại và cấu hình là một.

Đổi kênh là đổi khóa

Xóa kênh Website rồi tạo lại sẽ sinh connectionKey mới. Ứng dụng đang chạy phải cập nhật lại khóa.

Danh mục kiểm tra trước khi phát hành

  • Đã cấu hình và lưu kênh Web widget ít nhất một lần trên Console.
  • appOrigin lấy từ Console và giữ nguyên phần đường dẫn /chat-widget.
  • connectionKey đúng với kênh của Agent bạn muốn dùng.
  • Đã truyền locale của thiết bị, vì SDK không đọc ngôn ngữ mặc định trên Console.
  • Với iOS: Info.plist đã có NSPhotoLibraryUsageDescription và NSCameraUsageDescription - thiếu là ứng dụng thoát khi khách bấm ghim tệp.
  • Với Android, nếu bạn tự nhúng FptChatView: đã nối fileChooserHandler cùng onActivityResult, và Activity đã đặt windowSoftInputMode="adjustResize".
  • Đã thử mở, đóng và quay lại nhiều lần để chắc chắn vòng đời được xử lý đúng.
  • Đã thử trên cả mạng yếu để xem màn hình chờ và thông báo lỗi có hợp lý không.
Giới hạn kích thước tệp đính kèm, định dạng được phép và các mã lỗi chung nằm ở Phụ lục kỹ thuật.