This document is about: FUSION 2

SWITCH TO

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`	`字串`	`https://localhost:3581`	自訂後端的基本url。將附加Webhook路徑，例如：`{WebHookBaseUrl}/game/create` 必須始終設定。
`WebHookIntegration`	`字串`	`Default`	所選的webhook整合（預設值為`Default`）。 `Default`, `PlayFab`
`WebHookSecret`	`字串`	`**********`	這將與每個web請求一起發送，可用於對請求進行身份驗證。將設定名為“X-SecretKey”的標頭。
`WebHookCustomHttpHeaders`	`字典 <字串, 字串>`	`{"A": "Foo", "B": "100" }`	一個`JSON`字典。所有條目都將新增到自訂web請求標頭中。請確保使用雙引號。
`WebHookEnableOnCreate`	`布林值`	`真`	如果設定為`真`，則當客戶端創建遊戲階段時，將觸發CreateGame webhook。
`WebHookEnableOnClose`	`布林值`	`偽`	如果設定為`true`，則當遊戲階段關閉時，將觸發CloseGame webhook。
`WebHookEnableOnJoin`	`布林值`	`真`	如果設定為`真`，則當任何客戶端嘗試加入遊戲會話時，將觸發JoinGame webhook。
`WebHookEnableOnLeave`	`布林值`	`偽`	如果設定為`真`，則當任何客戶端離開遊戲階段時，將觸發LeaveGame webhook

Webhook API

Webhooks發送Json內容，只接受Json內容作為響應。Json的UTF-8字元集是必需的。

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

200：成功請求。
400：錯誤或操作被拒絕（例如，客戶端無法創建房間/遊戲階段）。

Photon伺服器在傳輸錯誤三次後以及在收到延遲為400ms、1600ms和6400ms的StatusCode 503（服務不可用）後重試Webhook。請求失敗且不重試之前的超時為10秒。

填寫WebhookError定義，將錯誤性質的資訊返回給Photon外掛程式。它可用於：

登錄；
向客戶端返回資訊；
一個自訂外掛程式，用於新增進一步的自訂錯誤處理；

Http請求重試

Photon伺服器透過再次發送請求三次，以對來自後端的可重試錯誤響應做出反應。

後續請求具有不同的標頭來標識它們。

EGRepeatId - 重複的數字，例如0、1、2或3（整數）
EGInvokeId - 請求id（整數）

常見請求標頭

這些常見的請求標頭新增到每個 web請求中。

名稱	類型	內容	描述
`Accept`	`字串`	`application/json`	Webhooks只接受`JSON`作為響應主體
`Accept-Charset`	`字串`	`utf-8`	Webhooks只接受utf-8作為響應主體字元集
`Content-Type`	`字串`	`application/json`	Webhooks全發送`JSON`主體資料
`X-SecretKey`	`字串`	`**********`	此鍵只應為自訂後端所知，並應該用於對傳入的web請求進行身份驗證。這在Photon儀表板上設定為`WebHookSecret`。
`X-Origin`	`字串`	`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`	`字串`	`d1f67eec-51fb-45c1`	Photon AppId。
`AppVersion`	`字串`	`1.0-live`	創建房間/遊戲階段時使用的AppVersion。
`Region`	`字串`	`eu`	創建房間/遊戲階段的遊戲伺服器的區域代碼。
`Cloud`	`字串`	`1`	運行遊戲伺服器的`Cloud Id`。
`UserId`	`字串`	`db757806-8570-45aa`	創建房間/遊戲階段的客戶端的`UserId`。
`AuthCookie`	`字典<字串, 物件>`	`db757806-8570-45aa`	後端設定的Photon自訂身份驗證cookie。
`RoomName`	`字串`	`e472a861-a1e2-49f7`	房間/遊戲階段名稱。
`GameId`	`字串`	`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可以`	`CreateGame響應`	房間/遊戲會話創建可以開始，響應中的設置資料將覆寫客戶端發送的資料。
`400錯誤請求`	`WebhookError`	不允許創建房間/遊戲階段，也將被取消。客戶端將收到一個錯誤。

CreateGame響應

