Chat Webhooks

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

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

設定

基礎設定

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

パス

それぞれのパスが、それぞれが自分のホストで識別できるURIにおいてイベントを受信できるように設定してください。空で残されたパスはヒットしません。
影響を受けるwebhook上ではあらゆるコールバックを受けることはありません。
設定する値にクエリ文字列が含まれる場合は、こちら をお読みください。

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

オプション

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

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

クエリ文字列の処理

クエリ文字列パラメータはベースURLまたはパスに含まれています。これを使用する場合は、以下の事柄について理解しておいてください。

• クエリ文字列パラメータはUTF8エンコードで解析されます。
• 同じクエリ文字列パラメータの複数同時発生が、同一の設定内で見られる場合は、カンマで各値を区切りながら単一のパラメータが使用されます。
  カンマは%2cを使用してエスケープされます。
• ベースURLと設定済みのパスで同じパラメータキーが使用されている場合、パス設定の値が使用されます。
• 値のないパラメータは認められています。
• キーのないパラメータは認められています。
  キーは空の文字列とみなされます。
  ベースURLと設定済パスの両方でキーが足りないパラメータが見つかった場合、設定済パスのもののみが使用されます。
• クエリ文字列パラメータはURLエンコードとなります。
• クエリ文字列パラメータ内でURLタグを使用できます。

例:

• 設定:

  • ベースURL:

    https://myawesomegame.com/chat/webhooks?clientver={AppVersion}&key=&keyA=valueA&keyA=valueB&keyB=valueB&=value
    

  • PathChannelCreate: create?key=X&keyA=valueC
  • PathChannelDestroy: destroy?keyB=valueC&keyC=valueC&=valueD&=valueE

• 生じるURL:

  • PathChannelCreate:

    https://myawesomegame.com/chat/webhooks/create?clientver=1.0&key=X&keyA=valueC&keyB=valueB&=value
    

  • PathChannelDestroy:

    https://myawesomegame.com/chat/webhooks/destroy?clientver=1.1&key=&keyA=valueA%2cvalueB&keyB=valueC&keyC=valueC&=valueD%2cvalueE
    

HTTP Headers Considerations

カスタムHTTPヘッダーの使用にあたり、いくつかの留意事項があります:

• CustomHttpHeaders設定キーの値は、文字列に変更された、文字列以外を含まないプロパティのJSONオブジェクトである必要があります。JSONオブジェクトのプロパティ名は、HTTPリクエストヘッダフィールド名として使用され、プロパティの値はリクエストヘッダーのそれぞれの値として使用されます。
  例:

  • CustomHttpHeaders 値:

    {'X-Secret': 'YWxhZGRpbjpvcGVuc2VzYW1l', 'X-Origin': 'Photon'}
    

  • Webhooks HTTP リクエストヘッダー:

    X-Secret: YWxhZGRpbjpvcGVuc2VzYW1l
    X-Origin: Photon
    

• カスタムHTTPヘッダーフィールド名は大文字と小文字を区別します。

• 次のHTTPヘッダーは制限されており、"CustomHttpHeaders"設定値から設定された場合、無視されます。

  • Connection
  • Content-Length
  • Host
  • Range
  • Proxy-Connection
  • Accept
  • Content-Type
  • Date
  • Expect
  • If-Modified-Since
  • Referer
  • Transfer-Encoding
  • User-Agent

URLタグ

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

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

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

URLタグの例

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

全てのwebhookへの共通引数

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

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

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

ChannelType:
チャンネルタイプ：パブリックチャンネルの場合はPublic、プライベートチャネルの場合はPrivate。

UserId:
フックをトリガーするプレイヤーのユーザーID（ChannelDestoryを除く）。

HistoryCount:
チャンネル履歴内のメッセージの現在の数（ChannelDestoryを除く）。

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

UsersPair:
プライベートチャンネルの両端のUserIDを含む2つの文字列の配列。（プライベートチャンネルのみ）。

Request Arguments List

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

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

プライベートチャンネルの場合、次の引数を持つ単一のwebhook PublishMessageがあります：

