Webhook

Photon Cloud でWebhookを使用するとアプリケーションを拡張でき、ゲームへのプレイヤーの再参加や、プレイヤーおよびゲームデータの保持が可能になります。

Photon WebhookはPhoton Cloud によって特定のURLに送信されるイベント駆動型のHTTP POSTリクエストです。 それぞれのPhoton Webhookは、それぞれ固有のトリガー、データ、目的地へのパスによって定義されます。

Webhook 1.2の新機能は こちらで参照してください。

目次

セットアップ

Photon CloudでWebhookをセットアップするには、ダッシュボードのアプリケーションリストの管理リンクをクリックしてください。 Webhookセクションに新規のWebhookを追加するか、または既存のWebhookを変更してください。

Webhook設定ページで、あらかじめ定義されたプリセットをドロップダウンリストから1つ選択します。 "デモ"プリセットは、開発環境でのみ使用してください。 このプリセットは、利用できる様々な設定の概要や、それらの使用方法を表示する際に使用します。

キー/値のセットを含む文字列を定義してコンフィグレーションをおこないます。 許容されるキーの最大長は256文字、値の最大長は1,024文字型です。

基本設定

  • BaseUrl (必須)
    WebRPCで呼ばれるすべてのメソッドと同様に、利用しているhookをホスティングしているサービスのURLです。 このURLの末尾にスラッシュは記載できません。 コールバックは以下で設定された相対パスURIで受信されます。
  • CustomHttpHeaders
    設定されたWebサービスに対して行なわれるすべての要求にHTTPヘッダーとして設定されるべき、キー/値のセットを含むJSONオブジェクト。

パス

ホスト上で識別される各URIでイベントを受け取るために、それぞれのパスを設定します。 空のままのパスを使用するとヒットされず、影響を受けたWebhook上でコールバックを受け取ることはありません。

  • PathCreate
    新規ルームが作成される時や、外部サービスからステートを読み込む必要がある時に呼ばれます。
  • PathClose
    ルームがPhotonサーバーのメモリから削除されると呼ばれます。 IsPersistent_がtrueに設定されている場合には、ルームのステートが送信されます。

  • PathJoin
    ルームがPhotonサーバのメモリにある際にプレイヤーが参加すると呼ばれます。

  • PathLeave
    プレイヤーがルームを出るときに呼ばれます。
  • PathEvent
    クライアントが、WebフラグHttpForwardが設定されたルームでイベントを上げた場合に呼ばれます。
  • PathGameProperties
    クライアントが、WebフラグHttpForwardを設定したルームやプレイヤープロパティを設定した場合に呼ばれます。

オプション

これらのオプションを使用すれば、Webhookの動作を微調整できます。 オプションは、設定されていない場合や、値が空の場合には設定されていないとみなされます。 各オプションのデフォルト値はfalseで、値が設定されていない場合に適用されます。

  • HasErrorInfo
    trueに設定すると、hookへのコールが失敗した場合にクライアントにErrorEventが通知されます。
  • IsPersistent
    trueに設定すると、Photon Cloudは、メモリからルームを削除する前にステートを送信します。 このオプションはPathCreatePathCloseが正常に設定されている場合にのみ有効です。 詳細な情報は、GameCreateGameCloseWebhookをご参照ください。
  • AsyncJoin
    このオプションは、IsPersistenttrueに設定されている場合にのみ有効です。 デフォルトではtrueに設定されており、サーバー上の名前でルームを見つけることができないjoinオペレーションがWebhookとしてWebサービスに転送されます。 この動作を非有効化するには、falseに設定してください。 詳細はこちらを参照してください。

ターンキーソリューション

Microsoft AzureとHerokuで利用可能な最新のターンキーインストレーションについては、弊社のgithubページを参照してください。 Bitbucket上にも、Javaを使用したPhoton Webhook用のサードパーティのソリューションを用意しています。

共通のクライテリア

すべてのPhotonのWebhookは、POSTするベースURL、Webサーバーで起こり得るエラーを返す能力、それぞれに送信されるベースラインデータを共有しています。

すべてのWebhookに共通の引数

AppId: ゲームクライアントから設定され、ダッシュボードで確認できる、アプリケーションのAppId。

AppVersion: ゲームクライアントから設定されるアプリケーションのバージョン。

