メッセージング API

メッセージング API は、同じストーリー内で動いている複数のスクリプト同士の通信を可能にします。スクリプト間で挙動を協調させたり、データを共有したりできます。

メッセージの種類

送信できるメッセージは 2 種類です。

  • ダイレクトメッセージ：スクリプト ID を指定して特定スクリプトへ送信
  • ブロードキャストメッセージ：待ち受けている全スクリプトへ送信

メッセージを送る

特定スクリプトへ送信

api.v1.messaging.send に相手スクリプトの ID とデータを渡します。

await api.v1.messaging.send('target-script-id', {
  type: 'greeting',
  text: 'Hello from another script!'
});

メッセージデータは、シリアライズ可能なオブジェクトなら何でも構いません（関数を含むものや循環参照のあるオブジェクトは送れません）。

全スクリプトへブロードキャスト

api.v1.messaging.broadcast を使います。

await api.v1.messaging.broadcast({
  type: 'notification',
  event: 'generation-complete',
  timestamp: Date.now()
});

メッセージハンドラを登録しているスクリプトは、全てブロードキャストを受信します。

メッセージを受け取る

ハンドラの登録

受信するには api.v1.messaging.onMessage でハンドラを登録します。

let unsubscribe = api.v1.messaging.onMessage((message) => {
  api.v1.log(`Received message from ${message.fromScriptId}: ${JSON.stringify(message)}`);
  
  if (message.data.type === 'greeting') {
    api.v1.log(`Greeting message: ${message.data.text}`);
  }
});

ハンドラには、メッセージデータ、送信元のスクリプト ID などを含む message オブジェクトが渡されます。

受信を停止する（購読解除）

onMessage は購読 ID（subscription index）を返します。後で unsubscribe して受信を止められます。

let unsubId = await api.v1.messaging.onMessage((message) => {
  // Handle message
});

// Later, when you want to stop receiving messages:
api.v1.messaging.unsubscribe(unsubId)

スクリプト ID を知る

特定スクリプトへ送るには相手の ID が必要です。自分自身の ID は api.v1.script.id で取得できます。

api.v1.log(`My script ID: ${api.v1.script.id}`);

ID のハードコードは変更に弱いためおすすめしません。代替として、ブロードキャストで動的に発見する方式が便利です。

参考