채팅 Webhook

Photon Cloud에서 webhook를 사용하여 채팅 어플리케이션을 더 많이 제어할 수 있습니다. 채널 이력 저장, 메시지 필터, 채널 생성 취소와 특정 플레이어가 채팅 룸을 구독하는 것도 금지 할 수 있습니다.

Photon 채팅 webhook는 Photon Cloud가 특정 URL로 전송하는 이벤트-기반의 HTTP POST 요청입니다. 개별 Photon 채팅 webhook는 소유자 트리거, 데이터와 목적지 경로에 의해 정의됩니다.

Contents

설정

기본 설정

  • BaseUrl (필수)
    호크 서비스 호스팅을 위한 URL입니다. 슬래시로 끝나면 안됩니다. 구성된 후크의 상대 경로 URI에서 콜백이 수신됩니다.
  • CustomHttpHeaders
    구성된 웹 서비스에 대한 요청에서 HTTP 헤더로 설정되어야하는 키/값의 쌍으로 이루어진 JSON 객체입니다.

Back To Top

Paths

호스트에서 식별되는 URI에서 이벤트를 수신하도록 각 경로를 구성합니다. 빈 경로는 히트되지 않으며 해당 Webhook에서 콜백을 수신 받지 않습니다.

  • PathChannelCreate
    신규 채널이 생성되거나 채널의 상태가 외부 서비스로부터 로드될 필요가 있을 때 호출됩니다.
  • PathChannelDestroy
    채널이 Photon 서버 메모리상에서 제거되었을 때 호출됩니다. IsPersistent가 true로 설정되어 있는 경우에는 채널 상태가 전송됩니다.
  • PathChannelSubscribe
    플레이어가 이미 생성되어 있는 채널을 구독할 때 호출 됩니다.
  • PathChannelUnsubscribe
    플레이어가 채널을 구독을 해지할 때 호출 됩니다.
  • PathPublishMessage
    클라이언트가 채널에 메시지를 게시했을 때 호출 됩니다.

Back To Top

옵션

이러한 옵션을 통해 채팅 webhook 동작을 조정하세요. 옵션은 설정되지 않았거나 값이 없는 경우 구성되지 않은 것으로 간주됩니다.

  • FailIfUnavailable
    true로 설정하면 채널 생성, 구독과 메시지 게시 오퍼레이션은 상응하는 후크의 구성된 엔드포인트를 사용 할 수 없을 때 실패할 것 입니다. 엔드 포인트는 HTTP 요청 처리동안에 오류가 발생하거나 HTTP 응답이 성공하지 않았을 때 사용할 수 없는 것으로 간주됩니다. 기본값은 false 입니다.

  • IsPersistent
    true 로 설정하면, Photon Cloud는 채널을 없애기전 채널 상태를 전송합니다. 이 옵션은 PathChannelCreatePathChannelDestory 두개 모두 올바르게 구성되어 있고 MaxChannelHistory 가 0보다 큰 경우에만 유효합니다. 자세한 내용은 ChannelCreateChannelDestroy webhook의 내용을 참조하시기 바랍니다. 기본값은 false 입니다.

  • MaxChannelHistory MaxChannelHistory는 채널당 지속될 최대 메시지수 입니다. 1에서 100 사이의 값입니다. 기본값은 100 입니다.

  • HasErrorInfo HasErrorInfo true 로 설정되어 있는 경우 채팅 클라이언트들은 후크 엔드포인트를 사용 할 수 없을 때 오류 메시지와 같이 알림을 받게되지만, FailIfUnavailablefalse 로 설정됩니다. 기본값은 false 입니다.

  • SkipPostCreationFailure SkipPostCreationFailure 이 true 로 설정되어 있는 경우, PathUnsubscribePathChannelDestory webhook 는 채널 생성 실패 이후 전송되지 않을 것 입니다. 기본값은 false 입니다.

Back To Top

공통 기준

모든 Webhook에 대한 공통 인수

AppId: 관리화면에서 찾을 수 있는 게임 클라이언트에서 설정된 어플리케이션의 AppId.

AppVersion: 게임 클라이언트에서 설정된 어플리케이션의 버전.

Region: 게임 클라이언트가 연결된 지역과 해당 룸이 속한 지역.

ChannelName: 후크가 트리거되는 채널의 이름.

Back To Top

ChannelDestroy를 제외한 모든 Webhook에 대한 공통 인수

UserId: 후크를 트리거하는 플레이어의 UserID.

Back To Top

ChannelCreate를 제외한 모든 Webhook에 대한 공통 인수

HistoryCount: 채널 이력내에 있는 현재의 메시지 개수.

Back To Top

인수 목록

이 테이블은 각 webhook에서 사용 할 수 있는 인수들을 보여줍니다:

인수 ChannelCreate /
ChannelSubscribe
ChannelDestroy PublishMessage ChannelUnsubscribe
AppId
AppVersion
Region
ChannelType ("Public")
ChannelName
HistoryLen
HistoryCount
UserId
ChannelState

Back To Top

세부 경로

ChannelCreate