Region: ゲームクライアントが接続され、該当のルームが所属するリージョン。

GameId: ルームのIDまたは名前。

Type: Webhookのタイプ。PathEventWebhookでは常に"Event"です。PathJoinwebhookでは常に"Join"です。その他のすべてのwebhookでは複数の値を持つことが可能です。

PathClose以外のすべてのWebhookに共通の引数

ActorNr: hookをトリガーするアクターの数。

UserId: hookをトリガーするアクターのUserId。

NickName: クライアントSDKから設定されたhookをトリガーするアクターの名前。

戻り値

想定されるレスポンス

Webhookを送る際、Photon Cloudはほとんどの場合、JSONオブジェクトのResultCodeプロパティが0に設定されたレスポンスのみを期待します。

ResultCodeがゼロならば、Webhookリクエストが受信され、Webサーバー上で正常に処理されていることを確認できます。

Webhookのコールに対して、ゼロ以外のResultCodeを伴うリターンオブジェクトの場合にはどのようなWebhookのコールでも、失敗と認識されます。

HasErrorInfoがtrueに設定されている場合、まだルームに参加しているクライアントにErrorInfoイベントが送信されます。 PathCreateの場合を除き、このような状況でもサーバーは通常の処理を続行します。イベントにはParameterCode.Infoも含まれます。詳細はSDKのAPIドキュメントを参照してください。

Photon Cloudによってすでに閉じられてメモリーから削除されたルームにプレイヤーが再び参加しようとした場合にのみ、Photon追加の要求をします。 詳細は下記のPathCreate項目をご確認ください。

ベストプラクティス

各Webhookに必要な引数は常に確認してください。 必要な引数が不足の場合を想定して、人間が読解可能なエラーコードを戻すように設計してください。 Webhookのリターンオブジェクトの推奨フォーマットは{ "ResultCode" : x, "Message" : "xxx" }です。

戻り値を処理するおすすめの方法は、Webhookのバックエンドロジックにヘルパールーチンを実装することです。 以下に、Webhookのリターンオブジェクトの例をいくつか羅列します。

  • 成功した場合のデフォルトのリターンオブジェクト

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

  • Photon側またはWebサーバー上でのプロトコルレベルのエラー

    { "ResultCode" : 1, "Message" : "Missing Webhook Argument: <argument name>." }

  • アプリケーション固有のエラー

    { "ResultCode" : 2, "Message" : "Game with GameId=<gameId> already exists." }
    { "ResultCode" : 3, "Message" : "Could not load the State, Reason=<reason>." }

パスの詳細

PathCreate

このWebhookは、サーバーレベルでルームが作成されるたびにトリガーされます。 OpCreateRoomを使用してルームが作成されると、このWebhookはType引数をCreateに設定します。 ルーム作成時に使用されるほとんどのRoomOptionsTypedLobbyは、CreateOptionsとして送信されます。 ActorNrの値は1で、アクターはPathJoinWebhookを除くことなく、自動的にルームに参加します。

アクターが、以前作成されてPhoton Cloudから削除されたルームに参加、または再び参加しようとすると、TypeLoadに設定されます。 また、Webサーバーは同じルームのシリアル化されたStateを返します。 バックエンドのロジックは、以前に保存されシリアル化されたルームステートのバージョンを引き出す必要があります。

ステートが見つかった場合、Webサーバー側は{ "State" : state, "ResultCode" : 0 }のようなJSONオブジェクトを返すべきです。 何らかの理由でステートが見つからない場合、Webサービス側はCreateIfNotExistsの値を確認して、新しいステートでのルーム作成を許可または却下すべきです。 CreateIfNotExists がtrueの場合、空のルームステートを返し(たとえば{ "State" : "", "ResultCode" : 0 })、クライアント側のルームオプションの設定に従ってルームの作成を許可することができます。 値がfalseの場合には、Webサーバーがステートの読み込みに失敗したことを0以外のResultCodeで返し、Photon Cloudに通知するように設計してください。 人間が読解可能な、原因とエラーメッセージを追加するよう検討してください。

"IsPersistent"がtrueに設定され、また"PathCreate"と"PathClose"がともに設定されると、以下の場合ではルーム作成、非同期参加または再参加は失敗します:
  • "PathCreate"は到達できず、もしくはHTTPエラーを返した。
  • "PathCreate" は0以外のResultCodeを返した。
  • Photon Serverは受信したルームステートの分析または設定に失敗した。

