This document is about: FUSION 2

SWITCH TO

FUSION 2-SHARED FUSION 1 FUSION 2

Webhooks

概述

Webhooks主要用於擁有受信任的遊戲配置和房間組成來源，並可大幅提升線上應用程式的安全性。

預設的雲端外掛程式支援透過AppID儀表板定義的不同鉤子。
一旦設定並啟用後，Photon Cloud會向自訂後端發送WebRequests（HTTP POST），並會使用回應資料（Json）對Photon房間和遊戲階段進行各種配置。

安裝

在Photon儀錶板上，每個AppId都啟用了Webhooks。

導航到Photon儀錶板並登入。
找到AppId並按一下Manage。
向下滾動到挿件，然後按一下Edit。
按一下Add New Pair並添加keys和values（每個設定值允許的最大長度為1024個字元）。
按Save，等待更改生效最多一分鐘。

儀錶板配置

鍵	類型	示例	描述
WebHookBaseUrl	`string`	`https://localhost:3581`	自定義後端的基本url。將附加Webhook路徑，導致路徑格式為：`{WebHookBaseUrl}/game/create` 必須始終設定。
WebHookIntegration	`string`	`Default`	所選的webhook集成（預設值為`Default`）。 `Default`, `PlayFab`
WebHookSecret	`string`	`**********`	這將與每個web請求一起發送，可用於對請求進行身份驗證。將設定名為`X-SecretKey`的標頭。
WebHookCustomHttpHeaders	`Dictionary <string, string>`	`{"A": "Foo", "B": "100" }`	`JSON`字典。所有條目都將添加到自定義web請求標頭中。確保使用雙引號。
WebHookEnableOnCreate	`bool`	`true`	如果設定為`true`，則當用戶端創建遊戲會話時，將觸發CreateGame webhook。
WebHookEnableOnClose	`bool`	`false`	如果設定為`true`，則當遊戲會話關閉時，將觸發CloseGame webhook。
WebHookEnableOnJoin	`bool`	`true`	如果設定為`true`，則當任何用戶端嘗試加入遊戲會話時，將觸發JoinGame webhook。
WebHookEnableOnLeave	`bool`	`false`	如果設定為`true`，則當任何用戶端離開遊戲會話時，將觸發LeaveGame webhook
WebHookUrl{KEY}	`string`	`https://foo.net/path`	此模式是可選的，可用於覆蓋基於單個Webhook的`WebHookBaseUrl`的默認路徑。`{KEY}`的有效替代品是`OnCreate`, `OnJoin`, `OnLeave`等。
WebHookBaseUrlAllowList	`Dictionary<string, string>`	`{ "one": "https://foo-one", "two": "https://foo-two" }`	基本url允許清單，用戶端可以通過將金鑰添加為房間内容“QuantumWebHookBaseUrl”來選擇金鑰。 `MatchmakingArguments.CustomProperties = new PhotonHashtable() { { RoomProperties.WebHookBaseUrl, "two" } }` 如果用戶端發送的金鑰與允許清單中的條目匹配，它將替換會話中所有Webhook的`WebHookBaseUrl`。如果找不到金鑰，則會記錄一條警告，並使用`WebHookBaseUrl`。
WebHookDefaultTimeout	`int`	`60`	覆蓋Photon Server應用於webhooks的默認超時（以秒為組織）（30秒）。

Webhook API

Webhooks傳送Json內容且只接受Json內容作為回應。Json使用UTF-8字元集是強制性的。

Webhooks期望HTTP回應代碼為200或400：

200: 請求成功。
400: 錯誤或操作已被拒絕（例如，客戶端不能建立房間/遊戲會話）。

Photon伺服器在傳輸錯誤後會重試三次網鉤（webhook），同樣在收到狀態碼 503（服務不可用）後，也會分別延遲400毫秒、1600毫秒和6400毫秒進行重試。請求失敗且不再重試前的超時時間為10秒。

填寫WebhookError定義，以將錯誤性質的資訊回傳至Photon外掛程式。其可用於：

日誌記錄；
將資訊回傳給客戶；
一個自訂外掛程式，用以新增進一步的自訂錯誤處理；

Http請求重試

Photon Server會對來自後端的可重試錯誤回應作出反應，額外重新發送請求三次。

後續的請求有不同的標頭以識別它們。

EGRepeatId - 重複的數字，例如 0、1、2 或 3 (int)
EGInvokeId - 請求識別碼 (int)

常見的請求頭

這些常見的請求頭被添加到每個web請求中。