이 webhook는 Photon 서버에서 채널을 만들려고 할 때 전송됩니다. 이전에 ChannelState 를 저장 한 경우 webhooks 응답으로 반환하여 내역을 로드해야합니다. 예를 보려면 "반환 값"을 참조하십시오.

Back To Top

특별한 인수

HistoryLen: 구독 오퍼레이션에서 클라이언트가 설정한 동일한 이름의 인수를 전달합니다. 클라이언트가 요청한 이력의 메시지 수를 포함 합니다.

샘플 호출

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

Back To Top

ChannelDestroy

Photon 서버에서 채널이 파괴되려고 할 때 이 webhook이 전송됩니다. 이 Webhook는 빈 채널이 타임아웃 될 때 발생합니다. 채널에 가입자가 떠나 아무도 남아 있지 않았을 때 채널은 비어있는 것으로 간주됩니다. 빈 채널 타임아웃 기본값은 5초입니다. IsPersistenttrue 로 설정하고 PathChannelDestory를 올바르게 구성하면 ChannelState 가 webhook 본문으로 전송됩니다. ChannelState에서 History 객체는 디버깅 목적으로만 사용됩니다. 폐기 할 수도 있습니다. Photon 서버는 BinaryHistory를 사용하여 데이터 형식을 유지합니다. 나중에 채널 이력을 로드하려면 현재 값을 저장해야합니다.

샘플 호출

{
   "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

ChannelSubscribe

이 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

ChannelUnsubscribe

이 webhook는 다음의 사유들중 하나에 의해서 클라이언트가 채널에서 연결해제 되었을 때 트리거 됩니다:

  • 구독 해지 오퍼레이션에 대한 명시적 호출.
  • 명시적인 연결해제.
  • 타임아웃 연결해제.
  • 채널 생성 실패와 SkipPostCreationFailurefalse 로 설정
  • 구독 실패.

샘플 호출

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

Back To Top

PublishMessage

이 webhook는 클라이언트가 채널에 메시지를 게시했을 때 트리거 됩니다.

Specific Arguments

Message: 채널의 모든 구독자에게 게시하는 메시지. 클라이언트로부터 전송되는 것처럼 전달됩니다.

샘플 호출

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

Back To Top

반환 값

모든 webhook는 JSON 객체를 담고 있으며 ResultCode 값은 다음과 같습니다:

  • 성공시에는 0.

성공 응답 샘플

{
   "ResultCode":0,
   "Message":"OK"
}
  • 이외 다른 정수값은 실패입니다.

실패 응답 샘플

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

"ChannelCreate" webhook는 ChannelState 인 웹서버로부터 추가 속성을 수신 할 수도 있습니다.

샘플 "Full" 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" 는 상태 불러오기에는 필수가 아니기 때문에 디버깅에 매우 유용합니다. 상태 저장 또는 상태를 불러올 때는 무시 할 수도 있습니다.

샘플 "Stripped" ChannelCreate 응답

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

다음 사항들에 대한 모법 사례로 간주됩니다.:

  • 사용자정의 오류 유형별 예약 ResultCode 값의 목록을 갖을 때.
  • 디버깅시에 유용하게 사용하는 메시지 문자열을 리턴할 때.

아래 표는 webhook을 사용하여 취소하거나 중단 할 수 있는 채팅 오퍼레이션을 보여줍니다. 그렇게 하려면 0이 아닌 ResultCode를 리턴해야하며 선택적으로 OperationResponseDebugMessage에서 찾을 수있는 Message를 리턴해야 합니다.

Webhook 취소될 수 있음
ChannelCreate
ChannelDestory
ChannelSubscribe
ChannelUnsubscribe
PublishMessage

Back To Top

URL 태그

대시보드에서 Webhooks 또는 WebRpc 의 기준 URL을 설정 할 때 하나 이상의 "동적 변수"를 설정 할 수 있습니다. 이러한 변수들은 요청을 전송하기 전에 백엔드에서 상응하는 값들로 교체 되게 됩니다.

어플리케이션에서 사용자들을 서로 다르게 분리하여 처리를 원할 때 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}

Back To Top

데이터 타입 변환

이 섹션에서는 Photon 서버와 웹 서비스간의 데이터 교환의 타입에 대해서만 설명합니다. 클라이언트와 Photon 서버간의 데이터 타입에 대해서는 Photon 의 직렬화 페이지를 참고 하시기 바랍니다.

Back To Top

Photon 서버 -> 웹 서비스

C# / .NET (Photon 지원 타입) JavaScript / JSON
byte number
short
int
long
double
bool bool
string string
byte[] (byte 배열 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

Back To Top

샘플 요청 데이터 (타입들이 연결되어 있습니다)

Photon 서버 전송:

Web 서비스 수신:

Back To Top

웹 서비스 -> Photon 서버

C#/.Net 에서 JavaScript/JSON 타입과 각각 대응하는 테이블입니다. Here is a table that matches each JavaScript/JSON type to its equivalent one in 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

Back To Top

응답 데이터 샘플 (타입들이 연결되어 있습니다)

Web Service 전송:

Photon Server 수신:

기술문서 TOP으로 돌아가기