AsyncJoinオプション

Photonアプリケーションは、ゲーム作成後に数時間経過してから招待を承認するなどの非同期オペレーションをサポートしているため、友達のプレイヤー同士が一緒にプレイしやすくなっています。 IsPersistentAsyncJoinがともに有効化されている場合、Photonサーバーメモリにルームが見つからないとルーム参加オペレーションはPathCreate (Type="Load") Webhookをトリガーします。 この仕様の目的は、そのルームが以前作成され保存されたことを想定して、Webサービスからルームステートをローディングしようとします。

IsPersistenttrueの場合、AsyncJoinはデフォルトで有効化されます。 AsyncJoinを非有効化するには、Webhook設定にない場合にキーを追加し、その値をfalseに設定します。

以下の表は、IsPersistentが有効化された場合にType="Load"をともなうPathCreate Webhookをトリガーするすべてのクライアントオペレーションを記載しています。

クライアントオペレーション JoinMode AsyncJoin = false AsyncJoin = true AsyncJoin = N/A
OpJoinRoom デフォルト (参加) x
OpRejoinRoom RejoinOnly
OpJoinOrCreateRoom CreateIfNotExists

特定の引数

PathCreate、Type "Create"

CreateOptions: ルームを作成する際に使用されるオプションです。このオプションには、使用されるTypedLobbyの詳細など、クライアントが設定するRoomOptionsクラスからの情報が含まれます。 全てのプロパティはStateにそのままコピーされるので、後でStateから取得することができます。

以下の表は、CreateOptionsRoomOptionsの比較を示しています。

プロパティまたはフィールド CreateOptions RoomOptions 備考
IsVisible x 後でルームのステートから取得可能。
IsOpen x 後でルームのステートから取得可能。
MaxPlayers
PlayerTtl
EmptyRoomTtl
CheckUserOnJoin プレイヤーごとに固有のIDがある場合、これをtrueに設定する必要があります。
SuppressRoomEvents trueに設定されている場合、参加と退室どちらの場合にもルームイベントは送信されません。 デフォルトはfalseで、送信されます。
DeleteCacheOnLeave これはRoomOptionsではCleanupCacheOnLeaveと呼ばれます。
LobbyType x ルームのロビーの種類で、ゲームクライアントによってTypedLobby.Typeで設定されます。 詳細はSDKのAPIドキュメントをご確認ください。
LobbyId x ルームのロビーの名前で、ゲームクライアントによってTypedLobby.Nameで設定されます。 詳細はSDKのAPIドキュメントをご確認ください。
CustomProperties x パブリックであるべき、ルームの初期カスタムプロパティのみが含まれています。すなわち、ロビーで表示されます。
CustomRoomProperties x ルームのすべての初期カスタムプロパティが含まれています。
CustomRoomPropertiesForLobby x パブリックであるべき、ルームのカスタムプロパティのキーが含まれています。すなわち、ロビーで表示されます。
PublishUserId x プレイヤーのUserIDが「パブリッシュされた」場合に定義します。
後でルームのステートから取得可能。
詳細は、こちらを参照してください。

PathCreate、Type "Load"

CreateIfNotExists: ルームのステートがWebサービスに見つからない場合に、新しいルームを作成する必要があるか表示するために使用されるフラグです。

CreateOptions以外にある、ルームのStateのプロパティ:

  • ActorCounter: 最後に参加したアクターのActorNr。
  • ActorList: ルーム内に存在する各アクター(アクティブまたは非アクティブ)に関する情報エントリーの配列。 各エントリーには以下のプロパティがあります:
    • ActorNr: ルーム内のアクターの番号。
    • UserId: アクターのUserID。
    • NickName: アクターのニックネーム。
    • IsActive: アクターがルームに参加したかどうかを示します。これは、PathCloseState引数では送信されません。
    • DeactivationTime: ルーム退出イベントのタイムスタンプ。 PathCloseStateでのみ送信されます。.
    • Binary*: Base64エンコーディングされたアクタープロパティ。
    • DEBUG_BINARY**: アクタープロパティの読み取り可能な形式。
  • Slice: キャッシュスライス・インデックス
  • Binary *: Base64エンコーディングされたルームプロパティとキャッシュイベント。
  • DebugInfo **: バイナリデータの読み取り可能な形式
    • DEBUG_PROPERTIES_18**: ルームプロパティの読み取り可能な形式。
    • DEBUG_EVENTS_19**: キャッシュされたイベントの読み取り可能な形式。
    • DEBUG_GROUPS_20**: インタレストグループの読み取り可能な形式。
  • ExpectedUsers: ルームに参加予定のプレイヤーのUserIDの配列。詳細はスロット予約を参照してください。

