Chuyển đến nội dung chính

Giới thiệu

Mở một kết nối WebSocket thời gian thực để nhận nội dung, đơn hàng và cập nhật 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 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 - qua một kết nối liên tục, vì vậy máy chủ sẽ gửi cập nhật đến bạn ngay lập tức thay vì bạn phải polling để nhận. Điều này 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 thời gian thực.

Phương thức duy nhất, connect(), mở kết nối và trả về một Socket của socket.io. Nó là đồng bộ và cần một người dùng đã được ủy quyền, vì vậy hãy xác thực trước.

🚀 Khởi động nhanh​

Khởi tạo mô-đun từ defineOneEntry:


const { WS } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

connect() là đồng bộ và trả về một Socket của socket.io (không có await). Gắn các trình xử lý sự kiện với socket.on(...):

// connect() requires an authorized user — authenticate first via AuthProvider.
const socket = WS.connect();

socket.on('connect', () => {
  console.log('WebSocket connected');
});

// Listen for an event by its marker (configured in the Events module).
socket.on('my_event', (payload) => {
  console.log('Update received!', payload);
});

✨ 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 client và server:

  • Kết nối liên tục - Giữ kết nối mở, không cần bắt tay lại
  • Hai chiều - Cả client và server đều có thể gửi tin nhắn
  • 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ả - Tốn ít tài nguyên hơn so với HTTP polling

WebSocket so với HTTP Polling​

Tính năngWebSocketHTTP Polling
Kết nốiLiên tục (giữ mở)Kết nối lặp lại
Độ trễDưới một giâyPhụ thuộc vào khoảng thời gian (2-30s)
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 (yêu cầu liên tục)
Trường hợp sử dụngCập nhật thời gian thựcChấp nhận cho các cập nhật không quan trọng

Vòng đời kết nối​

1. Authenticate the user (AuthProvider.auth)
   ↓
2. Open the connection: const socket = WS.connect()
   ↓
3. Wait for the 'connect' event: socket.on('connect', ...)
   ↓
4. Listen for events: socket.on('<event_marker>', callback)
   ↓
5. Server pushes events as they occur
   ↓
6. Disconnect when done: socket.disconnect()

Các sự kiện nào đến qua kết nối​

Không có danh sách tên sự kiện SDK cố định. 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 gốc 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 choChứa
attributesMỗi sự kiệnCác thuộc tính của sự kiện đó
productCác 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
userCác sự kiện từ biểu mẫu người dùngCác trường từ biểu mẫu người dùng
orderCác sự kiện đơn hàngid đơn hàng và các thuộc tính
email / codeBiểu mẫu đăng ký / mãCác trường bổ sung từ biểu mẫu

📋 Những điều bạn cần biết​

Cần có quyền truy cập​

connect() yêu cầu một người dùng đã được ủy quyền — gọi AuthProvider.auth(...) trước khi kết nối. Kết nối được xác thực bằng mã thông báo truy cập của người dùng cộng với mã thông báo ứng dụng của bạn từ defineOneEntry(). Nếu không có người dùng nào được ủy quyền, SDK sẽ ghi lại một lỗi.

connect() là đồng bộ​

connect() trả về một Socket của socket.io ngay lập tức — không cần await. 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(...).

Đăng ký sau khi kết nối mở, dọn dẹp khi xong​

Gắn các trình xử lý sự kiện sau khi sự kiện connect được kích hoạt, và ngắt kết nối chúng (socket.off) cộng với gọi socket.disconnect() khi kết nối không còn cần thiết (ví dụ: khi thành phần bị gỡ bỏ hoặc người dùng đăng xuất) để ngăn ngừa rò rỉ bộ nhớ trong SPAs.

Kết nối lại​

socket.io tự động kết nối lại theo mặc định. Để tùy chỉnh, lắng nghe các sự kiện disconnect và connect_error và kết nối lại với độ trễ tăng dần, đặt lại độ trễ khi kết nối thành công.

📊 Bảng tham khảo nhanh​

Phương thứcMô tảTrường hợp sử dụng
connect() 🔐Kết nối đến máy chủ WebSocketThiết lập kết nối

🔐 connect() yêu cầu một người dùng đã được ủy quyền — 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ới socket.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ó là đồng bộ và trả về một Socket của socket.io. Nó yêu cầu một người dùng đã được ủy quyền, 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).

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ý các kết nối bị ngắt?​

socket.io tự động kết nối lại theo mặc định. Để tùy chỉnh, lắng nghe các sự kiện disconnect và connect_error và kết nối lại với độ trễ tăng dần (ví dụ: 1s, 2s, 4s, 8s, tối đa), đặt lại bộ đếm độ trễ khi kết nối thành công.

Làm thế nào để tôi ngăn ngừa rò rỉ bộ nhớ với các đăng ký WebSocket?​

Ngắt kết nối các trình xử lý sự kiện (socket.off) và gọi socket.disconnect() khi các thành phần bị gỡ bỏ hoặc khi kết nối không còn cần thiết. Trong React, thực hiện điều này trong phần dọn dẹp của useEffect; trong Vue, trong beforeUnmount.

🎓 Thực hành tốt nhất​

  • Xác thực trước - connect() yêu cầu một người dùng đã được ủy quyền.
  • Đừng chờ connect() - Nó là đồng bộ và trả về một Socket.
  • Đăng ký sau khi kết nối mở - Gắn các trình xử lý sau khi sự kiện connect được kích hoạt.
  • 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ý kết nối lại - socket.io tự động kết nối lại; tùy chỉnh với disconnect / connect_error và độ trễ nếu cần.
  • Xác thực nội dung sự kiện - Hình dạng nội dung phụ thuộc vào nguồn sự kiện; kiểm tra các trường trước khi sử dụng chúng.

🔗 Tài liệu liên quan​