Chat Webhooks

Photon CloudでWebhookを用いることで、チャットアプリケーションをより制御することができるようになります。 チャンネル履歴を継続したり、メッセージをフィルタリングしたり、チャンネル作成をキャンセルしたり、特定のプレイヤーにチャットルームの登録を禁止したりすることができるようになります。

Photon Chat webhookは、イベントにより制御されるPhoton Cloudから特定のURLに送信されるHTTP POSTリクエストです。 それぞれのPhoton Chat webhookは、それ自身のトリガーやデータ、目的地経路によって定義されます。

Contents

設定

基礎設定

  • ベースURL (必須)
    フックをホストしているサービスのURLです。 フォワードスラッシュ(バックスラッシュでないスラッシュ)で終わっていないものです。 コールバックは、設定されたフックの関連するパスURLで受信されます。
  • カスタムHttpヘッダー
    設定されたウェブサービスに対して行われたいかなるリクエストにおいても、公開鍵と秘密鍵または値のペアが含まれるJSONオブジェクトはHTTPヘッダーとして設定できません。

Back To Top

パス

それぞれのパスが、それぞれがあなたのホストで識別できるURIにおいてイベントを受信できるように設定してください。空で残されたパスはヒットしません。 影響を受けるwebhook上ではあらゆるコールバックを受けることはありません。

  • パスチャンネル作成
    新たなチャンネルが作成されたとき、またはその状態が外部サービスからロードされる必要がある際に呼び出されます。
  • パスチャンネル崩壊
    チャンネルがPhotonサーバーのメモリから取り除かれる際に呼び出されます。 IsPersistenttrueに設定されている場合、チャンネルの状態が送信されます。
  • パスチャンネル登録
    プレイヤーが既に作成されたチャンネルに登録している場合に呼び出されます。
  • パスチャンネル登録解除
    プレイヤーがチャンネルから登録解除した場合に呼び出されます。
  • パス発行メッセージ
    クライアントがチャンネル内でメッセージを発行した場合に呼び出されます。

Back To Top

オプション

これらのオプションにより、チャットのwebhook設定の挙動を微調整できます。 設定されていない場合、またはその値が空のままになっている場合、オプションは設定されている状態であるとはされません。

  • 利用できない場合は失敗
    trueに設定されている場合、チャンネル作成、登録、発行メッセージのオペレーションは、対応するフックの設定されたエンドポイントが利用可能でないときに失敗することとなります。 そのHTTPリクエストのプロセス中にエラーが発生した場合、またはHTTPレスポンスが成功していない場合には、エンドポイントが利用可能ではないとされます。 デフォルトではfalseとなっています。
  • は継続です
    trueに設定されている場合、Photon Cloudは破棄の前にチャンネル情報を送信します。 このオプションが有効なのは、PathChannelCreatePathChannelDestroy の両方が適切に設定されており、かつ MaxChannelHistory が0を上回っている場合のみです。 詳細については、ChannelCreateおよびChannelDestroyのwebhookを読んでください。 デフォルトはfalseです。
  • MaxChannelHistory チャンネルごとに継続される最大メッセージ数です。 1から100の間が推奨されます。 デフォルトは100です。
  • HasErrorInfo trueに設定されている場合、hookのエンドポイントが利用できないのに FailIfUnavailablefalseに設定されているとき、チャットクライアントはエラーメッセージで通知されます。 デフォルトはfalseです。
  • SkipPostCreationFailure trueに設定されている場合、PathUnsubscribe および PathChannelDestroy のwebhookは、チャンネル作成が失敗した後に送信されません。 デフォルトはfalseです。

Back To Top

共通基準

全てのwebhookへの共通引数

アプリケーションID: ゲームクライアントから設定されている、ダッシュボードで見られるアプリケーションのアプリケーションID

アプリケーションのバージョン: ゲームクライアント側で設定されているアプリケーションのバージョン

リージョン: ゲームクライアントが接続される、および件のルームが属する領域を持っている

チャンネル名: フックがトリガー動作しているチャンネルの名前

Back To Top

ChannelDestroy以外の全てのwebhookに対する共通引数

ユーザーID: フックのトリガーとなっているプレイヤーのユーザーID

Back To Top

ChannelCreate以外の全てのwebhookに対する共通引数