• AppId
• AppVersion
• Region
• ChannelType (Privateに設定)
• UsersPair
• HistoryCount
• UserId

詳細なパス

チャンネル作成

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

特定の引数

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

サンプル呼び出し

text

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

ChannelDestroy

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

特定の引数

ChannelState:
直列化可能なチャンネル状態。

サンプル呼び出し

text

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Public",
   "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
            }
         ]
      }
   }
}

ChannelSubscribe

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

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

特定の引数

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

サンプル呼び出し

text

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

ChannelUnsubscribe

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

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

特定の引数

ChannelUnsubscribeには追加の引数はありません。

サンプル呼び出し

text

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

PublishMessage

このwebhookは、クライアントがチャンネルにメッセージを公開するか、ユーザーにプライベートメッセージを送信するとトリガーされます。
クライアントは、適切なWebFlagを使用して、メッセージをwebhookとしてHTTP転送することを明示的に選択する必要があります。
公開するメッセージを置き換えたい場合は、 Dataパラメーターで新しいメッセージを返すことができます。
返されたwebhookレスポンスの Dataプロパティの値は、クライアントによって送信された元のメッセージコンテンツではなく、チャンネル内で公開されます。
例は"Return Values" でご確認ください。

Photonの直列化で対応されている任意のタイプのデータを使用できます。
使用例の1つは、Webサーバーからのデータポーリングです。
DataリターンパラメータはPhoton RealtimeのWebRPCのように使用することもできます。

特定の引数

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

サンプル呼び出し

text

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

プライベートチャンネル: サンプル呼び出し

text

{
   "AppId":"00000000-0000-0000-0000-000000000000",
   "AppVersion":"1.0",
   "Region":"EU",
   "ChannelType":"Private",
   "UsersPair":["testClient1", "testClient2"],
   "HistoryCount":1,
   "UserId":"testClient2",
   "Message":"msg2"
}

戻り値

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

• 成功の場合は0

サンプル成功レスポンス

text

{
   "ResultCode":0,
   "Message":"OK"
}

• その他全ての整数は失敗

サンプル失敗レスポンス

text

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

"PublishMessage"webhookは、Webサーバーからの Dataの追加プロパティに対応しています。

サンプル "完全な" PublishMessage Response

text

{
   "ResultCode":0,
   "DebugMessage":"Message Will Be Overridden By Server",
   "Data": "Anything you want and supported by Photon Serialization"
}

"ChannelCreate" webhookは、 ChannelStateであるWebサーバーからの追加のプロパティに対応しています。

サンプル "完全な" ChannelCreateResponse

text

