シグナルを送信する

編集
この機能は実験的な機能であり、将来仕様が変更される可能性があります。予めご了承ください。

前提

このAPIを利用する際は、APIの活用方法のヒントや使い分け方などについてまとめたAPIのセオリーも合わせてご参照ください。

概要

ユーザー間で小さなデータ(信号)をやり取りできる機能です。
シグナルAPIには、そのゲームのプレイヤー全体に対する「グローバルシグナル」と個別ユーザー間の「ユーザーシグナル」があります。

グローバルシグナルAPI概念図 ユーザーシグナルAPI概念図

なにができるのか

  • グローバルシグナルは、そのゲームをプレイしているユーザー全体への信号を送信できます。全プレイヤーのプレイログを取得したり、全員アイテムプレゼントなどが可能になります。
  • ユーザーシグナルは、ユーザーIDで指定した相手に対して信号を送信できます。共有セーブと組み合わせて、所持アイテムの交換や、キャラクターの貸し出しなどが可能になります。

利用想定/利用例

この機能は、以下のような使い方を想定しています。

  • グローバルシグナル:全ユーザーの行動ログの送信、全ユーザーへ影響を与える指示
  • ユーザーシグナル:個別ユーザー間での指示

例えば、次のサンプルゲームではグローバルシグナルを利用し、他ユーザーのプレイ状況を表示しています。

また、こちらのサンプルゲームでは、ユーザーシグナルを利用して、スライムのバトル結果を送信しています。(スライムの情報は共有セーブ最近プレイしたユーザーから取得しています)

機能詳細

  • シグナルとは、最大100byteの任意の文字データです。
  • 受信できるシグナルにはサイズ・個数ともに上限があります。制限を回避するには、なるべく小さなサイズのシグナルを推奨します。
  • 制限詳細
    • 1シグナルのデータ上限は100byteまでです。
    • 積まれたシグナルは古いシグナルから順々に押し出され削除されます。
    • グローバルシグナルは、1ゲームあたり1,000件までです。
    • ユーザーシグナルは、1ゲームあたり10KBまでと、1ユーザーあたり1,000件あるいは100KBまでです(※1ユーザーあたりの制限は、ゲーム間共通のため他ゲームからのシグナル送受信によって押し出される可能性があります)。

利用方法

シグナル機能は次の方法で利用できます。

方法場所
ゲームAPI以下の「APIでの利用方法」を参考に、直接APIを呼び出してください

APIでの利用方法

グローバルシグナルの送信

メソッドwindow.RPGAtsumaru.experimental.signal.sendSignalToGlobal(data: string)
説明ゲームのグローバルシグナルとして data で指定した文字列を送信します。
引数
  • data : シグナルとして、任意の文字列を100byte以内で送信できます。
戻り値Promise<void>
リリース日2018/12/17
更新日2018/12/17
  • 補足事項
    • グローバルシグナルはゲームあたり1,000件まで保存されます。
起こりうるエラーの種類
名前説明
UNAUTHORIZEDプレイヤーがログインしていない
BAD_REQUEST
  • data に100byte以上の文字列を指定した
  • 引数として不正な値を指定している
INTERNAL_SERVER_ERRORRPGアツマールのサービス側で何らかの問題が発生しているか、または通信に失敗した
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている

グローバルシグナルの取得

メソッドwindow.RPGAtsumaru.experimental.signal.getGlobalSignals()
説明送信されたゲームのグローバルシグナルを取得します。
引数
戻り値Promise<GlobalSignal[]>
リリース日2018/12/17
更新日2018/12/17
  • 補足事項
    • グローバルシグナルはゲームあたり1,000件まで保存されます。
戻り値の型 GlobalSignal について

戻り値で取得できる GlobalSignal は以下のような型です。

interface GlobalSignal {
    id: number;
    senderId: number;
    senderName: string;
    data: string;
    createdAt: number;
}

プロパティの内容は次のようになっています。