* : Photonが使用するプロトコルの特性により、Binaryプロパティが存在します。**: 本番環境のアプリケーションでは、Debugプロパティを非有効化する必要があります。これらのプロパティはデバッグのみに使用してください。

サンプルコール

{
    "ActorNr": 1,
    "AppVersion": "client-x.y.z",
    "AppId": "00000000-0000-0000-0000-000000000000",
    "CreateOptions": {
        "MaxPlayers": 4,
        "LobbyId": null,
        "LobbyType": 0,
        "CustomProperties": {
            "lobby3Key": "lobby3Val",
            "lobby4Key": "lobby4Val"
        },
        "EmptyRoomTTL": 0,
        "PlayerTTL": 2147483647,
        "CheckUserOnJoin": true,
        "DeleteCacheOnLeave": false,
        "SuppressRoomEvents": false
    },
    "GameId": "MyRoom",
    "Region": "EU",
    "Type": "Create",
    "UserId": "MyUserId1",
    "NickName": "MyPlayer1"
}

PathJoin

Photon Cloudから削除されていないルームにアクターが参加または再参加した場合に、このWebhookが送信されます。 Type引数はJoinに設定されます。

特定の引数

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

サンプルコール

{
    "ActorNr": 2,
    "AppVersion": "client-x.y.z",
    "AppId": "00000000-0000-0000-0000-000000000000",
    "GameId": "MyRoom",
    "Region": "EU",
    "Type": "Join",
    "UserId": "MyUserId0",
    "NickName": "MyPlayer0"
}

PathGameProperties

HttpForwardWebフラグが設定され、正しい負荷メソッドを使用している場合、ユーザーがルームまたはプレイヤーのカスタムプロパティを設定すると、毎回このWebhookがクライアント側から送信されます。

特定の引数

  • Properties:クライアントSDKから送信される、更新された一連のプロパティ。
  • State: ルームの完全なステートのシリアル化されたスナップショット。
  • OpSetCustomPropertiesを呼ぶ際にSendStateWebフラグが設定され、"IsPersistent"がtrueに設定されている場合にのみ送信されます。
  • AuthCookie:暗号化されたオブジェクトで、クライアントには見えません。カスタム認証が成功した際に、オプションで返されます。
  • OpSetCustomPropertiesを呼ぶ際に、SendAuthCookieWebフラグが設定されている場合にのみ送信されます。 PathGameProperties、Type "Actor"
  • TargetActor: プロパティがアップデートされたアクターの数。

サンプルコール

{
    "ActorNr": 1,
    "AppVersion": "client-x.y.z",
    "AppId": "00000000-0000-0000-0000-000000000000",
    "Properties": {
        "turn": 1,
        "lobby3Key": "test1a",
        "lobby4Key": "test1b"
    },
    "GameId": "MyRoom",
    "Region": "EU",
    "State": {
        "ActorCounter": 2,
        "ActorList": [
            {
                "ActorNr": 1,
                "UserId": "MyUserId1",
                "NickName": "MyPlayer1",
                "IsActive": true,
                "Binary": "RGIAAAEBRAAAAAJzAAlz...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer1",
                        "player_id": "12345"
                    }
                }
            },
            {
                "ActorNr": 2,
                "UserId": "MyUserId0",
                "NickName": "MyPlayer0",
                "IsActive": true,
                "Binary": "RGIAAEBRAAAAAFi/3M15...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer0"
                    }
                }
            }
        ],
        "Binary": {
            "18": "RAAAAAdzAAhwcm9wMUtl..."
        },
        "CheckUserOnJoin": true,
        "CustomProperties": {
            "lobby4Key": "test1b",
            "lobby3Key": "test1a"
        },
        "DeleteCacheOnLeave": false,
        "EmptyRoomTTL": 0,
        "IsOpen": true,
        "IsVisible": true,
        "LobbyType": 0,
        "LobbyProperties": [
            "lobby3Key",
            "lobby4Key"
        ],
        "MaxPlayers": 4,
        "PlayerTTL": 2147483647,
        "SuppressRoomEvents": false,
        "Slice": 0,
        "DebugInfo": {
            "DEBUG_PROPERTIES_18": {
                "250": [
                    "lobby3Key",
                    "lobby4Key"
                ],
                "prop1Key": "prop1Val",
                "prop2Key": "prop2Val",
                "lobby4Key": "test1b",
                "lobby3Key": "test1a",
                "map_name": "mymap",
                "turn": 1
            }
        }
    },
    "Type": "Game",
    "UserId": "MyUserId1",
    "NickName": "MyPlayer1"
}

