استخدام SDK لإضافات WV¶

لدعم استرجاع بيانات المستخدم وتنفيذ التداول ومعالجة الأحداث والمزيد، يجب على إضافة WebView (العميل) إنشاء اتصال موثوق مع تطبيق cTrader (المضيف). يُسهّل SDK لإضافات WebView هذه التفاعلات مع cTrader، ويشرح هذا الدليل خط الاتصال بين العميل والمضيف.

تثبيت SDK ¶

يتوفر SDK لإضافات WebView كـ حزمة npm. لتثبيت SDK، انتقل إلى دليل مشروعك في نافذة طرفية ثم شغِّل هذا الأمر:

npm install @spotware-web-team/sdk

مزامنة العميل والمضيف ¶

قبل أن يتم تبادل أي رسالة، يجب إنشاء قناة اتصال. تشمل العمليات النموذجية التالي:

1. في بداية الاتصال، يحدث تبادل لحدث مباشر حيث يُرسل كل من العميل والمضيف حدثًا.

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. لكل حدث تأكيد جديد، يتم إرسال حدث تسجيل جديد لضمان المزامنة، حتى إذا قامت الإضافة بإعادة التهيئة.

   ملاحظة

   إذا فشل أي من الطرفين في استلام حدث مباشر مقابل، فلن يتم تحميل الإضافة. لتجنب الحلقات، يجب على الإضافة إرسال حدث التأكيد مرة واحدة فقط وتتبع تدفق الرسائل.

   تحذير

   يؤدي إرسال أحداث تأكيد متعددة إلى تفعيل أحداث تسجيل متكررة، ما قد يؤدي إلى حلقة غير مقصودة.

الطلبات ¶

بمجرد اكتمال المزامنة، يمكن للإضافة التفاعل مع خدمات 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 مع الخطأ ويظهره لمنشئ الإضافة.