外部通信

外部通信は、cluster外に用意したサーバーと空間インスタンス内からデータをやりとりする機能です。 ItemScriptで使うことができます。

サーバーは基本的にクリエイター自身もしくは信頼している第三者が管理している必要があります。 クリエイターのアカウントごとにひとつサーバーのURLを登録できます。 クリエイターが作成した全てのワールドやアイテムは登録されたサーバーと通信します。 クラフトアイテムから外部通信を行った場合、クラフトアイテムの作者のサーバーにアクセスします。

プレイヤーのプライバシー

外部通信は空間インスタンス内のデータを外部と送受信できる強力な機能です。 プレイヤーのプライバシーを保護するため、外部通信はclusterのサーバーを経由して行われます。

プレイヤーの個人情報に該当する情報を送信する場合、プレイヤーの同意が必要です。

サーバーの準備と登録

外部通信サーバーはHTTP POSTを受け付けるendpointを提供する必要があります。

外部通信APIの呼び出しのたびに、endpointに対してHTTP POSTが一回行われます。 POSTに対するresponseに含まれるデータがonExternalCallEndに渡されます。endpointが5秒のtimeoutを超えても応答しない場合、またエラーを返した場合、失敗と判定されます。clusterからendpointに対するリトライは行いません。

リクエスト

{
  "request": "...1kB以下の文字列..."
}

レスポンス

{
  "verify": "...verify_token...",
  "response": "...1kB以下の文字列..."
}

トークン発行とURL登録

CreatorKitの「Cluster > 外部通信(callExternal)接続先URL」を選択して表示されるウィンドウからURLを登録・変更できます。URLを登録するとウィンドウにトークンが表示されます。このトークンはサーバーが自身の管理下にあることを、clusterが確認するために利用します。

トークンは通信に必要です。トークンは一度しか表示されないためコピーして別の場所に保存するようにしてください。また、URLを登録する度にトークンは変化するのでご注意ください。

callExternal APIの利用

外部通信を行うには以下のAPIを利用します。

• ClusterScript.callExternal
• ClusterScript.onExternalCallEnd