名稱	類型	描述
`GameId`	`字串`	覆寫後續web請求中使用的`GameId`。可以是`空`或省略。
`EnterRoomParams`	`EnterRoomParams`	在創建時強制執行選定的房間選項。`JSON`物件不必包含所有成員，只需包含應被覆寫的成員。發送`EnterRoomParams`僅保護初始選項。其中大多數可以透過客戶端發送Photon Room屬性進行更改。要封鎖此操作，請啟用Photon儀表板屬性`BlockRoomProperties`。可以是`空`或省略。

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`	`字串`	`d1f67eec-51fb-45c1`	Photon AppId
`GameId`	`字串`	`0:eu:db757806-8570-45aa`	唯一的`GameId`
`UserId`	`字串`	`db757806-8570-45aa`	Photon `UserId`
`AuthCookie`	`字典<字串, 物件>`	`db757806-8570-45aa`	後端設定的Photon自訂身份驗證cookie。

Json示例：

JSON

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

HTTP響應代碼

名稱	類型	描述
`200可以`	`JoinGame響應`	客戶端將加入房間。
`400錯誤請求`	`WebhookError`	加入房間將失敗。

JoinGame響應

Json示例：

JSON

{
  // empty
}

LeaveGame

LeaveGame webhook是在客戶端離開現有的房間/遊戲階段後發送的。

需要在Photon AppId儀表板上設定WebHookBaseUrl和WebHookEnableOnLeave。

JavaScript

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

LeaveGame請求

名稱	類型	示例	描述
`AppId`	`字串`	`d1f67eec-51fb-45c1`	Photon AppId
`GameId`	`字串`	`0:eu:db757806-8570-45aa`	唯一的`GameId`
`UserId`	`字串`	`db757806-8570-45aa`	Photon `UserId`
`ActorNr`	`整數`	`db757806-8570-45aa`	Photon演員號碼，客戶端的遞增運行階段id。
`AuthCookie`	`字典<字串, 物件>`	`db757806-8570-45aa`	Photon `UserId`
`IsInactive`	`布林值`	`db757806-8570-45aa`	當玩家離開房間但仍被標記為非活躍中時，例如當玩家TTL被設定時，設定為真。在這種情況下，可以提出其他LeaveGame請求。

Json示例：

JSON

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

HTTP響應代碼

名稱	類型	描述
`200可以`	`LeaveGame響應`	只是確認收到。
`400錯誤請求`	`WebhookError`	錯誤被忽略，它將被記錄在Photon Cloud上。

LeaveGame響應

Json示例：

JSON

{
  // empty
}

CloseGame

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

需要在Photon儀表板上設定WebHookBaseUrl和WebHookEnableOnClose。

JavaScript

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

CloseGame請求

名稱	類型	示例	描述
`AppId`	`字串`	`d1f67eec-51fb-45c1`	Photon AppId
`GameId`	`字串`	`0:eu:db757806-8570-45aa`	唯一的遊戲id
`CloseReason`	`整數(CloseReason`)	`0`	本房間/遊戲階段關閉的原因。

Json示例：

JSON

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

HTTP響應代碼

名稱	類型	描述
`200可以`		確認收到。

CloseReason

名稱	值	描述
`可以`	`0`	遊戲階段已關閉，沒有錯誤。
`FailedOnCreate`	`1`	遊戲階段已關閉，因為創建失敗。

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

EnterRoomParams

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

名稱	類型	描述
`RoomOptions`	`RoomOptions`	RoomOptions物件
`ExpectedUsers`	`字串[]`	允許進入房間/遊戲階段的`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，也可以在發送回Quantum伺服器時省略，在這種情況下，此響應不會改變為已空值或省略的房間屬性，並將保持預設值或客戶端在創建房間時發送的值。

名稱	類型	描述
`IsVisible`	`布林值`	定義此房間是否列在Photon對戰配對中。
`IsOpen`	`布林值`	定義此房間是否可以由其他客戶端加入。
`MaxPlayers`	`位元組`	任何時候可以在房間裡的最大玩家數量。0表示「無限制」。
`PlayerTtl`	`整數`	房間裡「演員」的生存時間（TTL）。如果客戶端斷開連接，此演員將首先處於非活動狀態，並在此超時後被移除。以毫秒為單位。
`EmptyRoomTtl`	`整數`	最後一名玩家離開時房間的生存時間（TTL）。在記憶體中保留房間，以防玩家很快重新加入。以毫秒為單位。
`CustomRoomProperties`	`字典 <字串, 物件>`	在創建過程中設定房間的自訂屬性。
`CustomRoomPropertiesForLobby`	`字串[]`	定義哪些自訂房間屬性將在大廳中列出。屬性的值類型必須是`布林值`、`位元組`、`short`、`整數`、`long`或`字串`。屬性的最大數量為3。字串值的最大長度為64。還可以透過Photon儀表板屬性執行關鍵限制： `AllowedLobbyProperties`。
`SuppressRoomEvents`	`布林值`	告訴伺服器跳過加入和離開玩家的房間事件。預設為`偽`。
`SuppressPlayerInfo`	`布林值`	禁用事件加入和離開伺服器以及房間中的屬性廣播（以儘量減少流量）。預設為`偽`。
`PublishUserId`	`布林值`	定義玩家的UserId是否在房間中「發佈」。如果玩家想一起玩另一個遊戲，對FindFriends很有用。預設為`偽`。
`DeleteNullProperties`	`布林值`	可選地，當空值被賦值時，屬性會被移除。預設是`偽`。

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

WebhookError

名稱	類型	描述
`Status`	`整數`	HTTP狀態代碼
`Error`	`字串`	錯誤名稱
`Message`	`字串`	錯誤訊息

Json示例：

JSON

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

Photon Cloud網路請求限制

每個房間/遊戲階段的Photon伺服器都有全域限制。如果它們受到網路請求的擊中，響應可能會被丟棄。

HttpRequestTimeout：30000
LimitHttpResponseMaxSize：200000
MaxQueuedRequests：5000

概述
設定

儀表板設置

Webhook API

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

Photon Cloud網路請求限制