Usar SDK de plugins WV¶

Para permitir la recuperación de datos de usuario, la ejecución de operaciones, la gestión de eventos, etc., un plugin de WebView (cliente) debe establecer una comunicación fiable con la aplicación de cTrader (host). El SDK de plugins de WebView facilita estas interacciones con cTrader. En esta guía se explica el proceso de comunicación entre cliente y host.

Instalación del SDK ¶

El SDK de plugins WebView está disponible como paquete npm. Para instalar el SDK, navegue hasta el directorio de su proyecto en una ventana del terminal y ejecute este comando:

npm install @spotware-web-team/sdk

Sincronización cliente-host ¶

Antes de proceder a intercambiar mensajes, debe establecer un canal de comunicación. Las operaciones típicas incluyen:

1. Al inicio de la comunicación, se produce un intercambio de eventos activos en el que tanto el cliente como el host envían un evento.

2. El host envía un evento de registro (payloadType = 2000). Ejemplo:

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

3. El plugin de WebView envía un evento de confirmación (payloadType = 2001). Ejemplo:

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

4. Para cada nuevo evento de confirmación, se envía un nuevo evento de registro para garantizar la sincronización, aunque se reinicialice el plugin.

   Nota

   Si alguna de las partes no recibe el evento activo correspondiente, el plugin no se montará. Para evitar bucles, el plugin debe enviar el evento de confirmación solo una vez y llevar un seguimiento del flujo de mensajes.

   Advertencia

   El envío de múltiples eventos de confirmación activa eventos de registro repetidos, que pueden dar lugar a un bucle no deseado.

Solicitudes ¶

Una vez completada la sincronización, el plugin puede interactuar con los servicios de cTrader llamando a métodos SDK que se comunican internamente con el host.

1. El plugin llama a un método SDK. Por ejemplo, puede solicitar la información de la cuenta de un usuario.

2. El plugin de WebView envía una solicitud. Ejemplo:

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

   Internamente, establece dos campos clientMsgId (interno y externo):

   • El interno identifica la solicitud específica dentro de la carga útil y cTrader lo utiliza para emparejar esa solicitud con su respuesta correspondiente, así como con eventos relacionados.
   • El externo (cuando se usa junto con el interno) lleva el seguimiento del flujo general de mensajes entre cliente y host.

3. El host escucha las solicitudes:

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

Respuestas ¶

1. El host envía una respuesta:

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

   Cada respuesta incluye el clientMsgId original para vincularlo con la solicitud. La respuesta se basa en esta estructura:

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

   Las respuestas en tiempo real o múltiples generan nuevos eventos mediante:

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

2. El cliente escucha la respuesta:

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

Eventos y suscripciones ¶

Los plugins de WebView pueden suscribirse a datos en tiempo real como cotizaciones, actualizaciones de operaciones, eventos de ejecución y más.

1. Suscríbase a datos de cotización mediante una solicitud:

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

2. La suscripción activa el envío periódico de respuestas por parte del host:

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

Enlaces profundos ¶

Un plugin puede solicitar a cTrader que abra un enlace profundo (URL interna) mediante esta solicitud:

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

El plugin luego escucha para conocer la respuesta:

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

Los plugins de WebView pueden implementar un enlace profundo compatible como se demuestra a continuación:

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

Resumen de mensajes ¶

La tabla a continuación resume los mensajes del protocolo.

Manejo de errores ¶

Si algo sale mal, el host emite una respuesta de error estructurada:

payloadType: 2500 
clientMsgId: <original-id>

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

El SDK maneja el error y lo muestra al creador del plugin.