Gunakan SDK plugin WV¶

Untuk menyokong pengambilan data pengguna, pelaksanaan dagangan, pengendalian acara dan banyak lagi, plugin WebView (klien) mesti menjalinkan komunikasi yang boleh dipercayai dengan aplikasi cTrader (hos). SDK plugin WebView memudahkan interaksi ini dengan cTrader, dan panduan ini menerangkan saluran komunikasi antara klien dan hos.

Pemasangan SDK ¶

SDK plugin WebView tersedia sebagai pakej npm. Untuk memasang SDK, navigasi ke direktori projek anda dalam tetingkap terminal dan kemudian jalankan arahan ini:

npm install @spotware-web-team/sdk

Penyegerakan klien-hos ¶

Sebelum sebarang pertukaran mesej boleh dilakukan, saluran komunikasi mesti diwujudkan terlebih dahulu. Operasi yang lazim termasuk:

1. Pada permulaan komunikasi, pertukaran acara aktif berlaku apabila klien dan hos menghantar acara masing-masing.

2. Hos menghantar acara pendaftaran (payloadType = 2000). Contoh:

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

3. Plugin WebView menghantar acara pengesahan (payloadType = 2001). Contoh:

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

4. Bagi setiap acara pengesahan baharu, acara pendaftaran baharu dihantar untuk memastikan penyegerakan, walaupun plugin ditetapkan pada keadaan asal.

   Nota

   Jika mana-mana pihak gagal menerima acara aktif yang sepadan, plugin tidak akan dipasang. Bagi mengelakkan berlakunya gelung, plugin mesti menghantar acara pengesahan hanya sekali dan menjejaki aliran mesej.

   Amaran

   Menghantar berbilang acara pengesahan akan mencetuskan acara pendaftaran berulang, yang berpotensi mengakibatkan gelung yang tidak disengajakan.

Permintaan ¶

Setelah penyegerakan selesai, plugin boleh berinteraksi dengan perkhidmatan cTrader dengan memanggil kaedah SDK yang berkomunikasi secara dalaman dengan hos.

1. Plugin memanggil kaedah SDK. Sebagai contoh, plugin boleh meminta maklumat akaun pengguna.

2. Plugin WebView menghantar permintaan. Contoh:

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

   Secara dalaman, plugin menetapkan dua medan clientMsgId (dalam dan luar):

   • Medan yang dalam mengenal pasti permintaan khusus dalam muat beban dan digunakan oleh cTrader untuk memadankan permintaan tersebut dengan respons yang sepadan dan sebarang acara berkaitan.
   • Medan yang luar (apabila digunakan bersama medan yang dalam) menjejaki aliran mesej keseluruhan antara klien dan hos.

3. Hos mendengar permintaan:

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

Respons ¶

1. Hos menghantar respons:

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

   Setiap respons termasuk clientMsgId asal untuk menghubungkan respons dengan permintaan. Respons adalah berdasarkan struktur ini:

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

   Respons masa nyata atau berbilang menjana acara baharu menggunakan:

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

2. Klien mendengar respons:

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

Acara dan langganan ¶

Plugin WebView boleh melanggan data masa nyata seperti sebut harga, kemas kini dagangan, acara pelaksanaan dan banyak lagi.

1. Langgan data sebut harga dengan menghantar permintaan:

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

2. Langganan mencetuskan hos untuk menghantar respons berkala:

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

Pautan khusus ¶

Plugin boleh meminta cTrader untuk membuka pautan khusus (URL dalaman) dengan menghantar permintaan ini:

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

Plugin kemudian mendengar respons:

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

Plugin WebView boleh melaksanakan pautan khusus yang disokong seperti yang ditunjukkan di bawah:

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

Ringkasan mesej ¶

Jadual di bawah meringkaskan mesej protokol.

Pengendalian ralat ¶

Jika sesuatu yang tidak kena berlaku, hos mengeluarkan respons ralat berstruktur:

payloadType: 2500 
clientMsgId: <original-id>

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

SDK mengendalikan ralat dan mengemukakan ralat tersebut kepada pencipta plugin.