PathEvent

HttpForwardWebフラグが設定され、正しい負荷メソッドを使用している場合、ユーザーがクライアント側からカスタムイベントを発生させると毎回送信されます。 カスタムイベントコードとイベントデータは、Webhookと送信されます。

特定の引数

  • EvCode: カスタムイベントコード
  • Data: クライアントSDKから送信されるカスタムイベントデータ
  • State: ルームの完全なステートのシリアル化されたスナップショット。
  • OpRaiseEventを呼ぶ際にSendStateWebフラグが設定され、"IsPersistent"がtrueに設定されている場合にのみ送信されます。
  • AuthCookie: 暗号化されたオブジェクトで、クライアントには見えません。カスタム認証が成功した際に、オプションで返されます。
  • OpRaiseEventを呼ぶ際に、SendAuthCookieWebフラグが設定されている場合にのみ送信されます。

サンプルコール

{
    "ActorNr": 3,
    "AppVersion": "client-x.y.z",
    "AppId": "00000000-0000-0000-0000-000000000000",
    "Data": "data",
    "GameId": "MyRoom",
    "Region": "EU",
    "State": {
        "ActorCounter": 3,
        "ActorList": [
            {
                "ActorNr": 1,
                "UserId": "MyUserId1",
                "NickName": "MyPlayer1",
                "Binary": "RGIAAAEBRAAAAAJzAAlw...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer1",
                        "player_id": "12345"
                    }
                }
            },
            {
                "ActorNr": 3,
                "UserId": "MyUserId0",
                "NickName": "MyPlayer0",
                "IsActive": true,
                "Binary": "RGIAAAEBRAAAAAFi/3MAC...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer0"
                    }
                }
            }
        ],
        "Binary": {
            "18": "RAAAAAdzAAhwcm9wMUtl...",
            "19": "RGl6AAEAAAAAAAN6AANp..."
        },
        "CheckUserOnJoin": true,
        "CustomProperties": {
            "lobby4Key": "test1b",
            "lobby3Key": "test1a"
        },
        "DeleteCacheOnLeave": false,
        "EmptyRoomTTL": 0,
        "IsOpen": true,
        "IsVisible": true,
        "LobbyType": 0,
        "LobbyProperties": [
            "lobby3Key",
            "lobby4Key"
        ],
        "MaxPlayers": 4,
        "PlayerTTL": 2147483647,
        "SuppressRoomEvents": false,
        "Slice": 0,
        "DebugInfo": {
            "DEBUG_PROPERTIES_18": {
                "250": [
                    "lobby3Key",
                    "lobby4Key"
                ],
                "prop1Key": "prop1Val",
                "prop2Key": "prop2Val",
                "lobby4Key": "test1b",
                "lobby3Key": "test1a",
                "map_name": "mymap",
                "turn": 1
            },
            "DEBUG_EVENTS_19": {
                "0": [
                    [
                        3,
                        0,
                        "data"
                    ],
                    [
                        3,
                        0,
                        "data"
                    ],
                    [
                        3,
                        0,
                        "data"
                    ]
                ]
            }
        }
    },
    "Type": "Event",
    "UserId": "MyUserId0",
    "NickName": "MyPlayer0",
    "EvCode": 0
}

PathLeave

このhookは、アクターがPhotonゲームサーバーから切断される度にトリガーされます。 切断にはいくつかの原因が考えられます。 このWebhookは、人間が読解可能な形式でType、そして理由のコードでReasonを表示します。