プロパティ名内容
idnumberシグナルそれぞれでユニークなID値
senderIdnumberシグナルを送信したユーザーのニコニコユーザーID
senderNamestringシグナルを送信したユーザーのユーザー名
datastring送信したシグナル文字列
createdAtnumberシグナルが送信された日時(秒単位のunix timestamp)。すでに処理済みのシグナルを判別するために用います。
戻り値の例
// window.RPGAtsumaru.experimental.storage.getGlobalSignals().then(function(v) { console.log(v) }) を実行
[
  {
    createdAt: 1543397700,
    data: "test data",
    id: 3,
    senderId: 12345,
    senderName: "user1"
  },
  {
    createdAt: 1543397701,
    data: "test data2",
    id: 4,
    senderId: 12346,
    senderName: "user2"
  },
]
起こりうるエラーの種類
名前説明
INTERNAL_SERVER_ERRORRPGアツマールのサービス側で何らかの問題が発生しているか、または通信に失敗した
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている

ユーザーシグナルの送信

メソッドwindow.RPGAtsumaru.experimental.signal.sendSignalToUser(receiverId: number, data: string)
説明ユーザーシグナルとして receiverId で指定したユーザーIDのユーザーに data で指定した文字列を送信します。
引数
  • receiverId : 送信先のニコニコユーザーIDを指定します。
  • data : シグナルとして、任意の文字列を100byte以内で送信できます。
戻り値Promise<void>
リリース日2018/12/17
更新日2018/12/17
  • 補足事項
    • ユーザーシグナルは、ユーザーあたり1,000件までか、100KB保存されます。
    • また、ゲームあたり1ユーザー10KBまでとなります。
      • ゲームからのシグナル送信によって、古いシグナルから消えていきます。
      • 他のゲームからのシグナル送信によっても消える可能性があります。
起こりうるエラーの種類
名前説明
UNAUTHORIZEDプレイヤーがログインしていない
FORBIDDENuserIdプレイヤー間通信の有効化を行っていないユーザーのIDを指定した
BAD_REQUEST
  • data に100byte以上の文字列を指定した
  • 引数として不正な値を指定している
INTERNAL_SERVER_ERRORRPGアツマールのサービス側で何らかの問題が発生しているか、または通信に失敗した
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている

ユーザーシグナルの取得

メソッドwindow.RPGAtsumaru.experimental.signal.getUserSignals()
説明プレイしているユーザーのユーザーシグナルを取得します。
引数
戻り値Promise<UserSignal[]>
リリース日2018/12/17
更新日2018/12/17
  • 補足事項
    • ユーザーシグナルは、ユーザーあたり1,000件までか、100KB保存されます。
    • また、ゲームあたり1ユーザー10KBまでとなります。
      • ゲームからのシグナル送信によって、古いシグナルから消えていきます。
      • 他のゲームからのシグナル送信によっても消える可能性があります。
戻り値の型 UserSignal について

戻り値で取得できる UserSignal は以下のような型です。

interface UserSignal {
    id: number;
    senderId: number;
    senderName: string;
    data: string;
    createdAt: number;
}

プロパティの内容は次のようになっています。

プロパティ名内容
idnumberシグナルそれぞれでユニークなID値
senderIdnumberシグナルを送信したユーザーのニコニコユーザーID
senderNamestringシグナルを送信したユーザーのユーザー名
datastring送信したシグナル文字列
createdAtnumberシグナルが送信された日時(秒単位のunix timestamp)。すでに処理済みのシグナルを判別するために用います。
戻り値の例
// window.RPGAtsumaru.experimental.signal.getUserSignals().then(function(v) { console.log(v) }) を実行
[
  {
    createdAt: 1543397700,
    data: "test data",
    id: 3,
    senderId: 12345,
    senderName: "user1"
  },
  {
    createdAt: 1543397701,
    data: "test data2",
    id: 4,
    senderId: 12346,
    senderName: "user2"
  },
]
起こりうるエラーの種類
名前説明
UNAUTHORIZEDプレイヤーがログインしていない
INTERNAL_SERVER_ERRORRPGアツマールのサービス側で何らかの問題が発生しているか、または通信に失敗した
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている