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

   内部的には、2つの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にdeeplink（内部URL）を開くよう要求するために、このリクエストを送信できます:

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

プラグインはその後、応答を待ち受けます:

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

WebViewプラグインは、以下に示すようにサポートされているdeeplinkを実装できます:

// 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がエラーを処理し、プラグイン作成者にそれを表示します。