{
   "ResultCode":0,
   "DebugMessage":"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"は、デバッグに有用であるものの情報のロードには必要ないため、情報を保存するときあるいはロードするときに破棄することができます。

サンプル "Stripped" ChannelCreateResponse

text

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

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

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

Response Arguments List

以下の表には、どのチャットオペレーションがwebhookを利用中にキャンセルまたは中断可能であるかが示されています。

Argument	ChannelCreate	PublishMessage	others
ResultCode
DebugMessage	(optional)	(optional)	(optional)
Data		(optional)
ChannelState	(optional)

Cancelable Operations

以下の表は、webhookを使用してキャンセルまたは中止できるチャット操作を示しています。
そのためには、0以外の ResultCodeと、オプションで OperationResponseの DebugMessageにある DebugMessageを返す必要があります。

Webhook	Can Be Canceled
ChannelCreate
ChannelDestory
ChannelSubscribe
ChannelUnsubscribe
PublishMessage

データ型の変換

ここでは、Photon ServerとWebサービス間で通信するデータ型のみを説明します。
クライアントとPhoton Server間で通信するデータ型の詳細は、Photonのシリアライゼーションをご覧ください。

Photon Server -> Webサービス

C# / .NET (Photon supported types)	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 (of supported types, count < short.MaxValue, preferably Photon implementation)	object
Dictionary (keys and values of supported types, count < short.MaxValue)	object
null	null

リクエストデータ（型を連結済み）のサンプル

Photon Serverからの送信

JSON

{
    "(Dictionary<String,Object>)Dictionary":{
        "(Int32)dk_int":"1",
        "(String)dk_str":"dv2",
        "(Boolean)dk_bool":"True"
    },
    "(Hashtable)Hashtable":{
        "(Byte)hk_byte":"255",
        "(Object[])hk_array":[
            "(Int32)0",
            "(String)xy",
            "(Boolean)False"
        ],
        "hk_null":"null"
    },
    "null":"null",
    "(String[])string[]":[
        "PUN",
        "TB",
        "RT",
        "Bolt",
        "Chat"
    ],
    "(Byte[])byte[]":[
        "255",
        "0"
    ],
    "(Int16[])short[]":[
        "-32768",
        "32767"
    ],
    "(Int32[])int[]":[
        "-2147483648",
        "2147483647"
    ],
    "(Int64[])long[]":[
        "-9223372036854775808",
        "9223372036854775807"
    ],
    "(Single[])float[]":[
        "-3.402823E+38",
        "3.402823E+38"
    ],
    "(Double[])double[]":[
        "-1.79769313486232E+308",
        "1.79769313486232E+308"
    ],
    "(Boolean[])bool[]":[
        "True",
        "False"
    ]
}

Webサービスでの読み込み

JSON

{
    "(object)Dictionary":{
        "dk_int":"(number)1",
        "dk_str":"(string)dv2",
        "dk_bool":"(boolean)true"
    },
    "(object)Hashtable":{
        "(number)hk_byte":"255",
        "(array)hk_array":[
            "(number)0",
            "(string)xy",
            "(boolean)false"
        ],
        "hk_null":null
    },
    "null":null,
    "(array)string[]":[
        "(string)PUN",
        "(string)TB",
        "(string)RT",
        "(string)Bolt",
        "(string)Chat"
    ],
    "byte[]":"(string)/wA=",
    "(array)short[]":[
        "(number)-32768",
        "(number)32767"
    ],
    "(array)int[]":[
        "(number)-2147483648",
        "(number)2147483647"
    ],
    "(array)long[]":[
        "(number)-9223372036854776000",
        "(number)9223372036854776000"
    ],
    "(array)float[]":[
        "(number)-3.40282347e+38",
        "(number)3.40282347e+38"
    ],
    "(array)double[]":[
        "(number)-1.7976931348623157e+308",
        "(number)1.7976931348623157e+308"
    ],
    "(array)bool[]":[
        "(boolean)true",
        "(boolean)false"
    ]
}

Webサービス -> Photon Server

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 (not a type)	null
undefined (when sent)	null

レスポンスデータ（型を連結済み）のサンプル

Webサービスからの送信

JSON

{
    "(object)number": {
        "(number)MAX_VALUE": "1.7976931348623157e+308",
        "(number)MIN_VALUE": "5e-324"
    },
    "(object)object": {
        "(string)string": "xyz",
        "null": null,
        "(boolean)bool": "false",
        "(undefined)undefined": "undefined",
        "(number)float": "-3.14",
        "(number)integer": "123456"
    },
    "(array)array": [
        "(string)xyz",
        "(number)0",
        "(boolean)true",
        null,
        "(undefined)undefined"
    ]
}

Photon Serverでの読み込み

JSON

{
    "(Dictionary<String,Object>)number":{
        "(Double)MAX_VALUE":"1.79769313486232E+308",
        "(Double)MIN_VALUE":"4.94065645841247E-324"
    },
    "(Dictionary<String,Object>)object":{
        "(String)string":"xyz",
        "null":"null",
        "(Boolean)bool":"False",
        "(Double)float":"-3.14",
        "(Int64)integer":"123456"
    },
    "(Object[])array":[ 
        "(String)xyz",
        "(Int64)0",
        "(Boolean)True",
        "null",
        "null"
    ]
}

Webhookを保護する

HTTPSと最新のTLSバージョンの使用だけでなく、カスタムHTTPリクエストヘッダ や クエリ文字列パラメータを使用してwebhookセキュリティを強化できます。
受信するHTTPリクエストがPhoton Serverで生成されいることがわかるように、Photonのダッシュボードで１つもしくは複数の「秘密」（「トークン」、「キー」など）を設定します。

Back to top