特定の引数

Type: 人間が読解可能な形式で理由を表示し、以下のいずれかの値となる可能性があります:

  • ClientDisconnect: クライアントがOpLeaveRoom()またはDisconnect()を呼んだことを示します。
  • ClientTimeoutDisconnect: クライアントがサーバーをタイムアウトしたことを示します。 UDP/ENETを使用している場合のみ有効です。
  • ManagedDisconnect: クライアントの処理速度が遅すぎて、データ送信を処理できないことを示します。
  • ServerDisconnect: データ破損が原因と考えられる低レベルのプロトコルエラーを示します。
  • TimeoutDisconnect: サーバーがクライアントをタイムアウトしたことを示します。詳細はクライアント接続処理ページまたは切断の分析に関するドキュメントを参照してください。

  • LeaveRequest: クライアントがOpLeaveRoom() OpLeaveRoom(false)を呼んで明確にルームを放棄したことを示します。

  • PlayerTtlTimedOut: 非アクティブユーザーがタイムアウトしたことを示し、そのアクターに対してルームのPlayerTtLが失効したことを意味します。

    詳細は、お使いのSDKのAPIドキュメントを参照してください。

  • PeerLastTouchTimedOut: アクターがPhoton Serverに5分間以上なにも送信しなかったという、非常に稀な状況を示します。 通常、ピアはそれより前にtimeoutしますが、Photonは接続しているすべてのピアの、サーバーとの直近の交信(LastTouchと呼びます)のタイムスタンプを5分ごとに確認します。
  • PluginRequest: アクターがActorListからプラグインによって削除されたことを示します。
  • PluginFailedJoin: Webhook実装によるPhoton Cloud内の内部エラーを示します。

IsInactive: ルームを退室する前のアクターのステートを示します。trueの場合、アクターはゲームに再参加できます。falseの場合には、アクターはActorListから削除され、今後そのゲームに再参加することはできません。

Reason: 理由のコード

以下の表では、それぞれのTypeとそのコードを記載し、どのようにWebhookが作成されるのか、またルーム内のプレイヤーがどのような影響を受けるかを説明します。

ルーム作成時にRoomOptions.PlayerTTLを0に設定した場合:

RoomOptions.PlayerTTL == 0であるルームのアクターは非アクティブな状態にはなれないので、退室するとすぐにActorListから削除されます。 設計上、ルームに少なくとも1人以上の非アクティブアクターがいる場合のみルームステートを保存する必要があるため、IsPersistentオプションは無視されます。

イベントがPathLeaveWebhookをトリガーすると、該当するアクターはルームから削除されますから、アクターがアクティブかどうか確認のためだけにはPathLeaveWebhookを使用しないでください。 しかもこの状態ではOpLeaveRoom(true)は使用できなくなり、PathLeavePlayerTtlTimedOutタイプも発生しません。

タイプ 理由 トリガー ActorListのアクター
ClientDisconnect 0 Disconnect() または OpLeaveRoom(true)へのコール false
ClientTimeoutDisconnect 1 Photon Serverからのコール false
ManagedDisconnect 2 Photon Serverからのコール false
ServerDisconnect 3 Photon Serverからのコール false
TimeoutDisconnect 4 Photon Serverからのコール false
LeaveRequest 101 OpLeaveRoom()またはOpLeaveRoom(false)へのコール false
PlayerTtlTimedOut 102 N/A N/A
PeerLastTouchTimedout 103 Photon Serverからのコール false
PluginRequest 104 プラグインからのコール false
PluginFailedJoin 105 Photon Serverからのコール false
ルーム作成時にRoomOptions.PlayerTTL != 0に設定した場合:
タイプ 理由 トリガー IsComingBackまたはIsInactive ActorListのアクター
ClientDisconnect 0 Disconnect()またはOpLeaveRoom(true)へのコール true true
ClientTimeoutDisconnect 1 Photon Serverからのコール true true
ManagedDisconnect 2 Photon Serverからのコール true true
ServerDisconnect 3 Photon Serverからのコール true true
TimeoutDisconnect 4 Photon Serverからのコール true true
LeaveRequest 101 OpLeaveRoom()またはOpLeaveRoom(false)へのコール false false
PlayerTtlTimedOut 102 Photon Serverからのコール false false
PeerLastTouchTimedout 103 Photon Serverからのコール false false
PluginRequest 104 プラグインからのコール false false
PluginFailedJoin 105 Photon Serverからのコール false false