名稱	類型	內容	描述
接受	`string`	`application/json`	Webhooks只接受`JSON`作為響應體
接受字元集	`string`	`utf-8`	Webhooks只接受utf-8作為響應體字元集
內容類型	`string`	`application/json`	Webhooks都發送`JSON`正文數據
X-SecretKey	`string`	`**********`	此金鑰只應為自定義後端所知，並應用於對傳入的web請求進行身份驗證。這在Photon儀錶板上設定為`WebHookSecret`。
X-Origin	`string`	`Photon`	將始終設定為“Photon”

CreateGame

在Photon服務器上創建房間/遊戲會話之前，會調用此webhook。在webhook收到響應之前，創建將被封鎖，這將影響用戶端創建連接所需的時間。

CreateGame webhook始終是發起房間/遊戲會話創建的用戶的JoinGame請求。此用戶將沒有後續的JoinGame webhook。此webhook共享來自JoinGame webhook的數據。

需要在Photon儀錶板上設定WebHookBaseUrl及WebHookEnableCreateGame。

JavaScript

POST https://{WebHookBaseUrl}/game/create

CreateGame請求

名稱	類型	示例	描述
AppId	`string`	`d1f67eec-51fb-45c1`	Photon AppId。
AppVersion	`string`	`1.0-live`	創建房間/遊戲會話時使用的AppVersion。
地區	`string`	`eu`	創建房間/遊戲會話的遊戲服務器的地區碼。
Cloud	`string`	`1`	運行遊戲服務器的`Cloud Id`。
UserId	`string`	`db757806-8570-45aa`	創建房間/遊戲會話的用戶端的`UserId`。
AuthCookie	`Dictionary<string, object>`	`db757806-8570-45aa`	後端設定的Photon自定義身份驗證cookie。
RoomName	`string`	`e472a861-a1e2-49f7`	房間/遊戲會話名稱。
GameId	`string`	`0:eu:e472a861-a1e2-49f7`	一個唯一的`GameId`，由`{Cloud:}{Region:}RoomName`組成。可以在響應中覆蓋。
EnterRoomParams	`EnterRoomParams`	JSON：請參閱`EnterRoomParam`部分	用戶端發送的Photon房間/遊戲會話選項。

Json範例：

JSON

{
  "AppId": "d1f67eec-51fb-45c1",
  "AppVersion": "1.0-live",
  "Region": "eu",
  "Cloud": "1",
  "UserId": "db757806-8570-45aa",
  "AuthCookie": {
    "Secret": "**********"
  }
  "RoomName": "e472a861-a1e2-49f7",
  "GameId": "0:eu:e472a861-a1e2-49f7",
  "EnterRoomParams": {
    "RoomOptions": {
      "IsVisible": true,
      "IsOpen": true
    }
  }
}

HTTP回應碼

名稱	類型	描述
200 OK	`CreateGame Response`	房間/遊戲會話創建可以開始，響應中的配置數據將覆蓋用戶端發送的數據。
400 Bad Request	`WebhookError`	不允許創建房間/遊戲會話，將被取消。用戶端將收到一個錯誤。

CreateGame回應

名稱	類型	描述
GameId	`string`	覆蓋後續web請求中使用的`GameId`。可以是`null`或省略。
EnterRoomParams	`EnterRoomParams`	在創建時強制執行選定的“房間選項”。`JSON`對象不必包含所有成員，只需包含應被覆蓋的成員。發送`EnterRoomParams`僅保護初始選項。其中大多數可以通過用戶端發送Photon Room内容進行更改。要封鎖此操作，請啟用Photon儀錶板内容`BlockRoomProperties`。可以是`null`或省略。

Json示例：

JSON

{
  "GameId": "0:eu:db757806-8570-45aa",
  "EnterRoomParams": {
    "RoomOptions": {
      "CustomRoomProperties": {
        "GameType": "CUSTOM_GAME_TYPE",
        "CustomData": 101
      }
    }
  }
}

JoinGame

在用戶端加入現有的房間/遊戲會話之前，會發送JoinGame webhook。返回200表示允許加入，返回400表示取消加入。

需要在Photon AppId儀錶板上設定WebHookBaseUrl和WebHookEnableOnJoin。

JavaScript

POST https://{WebHookBaseUrl}/game/join

JoinGame請求

名稱	類型	示例	描述
AppId	`string`	`d1f67eec-51fb-45c1`	Photon AppId
GameId	`string`	`0:eu:db757806-8570-45aa`	唯一`GameId`
UserId	`string`	`db757806-8570-45aa`	Photon `UserId`
AuthCookie	`Dictionary<string, object>`	`db757806-8570-45aa`	後端設定的Photon自定義身份驗證cookie。

Json範例：

JSON

