使用 WV 插件 SDK¶

为了支持用户数据检索、交易执行、事件处理等功能，WebView 插件（客户端）必须与 cTrader 应用程序（主机）建立可靠的通信。 WebView 插件 SDK 促进了与 cTrader 的这些交互，本指南解释了客户端与主机之间的通信管道。

SDK 安装 ¶

WebView 插件 SDK 可作为 npm 包 使用。 要安装 SDK，请在终端窗口中导航到您的项目目录，然后运行以下命令：

npm install @spotware-web-team/sdk

客户端-主机同步 ¶

在交换任何消息之前，必须建立通信通道。 典型操作包括：

1. 在通信开始时，会进行存活事件交换，客户端和主机都会发送一个事件。

2. 主机发送一个注册事件（payloadType = 2000）。 示例：

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

3. WebView 插件发送一个确认事件（payloadType = 2001）。 示例：

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

4. 对于每个新的确认事件，都会发送一个新的注册事件以确保同步，即使插件重新初始化。

   注意

   如果任何一方未能接收到相应的存活事件，插件将不会挂载。 为了避免循环，插件必须仅发送一次确认事件并跟踪消息流。

   警告

   发送多个确认事件会触发重复的注册事件，可能导致意外的循环。

请求 ¶

一旦同步完成，插件可以通过调用与主机内部通信的 SDK 方法 与 cTrader 服务进行交互。

1. 插件调用一个 SDK 方法。 例如，它可以请求用户的 账户信息。

2. WebView 插件发送一个请求。 示例:

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

   在内部，它设置了两个 clientMsgId 字段（内部和外部）：

   • 内部字段用于标识有效载荷中的特定请求，并由 cTrader 用于将该请求与其对应的响应和任何相关事件进行匹配。
   • 外部字段（与内部字段一起使用时）跟踪客户端和主机之间的整体消息流。

3. 主机监听请求：

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

响应 ¶

1. 主机分派响应：

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

   每个响应都包含原始的 clientMsgId，以将其与请求关联。 响应基于以下结构：

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

   实时或多个响应使用以下方式生成新事件：

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

2. 客户端监听响应：

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

事件和订阅 ¶

WebView 插件可以订阅实时数据，例如 报价、交易更新、执行事件 等。

1. 通过发送请求订阅报价数据：

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

2. 订阅触发主机发送定期响应：

   {
     "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
   }
   

深度链接 ¶

插件可以通过发送以下请求要求 cTrader 打开一个深度链接（内部URL）：

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

然后插件会监听响应：

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

WebView 插件可以实现一个支持的深度链接，如下所示：

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

消息摘要 ¶

下表总结了协议消息。

错误处理 ¶

如果出现问题，主机会发出结构化的错误响应：

payloadType: 2500 
clientMsgId: <original-id>

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

SDK 会处理错误并将其呈现给插件创建者。