サンプルコール

{
    "ActorNr": 1,
    "AppVersion": "client-x.y.z",
    "AppId": "00000000-0000-0000-0000-000000000000",
    "GameId": "MyRoom",
    "IsInactive": true,
    "Reason": "0",
    "Region": "EU",
    "Type": "ClientDisconnect",
    "UserId": "MyUserId1",
    "NickName": "MyPlayer1"
}

PathClose

このhookはPhoton Cloudのメモリからルームインスタンスを削除する直前に送信されます。 EmptyRoomTTLが期限切れの場合にのみ発生します。 ルーム作成時にEmptyRoomTTLが設定された数値により、ルームが空になってからタイマーが動作してカウントダウンし始めます。 最後のアクティブなアクターがルームを退室した際に、ルームは空になったと判断されます。

IsPersistenttrueに設定されると、Photon Cloudはルームのシリアル化されたスナップショットであるStateを送信します。これには ルームのプロパティのほか、アクターやキャッシュ済みイベントの情報が含まれます。 この場合、WebhookのTypeにはSave値が設定されます。

IsPersistentがデフォルトのステートであるfalseに設定された場合、TypeCloseとなりStateは送信されず、ルームは消滅します。

特定の引数

ActorCount: 非アクティブなアクターの数。0の場合、Typeは"Close"にする必要があります。

PathClose、Type"Save"

State: ルームの完全なステートのシリアル化されたスナップショット。

サンプルコール

{
    "ActorCount": 2,
    "AppVersion": "client-x.y.z",
    "AppId": "00000000-0000-0000-0000-000000000000",
    "GameId": "MyRoom",
    "Region": "EU",
    "State": {
        "ActorCounter": 3,
        "ActorList": [
            {
                "ActorNr": 1,
                "UserId": "MyUserId1",
                "NickName": "MyPlayer1",
                "Binary": "RGIAAAEBRAAAAAJzAAlw...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer1",
                        "player_id": "12345"
                    }
                }
            },
            {
                "ActorNr": 3,
                "UserId": "MyUserId0",
                "NickName": "MyPlayer0",
                "Binary": "RGIAAAEBRAAAAAFi/3MA...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer0"
                    }
                }
            }
        ],
        "Binary": {
            "18": "RAAAAAdzAAhwcm9wMUtl...",
            "19": "RGl6AAEAAAAAAAN6AANp..."
        },
        "CheckUserOnJoin": true,
        "CustomProperties": {
            "lobby4Key": "test1b",
            "lobby3Key": "test1a"
        },
        "DeleteCacheOnLeave": false,
        "EmptyRoomTTL": 0,
        "IsOpen": true,
        "IsVisible": true,
        "LobbyType": 0,
        "LobbyProperties": [
            "lobby3Key",
            "lobby4Key"
        ],
        "MaxPlayers": 4,
        "PlayerTTL": 2147483647,
        "SuppressRoomEvents": false,
        "Slice": 0,
        "DebugInfo": {
            "DEBUG_PROPERTIES_18": {
                "250": [
                    "lobby3Key",
                    "lobby4Key"
                ],
                "prop1Key": "prop1Val",
                "prop2Key": "prop2Val",
                "lobby4Key": "test1b",
                "lobby3Key": "test1a",
                "map_name": "mymap",
                "turn": 1
            },
            "DEBUG_EVENTS_19": {
                "0": [
                    [
                        3,
                        0,
                        "data"
                    ],
                    [
                        3,
                        0,
                        "data"
                    ],
                    [
                        3,
                        0,
                        "data"
                    ]
                ]
            }
        }
    },
    "Type": "Save"
}

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としてすべてのタグを渡します。

ルームステートの除去

ルームステートのサイズが懸念事項である場合には、サイズを縮小し、データを失わずに済む方法があります。 Webサービスでルームステートを保存する際、以下の方法でサイズを縮小できます:

