SDK Hạ Tầng
Các SDK của Hạ Tầng đưa chat hỗ trợ vào website và ứng dụng của bạn, và nối server của bạn với API Hạ Tầng. Mọi client chat nói cùng một giao thức realtime với gateway chat.hatang.dev, nên khách nhắn từ website, ứng dụng di động, Zalo, Messenger, Instagram hay TikTok Shop đều về cùng một hộp thư.
Các SDK
| Nền tảng | Gói | Trạng thái | Hướng dẫn |
|---|---|---|---|
| Website (thẻ script) | https://chat.hatang.dev/widget.js | Ổn định | Widget web và JS API |
| React / Next.js | @hatang/chat-react | Ổn định | React và Next.js |
| WordPress | Hạ Tầng Chat | Ổn định | Plugin WordPress |
| Flutter (iOS, Android, web, desktop) | hatang_chat | Ổn định | Flutter |
| React Native / Expo | @hatang/chat-react-native | Ổn định | React Native |
| iOS (Swift) | HatangChat | Ổn định | iOS |
| Android (Kotlin) | dev.hatang:chat | Ổn định | Android |
| Node.js (server) | @hatang/sdk | Ổn định | SDK Node.js |
| Python (server) | hatang | Ổn định | SDK Python |
| AI coding agent (MCP) | @hatang/mcp | Mới | MCP server |
Các SDK phối hợp thế nào
Trên web, widget là phần lõi. @hatang/chat-react nạp widget trong ứng dụng React, còn plugin WordPress nạp widget trong website WordPress. Cả hai dùng chung JS API $hatang, và widget theo đúng cài đặt bạn chỉnh trong dashboard.
Trong ứng dụng di động, SDK là native. SDK Flutter, React Native, iOS và Android không nhúng web view. Mỗi SDK tự nói giao thức với gateway và có sẵn màn hình chat, danh sách hội thoại, nút chat nổi, hàm hỗ trợ thông báo đẩy và deep link. Chúng theo chung một hợp đồng: cùng khung mục trong tài liệu này, cùng các sự kiện, và cùng bộ kịch bản tuân thủ (C01–C12) mà mọi SDK phải chạy qua với gateway thật trước khi phát hành. Ứng dụng tự giới thiệu bằng khoá ứng dụng (hak_...) thay cho Origin của trình duyệt.
Ở server, dùng @hatang/sdk (Node.js) hoặc hatang (Python). Hai SDK gọi REST API bằng API key: gửi email, đọc và trả lời hội thoại như nhân viên, đưa gói và giao dịch mua lên hồ sơ khách, đồng bộ khách hàng, đơn hàng và kiến thức của trợ lý, tạo thanh toán và xác minh webhook. Với PHP, Go hay ngôn ngữ khác, gọi thẳng REST API.
Chủ đề dùng chung cho mọi SDK chat
- Nhận diện khách:
identifycó và không có chữ ký, identity secret, cách hộp thư gộp phiên. - Thông báo đẩy: tải tài khoản dịch vụ Firebase, khi nào Hạ Tầng gửi đẩy, dạng payload.
- Giao thức realtime: các khung WebSocket,
seqvàresume, mã đóng, JSON Schema tải về. - Tương thích: phiên bản SDK, giao thức và gateway tối thiểu, chính sách phiên bản.
Ma trận hỗ trợ
| SDK | Trạng thái | Hiện tại | Hỗ trợ | Giao thức | Nền tảng |
|---|---|---|---|---|---|
| widget.js | Ổn định | — | always current (served by the gateway) | 1 | Browsers with ES2020 (Chrome 80+, Safari 14+, Firefox 78+, Edge 80+) |
| @hatang/chat-react | Ổn định | 0.1.2 | 0.1.x | 1 | React 18+; Next.js 14+ (App Router and Pages) |
| @hatang/sdk | Ổn định | 0.6.2 | 0.6.x | 1 | Node 20+; Bun 1.1+; Edge runtimes with fetch (User-Agent reports node/unknown) |
| hatang (Python) | Ổn định | 0.1.1 | 0.1.x | 1 | Python 3.9+ (sync and asyncio, httpx) |
| hatang_chat (Flutter) | Ổn định | 0.6.1 | 0.6.x | 1 | Flutter 3.32+; Dart 3.8+; iOS 15+; Android 6.0 (API 23)+; macOS 11+; Web; Windows 10+; Linux (secure storage falls back to preferences) |
| @hatang/chat-react-native | Ổn định | 0.4.2 | 0.4.x | 1 | React Native 0.76+; Expo SDK 52+ |
| iOS (Swift) | Ổn định | 0.4.1 | 0.4.x | 1 | iOS 17+; Swift 6 / Xcode 16+; SwiftUI and UIKit (HatangChatViewController) |
| Android (Kotlin) | Ổn định | 0.4.1 | 0.4.x | 1 | Android 8+ (API 26); Kotlin 1.9+ / 2.x; Jetpack Compose (BOM 2024.12+); View-based apps open the chat through HatangChat.open |
| WordPress plugin | Ổn định | 0.2.3 | 0.2.x | 1 | WordPress 6.0+; PHP 7.4+ |
Bảng đầy đủ (gói, gateway tối thiểu) ở trang Tương thích.
Tham chiếu API
- REST API Hạ Tầng (email, hộp thư, thanh toán): Tham chiếu API.
- Gateway chat (endpoint của widget và SDK, có OpenAPI): Tham chiếu gateway chat. Giao thức dạng máy đọc được ở chat.hatang.dev/protocol.json.
@hatang/sdk: tham chiếu TypeDoc.@hatang/chat-react: README trên npm.hatang_chat(Flutter): tham chiếu dartdoc.HatangChatvàHatangChatCore(iOS): tham chiếu DocC.dev.hatang:chatvàdev.hatang:chat-core(Android): tham chiếu Dokka.
Các tham chiếu SDK được sinh từ chú thích trong mã nguồn của từng SDK và chỉ có bản tiếng Anh.
Bước tiếp theo
- Thêm chat vào website: Widget web và JS API hoặc React và Next.js.
- Thêm chat vào ứng dụng di động: Flutter, React Native, iOS hoặc Android.
- Gọi API từ server: SDK Node.js.