Giới thiệu
Mở kết nối WebSocket theo thời gian thực để nhận nội dung, cập nhật đơn hàng và người dùng mà không cần polling.
Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/events/introduction
🎯 Mô-đun này làm gì?
Mô-đun WS (WebSocket) cho phép bạn nhận thông báo theo thời gian thực - cập nhật nội dung, thay đổi đơn hàng, hành động của người dùng - thiết lập các kết nối liên tục để nhận cập nhật ngay lập tức mà không cần polling, cho phép các tính năng trực tiếp như thông báo, trò chuyện trực tiếp và bảng điều khiển theo thời gian thực.
Hãy nghĩ về nó như một hệ thống thông báo theo thời gian thực của bạn - thay vì liên tục hỏi "có gì mới không?" (polling), WebSocket giữ kết nối mở và máy chủ sẽ đẩy các cập nhật đến bạn ngay lập tức khi có sự kiện xảy ra.
📖 Giải thích đơn giản
Mỗi ứng dụng hiện đại đều cần cập nhật theo thời gian thực:
- 🔔 Thông báo trực tiếp - Cảnh báo ngay lập tức khi có điều gì xảy ra
- 💬 Trò chuyện trực tiếp - Nhắn tin theo thời gian thực giữa các người dùng
- 📊 Bảng điều khiển trực tiếp - Thống kê và chỉ số tự động cập nhật
- 🛒 Cập nhật đơn hàng - Thay đổi trạng thái đơn hàng ngay lập tức
- 📝 Cập nhật nội dung - Thay đổi và xuất bản nội dung theo thời gian thực
- 👥 Hoạt động của người dùng - Sự hiện diện và hành động của người dùng theo thời gian thực
- 🔄 Đồng bộ dữ liệu - Đồng bộ hóa tự động giữa các thiết bị
Vấn đề với polling (các yêu cầu lặp lại):
// ❌ Bad - Polling every 5 seconds
setInterval(async () => {
const orders = await Orders.getOrders();
// Check if anything changed
// Wastes bandwidth, delays updates, server load
}, 5000);
Vấn đề:
- 🔋 Tiêu tốn pin - Các yêu cầu liên tục lãng phí năng lượng
- 📡 Lãng phí mạng - Hầu hết các yêu cầu trả về "không có thay đổi"
- ⏱️ Cập nhật chậm - Đến 5 giây trễ
- 🖥️ Tải máy chủ - Các yêu cầu không cần thiết mỗi vài giây
Giải pháp WebSocket:
// ✅ Good - Real-time WebSocket connection
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
token: 'your-app-token'
});
// connect() returns a socket.io Socket (requires an authorized user)
const socket = await WS.connect();
// Listen for events with socket.on(...)
socket.on('my_event', (payload) => {
console.log('Update received!', payload);
// Instant notification, no polling!
});
Lợi ích:
- 🔋 Hiệu quả - Kết nối liên tục duy nhất
- 📡 Theo thời gian thực - Cập nhật ngay lập tức, không có độ trễ
- ⏱️ Độ trễ thấp - Giao hàng thông báo dưới một giây
- 🖥️ Giảm tải - Máy chủ chỉ đẩy khi cần thiết
✨ Khái niệm chính
WebSocket là gì?
WebSocket là một kết nối hai chiều liên tục giữa máy khách và máy chủ:
- Kết nối liên tục - Giữ kết nối mở, không cần bắt tay lặp lại
- Hai chiều - Cả máy khách và máy chủ đều có thể gửi tin nhắn
- Theo thời gian thực - Giao hàng tin nhắn ngay lập tức
- Dựa trên sự kiện - Lắng nghe các sự kiện với
socket.on(...) - Hiệu quả - Chi phí thấp hơn so với polling HTTP
WebSocket so với HTTP Polling
| Tính năng | WebSocket | HTTP Polling |
|---|---|---|
| Kết nối | Liên tục (giữ mở) | Kết nối lặp lại |
| Độ trễ | Dưới một giây | Phụ thuộc vào khoảng thời gian (2-30 giây) |
| Hiệu quả | Rất hiệu quả | Lãng phí (nhiều phản hồi trống) |
| Tải máy chủ | Thấp (chỉ sự kiện) | Cao (các yêu cầu liên tục) |
| Sử dụng pin | Thấp | Cao (trên thiết bị di động) |
| Trường hợp sử dụng | Cập nhật theo thời gian thực | Chấp nhận cho các cập nhật không quan trọng |
Vòng đời kết nối WebSocket
1. Client opens a connection
(const socket = await WS.connect())
↓
2. Connection established
(socket.on('connect', ...) fires)
↓
3. Client listens for events
(socket.on('my_event', callback))
↓
4. Server sends events when they occur
(Instant delivery)
↓
5. Client receives event messages
(Callback function executes)
↓
6. Connection stays open
(No reconnection needed)
↓
7. Client disconnects when done
(socket.disconnect())
Các sự kiện nào đến qua kết nối
Không có danh mục cố định các tên sự kiện SDK. Các sự kiện được kích hoạt theo cấu hình mô-đun Sự kiện của bạn trong bảng điều khiển quản trị (sự kiện phải có tùy chọn WebSocket được bật). Bạn lắng nghe một sự kiện theo dấu hiệu của nó với socket.on('<event_marker>', callback).
Nội dung phụ thuộc vào nguồn của sự kiện. Các trường nội dung điển hình (xem connect() để biết ví dụ đầy đủ):
| Trường nội dung | Đến cho | Chứa |
|---|---|---|
attributes | Mỗi sự kiện | Các thuộc tính của sự kiện đó |
product | Sự kiện danh mục (sản phẩm) | Các thuộc tính sản phẩm cộng với title |
user | Sự kiện từ biểu mẫu người dùng | Các trường từ biểu mẫu người dùng |
order | Sự kiện đơn hàng | id đơn hàng và các thuộc tính |
email / code | Biểu mẫu đăng ký / mã | Các trường biểu mẫu bổ sung |
Tại sao sử dụng mô-đun WebSocket?
| Lợi ích | Mô tả |
|---|---|
| Cập nhật theo thời gian thực | Thông báo ngay lập tức, không có độ trễ từ polling |
| Hiệu quả | Kết nối duy nhất, chi phí thấp |
| Thân thiện với pin | Không cần polling liên tục trên di động |
| Có thể mở rộng | Máy chủ chỉ đẩy khi cần thiết |
| Dựa trên sự kiện | Đăng ký các sự kiện cụ thể |
| Tính năng trực tiếp | Kích hoạt trò chuyện, thông báo, bảng điều khiển |
📋 Những điều bạn cần biết
Quản lý kết nối WebSocket
Các kết nối WebSocket cần được quản lý cẩn thận:
Thực hành tốt nhất:
- Kiểm tra trạng thái kết nối trước khi đăng ký
- Triển khai logic kết nối lại
- Xử lý lỗi kết nối một cách nhẹ nhàng
- Ngắt kết nối khi người dùng đăng xuất
Quản lý đăng ký sự kiện
Chỉ đăng ký các sự kiện sau khi kết nối được thiết lập
Thực hành tốt nhất:
- Sử dụng các hàm callback có tên để dễ dàng hủy đăng ký
- Đăng ký sau khi kết nối mở
- Hủy đăng ký khi thành phần không còn
- Không đăng ký cùng một sự kiện nhiều lần
Hủy đăng ký sự kiện
Luôn hủy đăng ký khi hoàn tất để ngăn ngừa rò rỉ bộ nhớ:
Thực hành tốt nhất:
- Hủy đăng ký trong các hàm dọn dẹp
- Ngắt kết nối WebSocket khi không cần thiết
- Ngăn ngừa rò rỉ bộ nhớ trong SPAs
Chiến lược kết nối lại
Triển khai kết nối lại tự động với độ trễ tăng dần:
Thực hành tốt nhất:
- Sử dụng độ trễ tăng dần cho việc kết nối lại
- Giới hạn số lần kết nối lại tối đa
- Đặt lại bộ đếm khi kết nối thành công
- Cho phép ngắt kết nối thủ công mà không cần kết nối lại
Cấu trúc nội dung sự kiện
Nội dung sự kiện tuân theo cấu trúc nhất quán:
Thực hành tốt nhất:
- Xác thực cấu trúc nội dung sự kiện
- Xử lý các trường thiếu một cách nhẹ nhàng
- Kiểm tra kiểu nội dung trong TypeScript
Xử lý lỗi
Triển khai xử lý lỗi toàn diện:
Thực hành tốt nhất:
- Bắt lỗi trong các trình xử lý sự kiện
- Ghi lại lỗi để gỡ lỗi
- Hiển thị thông báo lỗi thân thiện với người dùng
- Không để lỗi làm sập ứng dụng
Tối ưu hóa hiệu suất
Tối ưu hóa hiệu suất WebSocket:
Thực hành tốt nhất:
- Giới hạn tần suất sự kiện cao
- Gộp nhiều cập nhật lại với nhau
- Giảm thiểu các cập nhật UI
- Tránh các thao tác tốn kém trong các trình xử lý
💡 Lưu ý quan trọng
⚠️ Quản lý trạng thái kết nối
Luôn kiểm tra trạng thái kết nối trước khi đăng ký
🔄 Xử lý kết nối lại
Các kết nối WebSocket có thể bị ngắt đột ngột:
- Thay đổi mạng (từ WiFi sang di động)
- Máy chủ khởi động lại
- Thời gian chờ không hoạt động
Luôn triển khai logic kết nối lại
🧹 Ngăn ngừa rò rỉ bộ nhớ
Hủy đăng ký khi hoàn tất để ngăn ngừa rò rỉ bộ nhớ
🔒 Bảo mật
Các kết nối WebSocket được xác thực:
- Xác thực dựa trên token (giống như REST API)
- Giao thức WebSocket bảo mật (WSS)
- Không cần gửi token với mỗi tin nhắn
Thực hành tốt nhất:
- Sử dụng WSS (WebSocket bảo mật) trong sản xuất
- Không tiết lộ dữ liệu nhạy cảm trong các trình xử lý sự kiện
- Xác thực nội dung sự kiện trước khi xử lý
📱 Cân nhắc trên di động
WebSocket trên các thiết bị di động:
- Sử dụng pin (hiệu quả, nhưng kết nối liên tục)
- Các kết nối nền có thể bị ngắt
- Thay đổi mạng yêu cầu kết nối lại
Thực hành tốt nhất:
- Kết nối lại khi ứng dụng trở lại nền trước
- Xử lý các thay đổi trạng thái mạng
- Cân nhắc việc polling cho các cập nhật không quan trọng trên di động
📊 Bảng tham khảo nhanh
| Phương thức | Mô tả | Trường hợp sử dụng |
|---|---|---|
| connect() | Kết nối đến máy chủ WebSocket | Thiết lập kết nối |
🔐
connect()yêu cầu một người dùng đã được xác thực — xác thực trước qua AuthProvider. Sau khi kết nối, gán các trình xử lý sự kiện vớisocket.on(...).
❓ Câu hỏi thường gặp (FAQ)
Làm thế nào để tôi kết nối với máy chủ WebSocket?
Sử dụng WS.connect() để mở một kết nối — nó trả về một Socket của socket.io. Nó yêu cầu một người dùng đã được xác thực, vì vậy hãy gọi AuthProvider.auth(...) trước. Chờ sự kiện connect trước khi dựa vào socket, sau đó gán các trình xử lý với socket.on('<event_marker>', callback). Kết nối được xác thực bằng token truy cập của người dùng cộng với token ứng dụng của bạn từ defineOneEntry().
Tôi có thể đăng ký những sự kiện nào?
Không có danh sách sự kiện SDK cố định. Các sự kiện được xác định bởi cấu hình mô-đun Sự kiện của bạn trong bảng điều khiển quản trị (với tùy chọn WebSocket được bật), và bạn lắng nghe một sự kiện theo dấu hiệu của nó với socket.on('<event_marker>', callback). Xem connect() để biết ví dụ về nội dung (sản phẩm, người dùng, đơn hàng, biểu mẫu).
Làm thế nào để tôi xử lý việc ngắt kết nối?
Triển khai kết nối lại tự động với độ trễ tăng dần. Lắng nghe các sự kiện disconnect và connect_error của socket.io, sau đó cố gắng kết nối lại sau một khoảng thời gian (ví dụ: 1 giây, 2 giây, 4 giây, 8 giây, tối đa 30 giây). Đặt lại bộ đếm độ trễ khi kết nối thành công. (socket.io cũng tự động kết nối lại theo mặc định.)
Tôi nên sử dụng WebSocket hay polling cho ứng dụng của mình?
Sử dụng WebSocket cho các tính năng theo thời gian thực (trò chuyện trực tiếp, thông báo, bảng điều khiển) nơi mà các cập nhật ngay lập tức là quan trọng. Sử dụng polling cho các cập nhật không quan trọng hoặc khi các kết nối WebSocket gặp vấn đề (tường lửa hạn chế, chế độ nền di động).
Làm thế nào để tôi ngăn ngừa rò rỉ bộ nhớ với các đăng ký WebSocket?
Luôn hủy đăng ký các sự kiện khi các thành phần không còn hoặc khi kết nối không còn cần thiết. Trong React, sử dụng các hàm dọn dẹp trong useEffect. Trong Vue, sử dụng hook vòng đời beforeUnmount.
Tôi có thể sử dụng WebSocket trên các thiết bị di động không?
Có, nhưng hãy lưu ý rằng hệ điều hành di động có thể ngắt các kết nối WebSocket nền. Kết nối lại khi ứng dụng trở lại nền trước. Cân nhắc tác động đến pin của các kết nối liên tục trên các thiết bị di động.
🎓 Thực hành tốt nhất
- Kiểm tra trạng thái kết nối - Chỉ đăng ký sau khi kết nối mở
- Triển khai kết nối lại - Tự động kết nối lại khi ngắt với độ trễ tăng dần
- Hủy đăng ký khi dọn dẹp - Ngắt kết nối các trình xử lý (
socket.off) vàsocket.disconnect()để ngăn ngừa rò rỉ bộ nhớ trong SPAs - Xử lý lỗi một cách nhẹ nhàng - Bắt lỗi trong các trình xử lý sự kiện
- Giới hạn tần suất sự kiện cao - Tránh làm quá tải UI với các cập nhật
- Xác thực nội dung sự kiện - Kiểm tra cấu trúc dữ liệu trước khi xử lý
- Sử dụng các callback có tên - Dễ dàng hơn để hủy đăng ký và gỡ lỗi
- Ghi lại trạng thái kết nối - Theo dõi các sự kiện mở/đóng/lỗi để gỡ lỗi
Định nghĩa của mô-đun WS
Bạn có thể đăng ký các sự kiện qua WebSocket để nhận thông báo
const { WS } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Tài liệu liên quan
- Mô-đun Đơn hàng - Các sự kiện đơn hàng để theo dõi đơn hàng theo thời gian thực
- Mô-đun Người dùng - Các sự kiện người dùng để thông báo đăng ký
- Mô-đun Thanh toán - Các sự kiện thanh toán để cập nhật giao dịch
- WebSocket API