Menggunakan SDK plugin WV¶

Untuk mendukung pengambilan data pengguna, pelaksanaan trading, penanganan event dan lainnya, plugin WebView (klien) harus membangun komunikasi yang andal dengan aplikasi cTrader (host). SDK plugin WebView memfasilitasi interaksi ini dengan cTrader, dan panduan ini menjelaskan alur komunikasi antara klien dan host.

Instalasi SDK ¶

SDK plugin WebView tersedia sebagai paket npm. Untuk menginstal SDK, bukalah direktori proyek Anda di jendela terminal lalu jalankan perintah ini:

npm install @spotware-web-team/sdk

Sinkronisasi klien-host ¶

Sebelum pesan dapat dipertukarkan, saluran komunikasi harus dibuat. Operasi yang biasa dilakukan meliputi:

1. Pada awal komunikasi, terjadi pertukaran event alive di mana klien dan host sama-sama mengirimkan suatu event.

2. Host mengirim event registrasi (payloadType = 2000). Contoh:

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

3. Plugin WebView mengirim event konfirmasi (payloadType = 2001). Contoh:

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

4. Untuk setiap event konfirmasi baru, event registrasi baru dikirim untuk memastikan sinkronisasi, meskipun plugin diinisiasi ulang.

   Catatan

   Jika salah satu pihak gagal menerima event alive yang sesuai, plugin tidak akan terpasang. Untuk menghindari perulangan, plugin harus mengirim event konfirmasi satu kali saja dan melacak alur pesan.

   Peringatan

   Pengiriman beberapa event konfirmasi akan memicu event registrasi berulang, sehingga berpotensi mengakibatkan perulangan yang tidak diinginkan.

Permintaan ¶

Setelah sinkronisasi selesai, plugin dapat berinteraksi dengan layanan cTrader dengan memanggil metode SDK yang berkomunikasi secara internal dengan host.

1. Plugin memanggil suatu metode SDK. Misalnya, plugin dapat meminta informasi akun pengguna.

2. Plugin WebView mengirim permintaan. Contoh:

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

   Secara internal, plugin mengatur dua bidang clientMsgId (inner dan outer):

   • Inner mengidentifikasi permintaan spesifik dalam payload serta digunakan oleh cTrader untuk mencocokkan permintaan tersebut dengan respons yang sesuai dan event yang berkaitan.
   • Outer (ketika digunakan bersama dengan inner) melacak alur pesan keseluruhan antara klien dan host.

3. Host mendengarkan permintaan:

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

Respons ¶

1. Host mengirimkan respons:

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

   Setiap respons menyertakan clientMsgId asli untuk menghubungkannya dengan permintaan. Respons didasarkan pada struktur ini:

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

   Respons real-time atau berganda menghasilkan event baru menggunakan:

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

2. Klien mendengarkan respons:

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

Event dan langganan ¶

Plugin WebView dapat berlangganan data real-time seperti kuotasi, pembaruan deal, event pelaksanaan dan lainnya.

1. Berlangganan data kuotasi dengan mengirim permintaan:

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

2. Langganan memicu host untuk mengirim 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
   }
   

Deeplink ¶

Plugin dapat meminta cTrader untuk membuka deeplink (URL internal) dengan mengirim permintaan ini:

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

Plugin kemudian mendengarkan respons:

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

Plugin WebView dapat mengimplementasikan deeplink yang didukung seperti yang ditunjukkan di bawah ini:

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

Ringkasan pesan ¶

Tabel di bawah ini merangkum pesan-pesan protokol.

Penanganan galat ¶

Jika terjadi kesalahan, host mengeluarkan respons galat terstruktur:

payloadType: 2500 
clientMsgId: <original-id>

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

SDK menangani galat dan menampilkannya kepada pembuat plugin.