Sử dụng SDK plugin WV¶

Để hỗ trợ việc truy xuất dữ liệu người dùng, khớp lệnh giao dịch, xử lý sự kiện và nhiều tác vụ khác, plugin WebView (máy khách) cần thiết lập một kênh liên lạc đáng tin cậy với ứng dụng cTrader (máy chủ). SDK của các plugin WebView là cầu nối cho những tương tác này với cTrader, và hướng dẫn này sẽ giải thích quy trình giao tiếp giữa máy khách và máy chủ.

Cài đặt SDK ¶

SDK của các plugin WebView hiện có sẵn dưới dạng gói npm. Để cài đặt SDK, hãy chuyển đến thư mục dự án của bạn trong cửa sổ terminal và chạy lệnh sau:

npm install @spotware-web-team/sdk

Đồng bộ hóa máy khách-máy chủ ¶

Trước khi có thể trao đổi bất kỳ thông điệp nào, một kênh giao tiếp phải được thiết lập. Các thao tác điển hình bao gồm:

1. Khi bắt đầu quá trình giao tiếp, một sự kiện alive sẽ được trao đổi, trong đó cả máy khách và máy chủ đều gửi đi một sự kiện.

2. Máy chủ gửi một sự kiện đăng ký (payloadType = 2000). Ví dụ:

   window.dispatchEvent(new MessageEvent('message-from-host', { data: {"clientMsgId": "152cf2d4-bfb6-4426-a303-9243b6a0daf4", "payload": {}, "payloadType": 2000} }))
   

3. Plugin WebView gửi một sự kiện xác nhận (payloadType = 2001). Ví dụ:

   window.dispatchEvent(new MessageEvent('message-to-host', { data: {"clientMsgId": "152cf2d4-bfb6-4426-a303-9243b6a0daf4", "payload": {}, "payloadType": 2001} }))
   

4. Đối với mỗi sự kiện xác nhận mới, một sự kiện đăng ký mới sẽ được gửi đi để đảm bảo đồng bộ hóa, ngay cả khi plugin được khởi tạo lại.

   Ghi chú

   Nếu một trong hai bên không nhận được sự kiện alive tương ứng, plugin sẽ không được khởi tạo. Để tránh xảy ra các vòng lặp, plugin chỉ được phép gửi sự kiện xác nhận một lần duy nhất và phải theo dõi luồng tin nhắn.

   Cảnh báo

   Việc gửi nhiều sự kiện xác nhận sẽ kích hoạt các sự kiện đăng ký lặp lại, có thể dẫn đến một vòng lặp không mong muốn.

Yêu cầu ¶

Khi đồng bộ hóa hoàn tất, plugin có thể tương tác với các dịch vụ cTrader bằng cách gọi phương thức SDK để giao tiếp nội bộ với máy chủ.

1. Plugin gọi một phương thức SDK. Ví dụ, plugin có thể yêu cầu thông tin tài khoản của người dùng.

2. Plugin WebView gửi một yêu cầu. Ví dụ:

   {
     "payloadType": 2100,
     "payload": {
       "payloadType": 175,
       "clientMsgId": "asd1-asd1"
     },
     "clientMsgId": "asd2-asd2"
   }
   

   Về mặt nội bộ, hệ thống thiết lập hai trường clientMsgId (bên trong và bên ngoài):

   • Trường bên trong xác định yêu cầu cụ thể trong payload và được cTrader sử dụng để ghép nối yêu cầu đó với phản hồi tương ứng và các sự kiện liên quan.
   • Trường bên ngoài (khi được sử dụng cùng với trường bên trong) theo dõi toàn bộ luồng thông điệp giữa máy khách và máy chủ.

3. Máy chủ lắng nghe các yêu cầu:

   window.addEventListener('message-to-host', function (event) {})
   

Phản hồi ¶

1. Máy chủ gửi một phản hồi:

   window.dispatchEvent(new MessageEvent('message-from-host', { data }))
   

   Mỗi phản hồi đều bao gồm clientMsgId gốc để liên kết với yêu cầu tương ứng. Phản hồi dựa trên cấu trúc này:

   payloadType: 2101 
   clientMsgId: "<same-id-as-request>"
   

   Phản hồi thời gian thực hoặc phản hồi nhiều lần sẽ tạo ra các sự kiện mới thông qua:

   payloadType: 2102
   clientMsgId: "<same-id-as-request>"
   

2. Máy khách lắng nghe phản hồi:

   window.addEventListener('message-from-host', function (event) {})
   

Sự kiện và đăng ký ¶

Plugin WebView có thể đăng ký nhận dữ liệu thời gian thực như báo giá, cập nhật giao dịch, sự kiện khớp lệnh và nhiều loại dữ liệu khác.

1. Đăng ký nhận dữ liệu báo giá bằng cách gửi yêu cầu:

   {
     "payloadType": 2100, // indicates a request
     "payload": {
       "payloadType": 601,
       "symbolId": ["EURUSD_ID"],
       "clientMsgId": "quote-sub-123"
     },
     "clientMsgId": "asd2-asd2" // outer message ID
   }
   

2. Việc đăng ký sẽ khiến máy chủ gửi phản hồi định kỳ:

   {
     "payloadType": 2102, // indicates an event
     "payload": {
       "payloadType": 3, // mapped to QUOTE_EVENT
       "payload": {
         "ask": 85274,
         "bid": 85271,
         "depth": [],
         "high": 85340,
         "low": 84932,
         "sessionClose": 85133,
         "symbolId": 9,
         "tickbar": [],
         "timestamp": 1750162811236,
         "trendbar": []
       },
       "clientMsgId": "asd1-asd1" // inner message ID
     },
     "clientMsgId": "asd2-asd2" // outer message ID
   }
   

Liên kết sâu ¶

Plugin có thể yêu cầu cTrader mở một liên kết sâu (URL nội bộ) bằng cách gửi yêu cầu này:

payloadType: 2103
clientMsgId: "<client-msg-id>"

Plugin sau đó lắng nghe phản hồi:

payloadType: 2104
clientMsgId: "<same-id-as-request>"

Plugin WebView có thể triển khai một liên kết sâu được hỗ trợ như được minh họa dưới đây:

// Open EURUSD symbol overview
  const openEURUSDInfo = useCallback(() => {
      const url = baseUrl ? ${baseUrl}symbols/EURUSD/info : 'symbols/EURUSD/info';
      openUrl(url);
  }, [baseUrl, openUrl]);

Tóm tắt các thông điệp ¶

Bảng dưới đây tóm tắt các thông điệp giao thức.

Xử lý lỗi ¶

Nếu có sự cố xảy ra, máy chủ sẽ gửi một phản hồi lỗi có cấu trúc như sau:

payloadType: 2500 
clientMsgId: <original-id>

{
  "payloadType": 2500,
  "clientMsgId": "<original-id>",
  "error": "InvalidPayload"
}

SDK sẽ xử lý lỗi và hiển thị lỗi đó cho người tạo plugin.