Utilizar o SDK de plugins WV¶

Para suportar a recuperação de dados do utilizador, a execução de negociações, a gestão de eventos e mais, um plugin WebView (cliente) deve estabelecer uma comunicação fiável com a aplicação cTrader (host). O SDK de plugins WebView facilita estas interações com o cTrader, e este guia explica o pipeline de comunicação entre o cliente e o anfitrião.

Instalação do SDK ¶

O SDK de plugins WebView está disponível como um pacote npm. Para instalar o SDK, aceda ao diretório do seu projeto numa janela de terminal e execute este comando:

npm install @spotware-web-team/sdk

Sincronização cliente-anfitrião¶

Para que qualquer mensagem possa ser trocada, deve ser estabelecido um canal de comunicação. As operações típicas incluem:

1. No início da comunicação, ocorre uma troca de eventos ativa, onde tanto o cliente como o anfitrião enviam um evento.

2. O anfitrião envia um evento de registo (payloadType = 2000). Exemplo:

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

3. O plugin WebView envia um evento de confirmação (payloadType = 2001). Exemplo:

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

4. Para cada novo evento de confirmação, é enviado um novo evento de registo para assegurar a sincronização, mesmo que o plugin reinicialize.

   Nota

   Se qualquer uma das partes não receber o evento ativo correspondente, o plugin não será montado. Para evitar loops, o plugin deve enviar o evento de confirmação apenas uma vez e monitorizar o fluxo de mensagens.

   Aviso

   O envio de múltiplos eventos de confirmação desencadeia eventos de registo repetidos, o que pode resultar num loop não intencional.

Pedidos ¶

Após a conclusão da sincronização, o plugin pode interagir com os serviços cTrader chamando métodos SDK que comunicam internamente com o anfitrião.

1. O plugin executa um método SDK. Por exemplo, pode solicitar informações da conta de um utilizador.

2. O plugin WebView envia um pedido. Exemplo:

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

   Internamente, define dois campos clientMsgId (interno e externo):

   • O campo interno identifica o pedido específico dentro do payload e é usado pelo cTrader para corresponder esse pedido com a sua resposta correspondente e quaisquer eventos relacionados.
   • O campo externo (quando usado junto com o interno) monitoriza o fluxo geral de mensagens entre o cliente e o anfitrião.

3. O anfitrião escuta os pedidos:

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

Respostas ¶

1. O anfitrião envia uma resposta:

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

   Cada resposta inclui o clientMsgId original para a ligar ao pedido. A resposta é baseada na estrutura seguinte:

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

   Respostas em tempo real ou múltiplas geram novos eventos usando:

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

2. O cliente escuta a resposta:

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

Eventos e subscrições ¶

Os plugins WebView podem subscrever dados em tempo real como cotações, atualizações de negociações, eventos de execução e mais.

1. Subscreva dados de cotação enviando um pedido:

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

2. A subscrição faz com que o anfitrião envie respostas periódicas:

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

Deeplinks ¶

Um plugin pode pedir ao cTrader para abrir um deeplink (URL interno) enviando este pedido:

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

Em seguida, o plugin aguarda por uma resposta:

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

Os plugins WebView podem implementar um deeplink suportado como demonstrado abaixo:

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

Resumo das mensagens ¶

A tabela abaixo resume as mensagens do protocolo.

Gestão de erros ¶

Se ocorrer um erro, o anfitrião emite uma resposta de erro estruturada:

payloadType: 2500 
clientMsgId: <original-id>

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

O SDK processa o erro e apresenta-o ao criador do plugin.