{
  "AppId": "*******************",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa",
  "AuthCookie": {
    "Secret": "**********"
  }
}

HTTP回應碼

名稱	類型	描述
200 OK	`JoinGame回應`	客戶將加入房間。
400 Bad Request	`WebhookError`	加入房間將失敗。

JoinGame回應

Json示例：

JSON

{
  // empty
}

LeaveGame

LeaveGame webhook是在用戶端離開現有的房間/遊戲會話後發送的。

需要在Photon AppId儀錶板上設定WebHookBaseUrl及WebHookEnableOnLeave。

JavaScript

POST https://{WebHookBaseUrl}/game/leave

LeaveGame請求

名稱	類型	示例	描述
AppId	`string`	`d1f67eec-51fb-45c1`	Photon AppId
GameId	`string`	`0:eu:db757806-8570-45aa`	唯一`GameId`
UserId	`string`	`db757806-8570-45aa`	Photon `UserId`
ActorNr	`int`	`db757806-8570-45aa`	Photon角色編號，用戶端的遞增運行階段id。
AuthCookie	`Dictionary<string, object>`	`db757806-8570-45aa`	Photon `UserId`
IsInactive	`bool`	`false`	當離開房間的玩家仍被標記為非活動狀態時，例如當設定了`PlayerTTL`時，`true`。在這種情況下，可以提出其他LeaveGame請求。
FailedOnCreate	`bool`	`false`	此標誌表示此離開遊戲webhook是為創建房間失敗的用戶端調用的。

Json範例：

JSON

{
  "AppId": "*******************",
  "GameId": "0:eu:db757806-8570-45aa",
  "UserId": "db757806-8570-45aa",
  "ActorNr": 1,
  "AuthCookie": {
    "Secret": "**********"
  },
  "IsInactive": false,
  "FailedOnCreate": false
}

HTTP回應碼

名稱	類型	描述
200 OK	`LeaveGame Response`	只是確認收到。
400 Bad Request	`WebhookError`	錯誤被忽略，它將被記錄在Photon Cloud上。

LeaveGame回應

Json範例：

JSON

{
}

CloseGame

當所有用戶端離開後，房間/遊戲會話關閉時，會發送CloseGame webhook。

需要在Photon儀錶板上設定WebHookBaseUrl及WebHookEnableOnClose。

JavaScript

POST https://{WebHookBaseUrl}/game/close

CloseGame請求

名稱	類型	示例	描述
AppId	`string`	`d1f67eec-51fb-45c1`	Photon AppId
GameId	`string`	`0:eu:db757806-8570-45aa`	唯一遊戲id
CloseReason	`int (CloseReason`)	`0`	本會議室/環節關閉的原因。

Json範例：

JSON

{
  "GameId": "0:eu:db757806-8570-45aa",
  "CloseReason": 0
}

HTTP回應碼

名稱	類型	描述
200 OK		確認收到。

CloseReason

名稱	值	描述
Ok	`0`	會話已關閉，沒有錯誤。
FailedOnCreate	`1`	會話已關閉，因為創建失敗。

名稱	值	描述
`ExceptionOnUpdateLoop`	`101`	外掛程式伺服器更新迴圈上發生任何異常，導致遊戲階段關閉。
`ExceptionOnHostMigration`	`102`	在外掛程式側執行主機遷移時出現任何異常。
`ServerHasDisconnected`	`103`	Fusion伺服器已斷開與遊戲階段的連接，必須斷開所有客戶端的連接。
`FailedToSetupServer`	`104`	執行外掛程式伺服器設定時出現任何異常，導致遊戲階段關閉。
`FailedToParseNetworkProjectConfig`	`105`	未能解析Fusion的`NetworkProjectConfig`。

EnterRoomParams

此定義旨在類似於Photon Realtime中的EnterRoomParams類。它包括所有可以通過CreateGame webhook設定的選項。在編寫JsonResponse時，每個成員都是可選的，可以為null或不設定。

名稱	類型	描述
RoomOptions	`RoomOptions`	RoomOptions物件
ExpectedUsers	`string[]`	允許進入房間/會話的`UserIds`清單（除創建房間的用戶外）。如果`MaxPlayers`大於列出的 `ExpectedUsers`數量，則任何玩家都可以加入並填補未保留的插槽。僅適用於`RoomJoin()`，不適用於`JoinRandom()`。

Json範例：

JSON

