ใช้ SDK ของปลั๊กอิน WV¶

เพื่อสนับสนุนการดึงข้อมูลผู้ใช้ การดำเนินการเทรด การจัดการเหตุการณ์ และอื่นๆ ปลั๊กอิน WebView (ไคลเอ็นต์) ต้องสร้างการสื่อสารที่เชื่อถือได้กับแอปพลิเคชัน cTrader (โฮสต์) SDK ของปลั๊กอิน WebView ช่วยอำนวยความสะดวกในการโต้ตอบเหล่านี้กับ cTrader และคู่มือนี้จะอธิบายถึงไปป์ไลน์การสื่อสารระหว่างไคลเอ็นต์และโฮสต์

การติดตั้ง SDK ¶

SDK ของปลั๊กอิน WebView มีให้ใช้งานเป็น แพ็คเกจ npm ในการติดตั้ง SDK ให้นำทางไปยังไดเรกทอรีโปรเจกต์ของคุณในหน้าต่างเทอร์มินัล แล้วรันคำสั่งนี้:

npm install @spotware-web-team/sdk

การซิงโครไนซ์ระหว่างไคลเอ็นต์และโฮสต์ ¶

ก่อนที่จะมีการแลกเปลี่ยนข้อความใดๆ จะต้องมีการสร้างช่องทางการสื่อสารก่อน การดำเนินการทั่วไปประกอบด้วย:

1. ในช่วงเริ่มต้นของการสื่อสาร จะมีการแลกเปลี่ยนเหตุการณ์ alive ที่ทั้งไคลเอ็นต์และโฮสต์ส่งเหตุการณ์

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. สำหรับเหตุการณ์การยืนยันใหม่แต่ละครั้ง จะมีการส่งเหตุการณ์การลงทะเบียนใหม่เพื่อให้แน่ใจว่ามีการซิงโครไนซ์ แม้ว่าปลั๊กอินจะเริ่มต้นใหม่ก็ตาม

   หมายเหตุ

   หากฝ่ายใดฝ่ายหนึ่งไม่ได้รับเหตุการณ์ alive ที่เกี่ยวข้อง ปลั๊กอินจะไม่ถูกติดตั้ง เพื่อหลีกเลี่ยงการวนซ้ำ ปลั๊กอินต้องส่งเหตุการณ์การยืนยันเพียงครั้งเดียวและติดตามการไหลของข้อความ

   คำเตือน

   การส่งเหตุการณ์การยืนยันหลายครั้งจะทำให้เกิดเหตุการณ์การลงทะเบียนซ้ำๆ ซึ่งอาจส่งผลให้เกิดการวนซ้ำที่ไม่ต้องการ

คำขอ ¶

เมื่อการซิงโครไนซ์เสร็จสมบูรณ์ ปลั๊กอินสามารถโต้ตอบกับบริการ cTrader โดยเรียกใช้ เมธอด SDK ที่สื่อสารภายในกับโฮสต์

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 จัดการข้อผิดพลาดและแสดงให้ผู้สร้างปลั๊กอินเห็น