메시징 사용 가이드

메시징 서비스 API는 엔진의 MessagingService와 동등한 Open Cloud 서비스로, 게임의 서버와 클라이언트 간에 소통할 수 있게 해줍니다. 엔진 API는 메시지를 게시하기 위해 Studio에서 수동으로 스크립트를 작성하고 업데이트하는 것만 허용하지만, Open Cloud API는 외부 도구에서 라이브 서버로 메시지를 전송하여 운영 작업 흐름을 자동화하고 개선할 수 있습니다.

사용법

메시징 서비스 API로 크로스 서버 통신을 지원하며 구축할 수 있는 몇 가지 유용한 도구는 다음과 같습니다:

• 공지 포털: 공지 포털은 게임의 모든 사용자에게 이벤트, 업데이트, 대회의 우승자 발표와 같은 공지를 전송하는 데 도움이 될 수 있습니다. 포털에서 메시지를 수정하고, 버튼을 클릭하여 API를 호출하여 모든 사용자 또는 선택된 사용자에게 메시지를 전송할 수 있습니다.

• 모더레이션 시스템: 모더레이션 시스템은 게임을 안전하고 보안하게 유지하는 데 도움이 됩니다. 부적절한 행동을 하는 사용자를 감지하면 특정 사용자에게 경고하거나 차단하도록 게임 서버를 트리거하는 메시지를 게시할 수 있습니다. 모더레이션 시스템에서 데이터 저장소를 사용하여 재가입을 방지하는 블록 리스트에 사용자 계정을 추가할 수 있습니다.

• LiveOps 대시보드: LiveOps 대시보드는 할로윈 파티와 같은 라이브 이벤트를 관리하는 데 유용한 도구입니다. 대시보드에서 이벤트를 미리 코딩하고, 이벤트 메시지를 업데이트하고, 이벤트가 준비되었을 때 트리거하며, 게임 코드를 업데이트하지 않고도 선택된 사용자에게 특별한 아이템(예: 가상 왕관)을 보상할 수 있습니다.

제한 사항

메시징 서비스 API는 엔진의 MessagingService와 동일한 제한 사항을 따릅니다. 속도 제한은 두 API 간에 공유되며, 두 API의 사용량은 동일한 제한에 대해 계산됩니다.

메시징을 위한 주제 설정

게임의 라이브 서버에 메시지를 게시하기 전에, 여러 서버에서 액세스할 수 있는 커스터마이즈된 메시지 채널인 주제를 설정해야 합니다. 주제를 정의한 후에는 사용자에게 주제를 구독시켜 들어오는 메시지를 받을 수 있어야 합니다.

현재 주제를 Studio에서 정의하고 Luau API MessagingService:SubscribeAsync()를 사용하여 사용자에게 구독할 수 있습니다. 다음 코드 샘플은 사용자가 게임에 참여할 때 주제에 구독하는 방법을 보여줍니다:

주제 설정 및 사용자 구독
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- 주제를 정의하고 구독합니다
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- 플레이어 조상이 변경되면 주제에서 구독 해지
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

라이브 서버에 메시지 게시

주제를 설정한 후 게임의 라이브 서버에 메시지를 게시합니다:

1. API 키 생성 를 위해 크리에이터 대시보드에서 키를 생성하고 안전한 곳에 복사합니다. 다음 설정을 수행해야 합니다:

   1. Access Permissions에 messaging-service를 추가합니다.
   2. 게임을 선택하고 universe-messaging-service:publish 작업을 추가합니다.

2. 게임의 UnIVERSE ID를 가져옵니다:

   1. 크리에이터 대시보드로 이동합니다.

   2. 메시지를 게시하고자 하는 게임을 찾습니다.

   3. 게임 썸네일 위에 마우스를 올리고 ⋯ 버튼을 클릭하여 Copy Universe ID를 선택합니다.

      

3. API 키와 우주를 POST 요청에 추가합니다, 다음의 예와 같이:

   메시지 게시를 위한 예시 요청
   curl -L -X POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   -H 'x-api-key: {api-key}' \
   -H 'Content-Type: application/json' \
   --data '{
    "topic": "your-topic",
    "message": "안녕하세요, 여러분!"
   }'

4. HTTP 요청을 전송하여 메시지를 게시합니다.

   요청이 성공하면 HTTP 200과 함께 응답 본문이 비어 있습니다.

OAuth 2.0 앱에 메시징 서비스 API 추가

사용자가 자신의 라이브 서버에 메시지를 게시할 수 있도록 할 수 있는 OAuth 2.0 애플리케이션을 생성할 수 있습니다.

애플리케이션에서 메시징 서비스 API를 사용하고 사용자에게 권한을 요청하기 위해 다음 설정을 수행합니다:

1. 애플리케이션 등록 시 Permissions에서 universe-messaging-service:publish 범위를 선택합니다.

2. 인증 흐름 구현 시 scope의 인증 URL 매개변수에 universe-messaging-service:publish를 포함합니다. 이는 사용자가 애플리케이션으로 돌아갈 때를 위한 예시입니다:

   https://apis.roblox.com/oauth/v1/authorize?client_id=816547628409595165403873012&redirect_uri=https://my-app.com/redirect&scope=openid+universe-messaging-service:publish&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. 사용자가 메시지를 게시하고자 하는 게임의 universeId 접근 요청을 합니다. 애플리케이션은 접근 토큰, 클라이언트 ID와 비밀 또는 code challenge에 따라, 토큰 자원 엔드포인트로 POST 요청을 보내 universeIds의 목록을 받을 수 있습니다:

   예시 요청
   curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/resources' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'token=<access_token>' \
   --data-urlencode 'client_id=<client_id>' \
   --data-urlencode 'client_secret=<client_secret>'

   이 엔드포인트는 다음과 같은 예시 응답과 같이 universeIds의 목록을 반환합니다:

   예시 응답
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. 이제 애플리케이션은 사용자가 권한을 부여한 모든 게임에 메시지를 전송할 수 있습니다. 요청을 보낼 때는 인증 헤더에 접근 토큰을 포함하고, 요청 URI에 universeId와 주제를 아래와 같은 형식으로 포함합니다:

   예시 요청
   curl --location --request POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   --header 'Authorization: Bearer <access_token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{"topic": "some-topic","message":"게시할 메시지"}'

HTTPService와 사용

이 API는 HttpService에서 지원하는 Open Cloud 엔드포인트 중 하나입니다. 이를 사용하여 게임 내에서 서로 다른 게임 간에 메시지를 게시할 수 있습니다.