履歴カウント: チャンネルの履歴にあるメッセージの現在のカウント

Back To Top

引数リスト

この表から、それぞれのwebhookについて何の引数を用いることができるかが分かります:

引数 ChannelCreate /
ChannelSubscribe
ChannelDestroy PublishMessage ChannelUnsubcribe
AppId
AppVersion
Region
ChannelType ("Public")
ChannelName
HistoryLen
HistoryCount
UserId
ChannelState
Message

Back To Top

詳細なパス

チャンネル作成

このwebhookは、チャンネルがPhotonサーバー上で作成されようとしているときに送信されます。 前回保存されたチャンネル状態がある場合、履歴をロードするためのwebhookレスポンスにおいてそれを戻さなければなりません。 例としては、"戻り値を確認してください。

Back To Top

特定の引数

HistoryLen: 登録オペレーションの中でクライアントにより設定されているものと同じ名前を持つパラメータを転送します。 これには、クライアントから要請を受けた履歴からのメッセージ数も含まれます。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelName":"PersistentChannel",
   "HistoryLen":10,
   "UserId":"testClient1"
}

Back To Top

チャンネル破棄

本webhookは、チャンネルがPhotonサーバー上で破棄されようとしているときに送信されます。 これは、空のチャンネルがタイムアウトした際に発生します。 チャンネルが空とされるのは、登録者が離れたために一人もいない場合です。 デフォルトの空チャンネルタイムアウト値は5秒となっています。 IsPersistenttrueに設定されており、PathChannelDestroy が適切に設定されている場合、 ChannelStateがwebhookボディ内で送信されます。 ChannelState内ではHistoryオブジェクトは単にデバッグ用です。これは破棄することができます。 PhotonサーバーはBinaryHistoryを用いてデータタイプを追跡します。 チャンネル履歴を後にロードする場合、as is で保存してください。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelName":"PersistentChannel",
   "HistoryCount":2,
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp..",
      "History":{
         "MessageIdBase":2,
         "Entries":[
            {
               "Message":"msg1",
               "Sender":"testClient1",
               "MsgId":1
            },
            {
               "Message":"msg2",
               "Sender":"testClient2",
               "MsgId":2
            }
         ]
      }
   }
}

Back To Top

チャンネル登録

本webhookのトリガーは、既に作成されたチャンネルへのクライアントの登録です。 クライアントには以下のケースがあります::

  • 最初の登録者ではない。最もよくあるケースです。
  • チャンネルが空でタイムアウトしていなかった場合、最初の登録者となります。時間が短いため、あまりあることではありません。

Back To Top

特定の引数

HistoryLen: 登録オペレーションの中でクライアントにより設定されているものと同じ名前を持つパラメータを転送します。 これには、クライアントから要請を受けた履歴からのメッセージ数も含まれます。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelName":"PersistentChannel",
   "HistoryLen":-1,
   "HistoryCount": 1,
   "UserId":"testClient2"
}

Back To Top

チャンネル登録解除

本webhookのトリガーは、クライアントがチャンネルとの接続を切ったときです。これは、以下の理由で起こりえます。

  • 登録解除オペレーションを意識的に呼び出したとき。
  • 意識的に接続を切ったとき。
  • タイムアウトによる接続切れ。
  • チャンネル作成が失敗し、SkipPostCreationFailurefalseに設定されているとき。
  • 登録が失敗したとき。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelName":"PersistentChannel",
   "HistoryCount":2,
   "UserId":"testClient2"
}

Back To Top

発行メッセージ

本webhookのトリガーは、チャンネルにメッセージを発行したときです。

特定の引数

Message: チャンネルの全ての登録者に対して発行されるメッセージです。クライアントから送信されると転送されます。

サンプル呼び出し

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelName":"PersistentChannel",
   "HistoryCount":1,
   "UserId":"testClient2",
   "Message":"msg2"
}

Back To Top

戻り値

全てのwebhookには、ResultCodeが含まれるJSONオブジェクトが期待されます。ResultCodeは以下のものである可能性があります::

  • 成功のための0

サンプル成功レスポンス

{
   "ResultCode":0,
   "Message":"OK"
}
  • 失敗に関するその他全ての整数

サンプル失敗レスポンス

{
   "ResultCode":1,
   "Message":"A nice self explained error message"
}

