채팅 Webhook

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

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

설정

기본 설정

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

Paths

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

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

옵션

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

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

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

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

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

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

공통 기준

모든 Webhook에 대한 공통 인수

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

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

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

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

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

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

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

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

인수 목록

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

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

세부 경로

ChannelCreate

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

특별한 인수

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

샘플 호출

text

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

ChannelDestroy

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

샘플 호출

text

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

ChannelSubscribe

이 webhook은 이미 생성된 채널에 클라이언트 구독에 의해 트리거됩니다. 클라이언트는 다음 중 하나입니다:

  • 첫 번째의 구독자가 아닙니다. 이것은 가장 많이 발생하는 사례이어야 합니다.
  • 채널이 비어있고 타임아웃이 일어나지 않을 때 첫 번째 구독자입니다. 작은 창이기 때문에 가능성이 희박합니다.

특별한 인수

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

샘플 호출

text

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

ChannelUnsubscribe

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

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

샘플 호출

text

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

PublishMessage

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

Specific Arguments

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

샘플 호출

text

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

반환 값

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

  • 성공시에는 0.

성공 응답 샘플

text

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

실패 응답 샘플

text

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

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

샘플 "Full" ChannelCreate 응답

text

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

text

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

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

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

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

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

URL 태그

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

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

데이터 타입 변환

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

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

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

Photon 서버 전송:

JavaScript

{
    "(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":[
            "(Object)0",
            "(Object)xy",
            "(Object)False"
        ],
        "hk_null":"null"
    },
    "null":"null",
    "(String[])string[]":[
        "(String)PUN",
        "(String)TB",
        "(String)RT",
        "(String)Bolt",
        "(String)Chat"
    ],
    "(Byte[])byte[]":[
        "(Byte)255",
        "(Byte)0"
    ],
    "(Int16[])short[]":[
        "(Int16)-32768",
        "(Int16)32767"
    ],
    "(Int32[])int[]":[
        "(Int32)-2147483648",
        "(Int32)2147483647"
    ],
    "(Int64[])long[]":[
        "(Int64)-9223372036854775808",
        "(Int64)9223372036854775807"
    ],
    "(Single[])float[]":[
        "(Single)-3.402823E+38",
        "(Single)3.402823E+38"
    ],
    "(Double[])double[]":[
        "(Double)-1.79769313486232E+308",
        "(Double)1.79769313486232E+308"
    ],
    "(Boolean[])bool[]":[
        "(Boolean)True",
        "(Boolean)False"
    ]
}

Web 서비스 수신:

JavaScript

{
    "(object)Dictionary":{
        "dk_int":"(number)1",
        "dk_str":"(string)dv2",
        "dk_bool":"(boolean)true"
    },
    "(object)Hashtable":{
        "hk_byte":"(number)255",
        "hk_null":null,
        "hk_array":[
            "(number)0",
            "(string)xy",
            "(boolean)false"
        ]
    },
    "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"
    ]
}

웹 서비스 -> 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

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

Web Service 전송:

JavaScript

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

Photon Server 수신:

JavaScript

{
    "(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)number":"-3.14"
    },
    "(Object[])array":[ 
        "(Object)xyz",
        "(Object)0",
        "(Object)True",
        "null",
        "null"
    ]
}
Back to top

Cookies,
anyone?

We use cookies and related technologies to enhance your experience, show you personalised content and analyze performance and traffic on our website. By clicking on the „Accept All“ button you consent to the use of non-functional cookies and the subsequent processing of personal data to optimize our website and services as described in more detail in our Privacy and Cookie Policy.

By clicking on the „Customize or Deny all“ button you can decide otherwise. Clicking on the „Customize“ button will take you to a page where you can configure the usage of non-functional cookies (and related technologies) or deny all of them. You can access these settings at any time and also subsequently deselect cookies at any time in the footer area of our website.

ACCEPT ALL

Cookie Overview

We use the following categories of cookies and related technologies to enhance your experience, show you personalized content, and analyze performance and traffic on our website. We respect your right to privacy and accordingly you can chose to not allow some types of cookies (and related technologies). Click on the different category sliders and change our default settings to manage your cookie settings.

For more information on the specific cookies/related technologies we use and on how we use these, please see section 15 E. of our Privacy and Cookie Policy.

ABSOLUTELY NECESSARY

Authentication cookies we use are required to run our services … Cookies are required: Link

FUNCTIONAL AND MARKETING COOKIES

These cookies collect anonymous data and allow us to optimize our website and user experience. These cookies are listed here:

ANALYTICS

Help us to understand how visitors interact with our services, enables us to analyze and improve our services (also through third party analytics).