WV 플러그인 SDK 사용¶

사용자 데이터 검색, 거래 실행, 이벤트 처리 등을 지원하기 위해 WebView 플러그인(클라이언트)는 cTrader 애플리케이션(호스트)와 신뢰할 수 있는 통신을 설정해야 합니다. WebView 플러그인 SDK는 이러한 상호 작용을 cTrader와 원활하게 지원하며, 이 가이드는 클라이언트와 호스트 간의 통신 파이프라인을 설명합니다.

SDK 설치 ¶

WebView 플러그인 SDK는 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 이벤트를 수신하지 못하면, 플러그인은 마운트되지 않습니다. 루프를 방지하기 위해, 플러그인은 확인 이벤트를 한 번만 전송하고 메시지 흐름을 추적해야 합니다.

   경고

   여러 확인 이벤트를 전송하면 반복된 등록 이벤트가 발생하여 의도하지 않은 루프가 발생할 수 있습니다.

요청 ¶

동기화가 완료되면, 플러그인은 호스트와 내부적으로 통신하는 SDK 메서드를 호출하여 cTrader 서비스와 상호작용할 수 있습니다.

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가 오류를 처리하고 플러그인 생성자에게 표시함.