"ChannelCreate"webhookはChannelStateのウェブサーバーから 余分なプロパティを取得することもあります。

サンプル "フル" ChannelCreateレスポンス

{
   "ResultCode":0,
   "Message":"ChannelState Loaded Successfully",
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp..",
      "History":{
         "MessageIdBase":2,
         "Entries":[
            {
               "Message":"msg1",
               "Sender":"testClient1",
               "MsgId":1
            },
            {
               "Message":"msg2",
               "Sender":"testClient2",
               "MsgId":2
            }
         ]
      }
   }
}

"History"は、デバッグに有用であるものの情報のロードには必要ないため、情報を保存するときあるいはロードするときに破棄することができます。

サンプル"裸"ChannelCreateレスポンス

{
   "ResultCode":0,
   "Message":"ChannelState Loaded Successfully",
   "ChannelState":{
      "ChannelHistoryCapacity":100,
      "BinaryHistory": "RGl6AAEAAAAAAAN6AANp.."
   }
}

ベストプラクティスと考えられるのは以下です:

  • カスタムユーザーエラータイプごとに確保されたResultCode値のリストを作る
  • デバッグに有用な可能性のあるMessage文字列を戻す

以下の表には、どのチャットオペレーションがwebhookを利用中にキャンセルまたは中断可能であるかが示されています。 このためには、0以外のResultCodeを返し、OperationResponseDebugMessageにあるMessageを返す必要があります(後者は必須ではありません)。

Webhook はキャンセル可能です
ChannelCreate
ChannelDestory
ChannelSubscribe
ChannelUnsubscribe
PublishMessage

Back To Top

URLタグ

ダッシュボードからwebhookまたはWebRpcのベースURLを設定する場合、必要に応じて、クエリ文字列の一部として1つ以上の動的変数 を設定することができます。 これらの変数は、要求を送信する前に、バックエンドでそれぞれの値に置き換えられます。

それぞれのアプリケーションのユーザー・セグメントを個別に処理したい場合は、URLのタグを使用します。 Photonは、次のURLのタグに対応しています:

  • {AppVersion} クライアントによって設定されたアプリケーションのバージョンを渡します。
  • {AppId} アプリケーションのIDを渡します。
  • {Region} トリガークライアントが接続されているクラウドリージョンのトークンを渡します。例:"eu"
  • {Cloud} は、トリガークライアントが接続されているクラウドの名前を渡します。例:「public」または「enigmaticenterprise」

Back To Top

URLタグの例

  1. https://{Region}.mydomain.com/{AppId}?version={AppVersion}&cloud={Cloud} 例:パラメータとして渡される異なるホスト、バージョン、およびクラウドに各リージョンをルート。
  2. https://mydomain.com/{Cloud}/{Region}/{AppId}/{AppVersion} 構造化されたURIとしてすべてのタグを渡します。

Back To Top

データ型の変換

このセクションでは、Photonクラウドとウェブサービスの間で交換されるデータ型のみが説明されています。クライアントとPhotonサーバ間のデータ型の詳細はPhotonページのシリアル化を参照してください。

Photon Cloud -> ウェブサービス

C# / .Net (Photonが対応するタイプ) JavaScript / JSON
byte number
short
int
long
double
bool bool
string string
byte[] (byte array length < short.MaxValue) string (Base64 encoded)
T[] (array of supported type T, length < short.MaxValue) array
Hashtable (対応されているタイプの, カウント < short.MaxValue, Photon実装が望ましい) object
Dictionary (対応されているタイプのキーや値, カウント < short.MaxValue) object
null null

Back To Top

サンプルリクエストデータ(タイプは連結されます)

Photonクラウドから送信:

ウェブサーバによって読み込み:

Back To Top

ウェブサービス - >Photon Cloud

各JavaScript/JSONタイプをC#/.Netの同等のものに照らし合わせる表:

JavaScript / JSON C# / .Net
object Dictionary
array object[] (array of objects)
number (integral) long
number (floating) double
string string
boolean bool
null (タイプではない) null
undefined(送信時) null

Back To Top

サンプルのレスポンスデータ(タイプは連結されています)

ウェブサーバーから送信:

Photon Cloudから読み込み:

ドキュメントのトップへ戻る