{
  "RoomOptions": {
    "IsVisible": true,
    "IsOpen": true,
    "MaxPlayers": 8,
    "PlayerTtl": null,
    "EmptyRoomTtl": 10000,
    "CustomRoomProperties": {
      "Foo": "bar",
      "PlayerClass": 1
    },
    "CustomRoomPropertiesForLobby": [
      "Foo"
    ],
    "SuppressRoomEvents": null,
    "SuppressPlayerInfo": null,
    "PublishUserId": null,
    "DeleteNullProperties": null,
    "BroadcastPropsChangeToAll": null,
    "CleanupCacheOnLeave": null,
    "CheckUserOnJoin": null
  },
  "ExpectedUsers": [
    "A",
    "B",
    "C"
  ]
}

訣竅

Fusion僅支援覆蓋遊戲階段的RoomOptions.CustomRoomProperties。如果返回到Photon Cloud，則忽略所有其他欄位。

RoomOptions

所有值都是可以為null的類型，可以設定為null，也可以在發送回Quantum服務器時省略，在這種情況下，此響應不會改變為null或省略的房間内容，並將保持預設值或用戶端在創建房間時發送的值。

名稱	類型	描述
IsVisible	`bool`	定義此房間是否列在Photon匹配中。
IsOpen	`bool`	定義此房間是否可以由其他用戶端加入。
MaxPlayers	`byte`	任何時候可以在房間裏的最大玩家數量。 0表示“無限制”。
PlayerTtl	`int`	房間裏“演員”的生存時間（TTL）。如果用戶端斷開連接，此參與者將首先處於非活動狀態，並在此超時後被删除。以毫秒為單位。
EmptyRoomTtl	`int`	最後一名玩家離開時房間的生存時間（TTL）。在記憶體中保留空間，以防玩家很快重新加入。以毫秒為單位。
CustomRoomProperties	`Dictionary <string, object>`	在創建過程中設定房間的自訂屬性。
CustomRoomPropertiesForLobby	`string[]`	定義哪些自定義房間内容將在大廳中列出。内容的值類型必須是`bool`, `byte`, `short`, `int`, `long`或`string`。内容的最大數量為3。字串值的最大長度為64。鍵限制也可以通過Photon儀錶板内容強制執行：`AllowedLobbyProperties`。
SuppressRoomEvents	`bool`	告訴服務器跳過加入和離開玩家的房間事件。預設值為`false`。
SuppressPlayerInfo	`bool`	禁用事件加入和離開服務器以及房間中的内容廣播（以儘量減少流量）。預設值為`false`。
PublishUserId	`bool`	定義玩家的用戶ID是否在房間中“發佈”。如果玩家想一起玩另一個遊戲，對FindFriends很有用。預設值為`false`。
DeleteNullProperties	`bool`	可選地，當null被賦值時，内容會被删除。預設值為 `false`。

名稱	類型	描述
`CleanupCacheOnLeave`	`布林值`	當用戶離開時，從房間中移除用戶的事件和屬性。應始終為`真`。
`CheckUserOnJoin`	`布林值`	預設下，屬性更改會被發送回設定它們的客戶端，以避免在同時設定屬性時不同步。應始終為`真`。

WebhookError

名稱	類型	描述
Status	`int`	HTTP狀態碼
Error	`string`	錯誤名稱
Message	`string`	錯誤訊息

Json範例：

JSON

{
  "Status": 400,
  "Error": "PlayerNotAllowed",
  "Message": "LoremIpsum"
}

PlayFab

要啟用PlayFab整合，請新增WebHookIntegration儀表板變數並將其設定為PlayFab。

所有路徑中的斜線都將被替換為下劃線：game/create => game_create
所有webhook請求將自動新增AppId屬性（若缺失），由WebHooksConfig.AppId控制
所有 webhook 請求皆會自動新增 UserId 屬性（若缺失）為 "0"
Webhook回應將處理以下Json結果主體，並導致webhooks失敗於ResultCode != 0。發生錯誤時，Message會被複製到WebHookError.Message。

JSON

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

Photon Cloud Web請求限制

默認情況下，Photon Server按順序管理HTTP請求，並且在當前請求完成之前不會啟動新請求。新請求已排隊。此限制為每間房都有。

這可能會導致用戶端在使用OnJoin或AddPlayer webhooks時出現意外的等待時間，同時玩家湧入率很高，從Photon雲到自定義後端的往返時間也很長。

可以為企業雲啟用並行請求。我們正在研究一種解決方案，讓他們也選擇使用公共應用程式。

其他限制包括：

HttpRequestTimeout: 30000
LimitHttpResponseMaxSize: 200000
MaxQueuedRequests: 5000

概述
安裝

儀錶板配置

Webhook API

Http請求重試
常見的請求頭
CreateGame
JoinGame
LeaveGame
CloseGame
EnterRoomParams
RoomOptions
WebhookError

PlayFab
Photon Cloud Web請求限制