1.ルームのローディング時にルームステートの再構築に使用されない、デバッグを目的に作成された読み取り専用のいくつかのフィールドを削除。 該当するフィールドは:CustomPropertiesDebugInfo、またActorList内の各アクターのすべてのDEBUG_BINARYNickName`です。 これらのフィールドは、ルームステートを非シリアル化する際に無視されるため、削除しても問題ありません。

以下は、PathCreateで返される完全なルームステートです、Type="Load"Webhook:

{
    "ResultCode": 0,
    "Message": "Room State successfully loaded",
    "State": {
        "ActorCounter": 3,
        "ActorList": [
            {
                "ActorNr": 1,
                "UserId": "MyUserId1",
                "NickName": "MyPlayer1",
                "Binary": "RGIAAAEBRAAAAAJzAAlw...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer1",
                        "player_id": "12345"
                    }
                }
            },
            {
                "ActorNr": 3,
                "UserId": "MyUserId0",
                "NickName": "MyPlayer0",
                "Binary": "RGIAAAEBRAAAAAFi/3MA...",
                "DEBUG_BINARY": {
                    "1": {
                        "255": "MyPlayer0"
                    }
                }
            }
        ],
        "Binary": {
            "18": "RAAAAAdzAAhwcm9wMUtl...",
            "19": "RGl6AAEAAAAAAAN6AANp..."
        },
        "CheckUserOnJoin": true,
        "CustomProperties": {
            "lobby4Key": "test1b",
            "lobby3Key": "test1a"
        },
        "DeleteCacheOnLeave": false,
        "EmptyRoomTTL": 0,
        "IsOpen": true,
        "IsVisible": true,
        "LobbyType": 0,
        "LobbyProperties": [
            "lobby3Key",
            "lobby4Key"
        ],
        "MaxPlayers": 4,
        "PlayerTTL": 2147483647,
        "SuppressRoomEvents": false,
        "Slice": 0,
        "DebugInfo": {
            "DEBUG_PROPERTIES_18": {
                "250": [
                    "lobby3Key",
                    "lobby4Key"
                ],
                "prop1Key": "prop1Val",
                "prop2Key": "prop2Val",
                "lobby4Key": "test1b",
                "lobby3Key": "test1a",
                "map_name": "mymap",
                "turn": 1
            },
            "DEBUG_EVENTS_19": {
                "0": [
                    [
                        3,
                        0,
                        "data"
                    ],
                    [
                        3,
                        0,
                        "data"
                    ],
                    [
                        3,
                        0,
                        "data"
                    ]
                ]
            }
        }
    }
}

以下は、同じWebhookで返されるルームステートの、除去されたバージョンです:

{
    "ResultCode": 0,
    "Message": "Room State successfully loaded",
    "State": {
        "ActorCounter": 3,
        "ActorList": [
            {
                "ActorNr": 1,
                "UserId": "MyUserId1",
                "Binary": "RGIAAAEBRAAAAAJzAAlw..."
            },
            {
                "ActorNr": 3,
                "UserId": "MyUserId0",
                "Binary": "RGIAAAEBRAAAAAFi/3MA..."
            }
        ],
        "Binary": {
            "18": "RAAAAAdzAAhwcm9wMUtl...",
            "19": "RGl6AAEAAAAAAAN6AANp..."
        },
        "CheckUserOnJoin": true,
        "DeleteCacheOnLeave": false,
        "EmptyRoomTTL": 0,
        "IsOpen": true,
        "IsVisible": true,
        "LobbyType": 0,
        "LobbyProperties": [
            "lobby3Key",
            "lobby4Key"
        ],
        "MaxPlayers": 4,
        "PlayerTTL": 2147483647,
        "SuppressRoomEvents": false,
        "Slice": 0
    }
}

2.アプリケーションロジックで固定値とみなされ、ルームのライフタイムを通じて変更の必要がない、またはルームのローディング時にPhoton Serverにステートを返す前にコードで再設定できるいくつかのフィールドを除去。 これらのフィールドは、Photonサーバーにステートを返す前に当初の値を追加しなければなりません。当初の値を追加しないと、ステートが破損する可能性があります。

該当するフィールドは以下のとおりです:

  • ActorCounter
  • CheckUserOnJoin
  • DeleteCacheOnLeave
  • EmptyRoomTTL
  • IsOpen
  • IsVisible
  • MaxPlayers
  • LobbyId
  • LobbyType
  • LobbyProperties
  • PlayerTTL
  • SuppressRoomEvents
  • Slice

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