푸시 메시지 전송

Cloud Code C# 모듈에서는 WebSocket을 통해 메시지를 클라이언트에 푸시할 수 있습니다. 이 페이지는 이 기능의 개요와 더불어 Cloud Code 모듈과 Cloud Code SDK에서 이 기능을 사용하는 방법에 관한 지침을 제공합니다.

참고: 푸시 메시지와 푸시 알림은 게임에서 다른 목적으로 사용됩니다. 푸시 메시지는 게임플레이에 적극적으로 참여하는 플레이어를 타게팅하며, 푸시 알림은 게임이 비활성 상태이거나 백그라운드에서 가동되고 있을 때 디바이스에 전송됩니다.

푸시 메시지를 보내려면 모듈 엔드포인트를 호출해야 합니다. Unity 에디터에서 푸시 메시지를 구독할 수 있습니다.

사용 사례 및 이점

다음과 같이 다양한 목적으로 푸시 메시지를 사용할 수 있습니다.

사용예시이점
실시간으로 메시지를 서버에서 클라이언트로 푸시하여 게임의 상호 작용을 향상합니다.플레이어에게 게임 이벤트, 업데이트 또는 비동기식 멀티플레이어 게임(예: 경쟁 카드 게임)에 대해 알릴 수 있습니다.실시간 상호 작용
업데이트와 알림을 클라이언트에 바로 푸시하여 사용자에게 최신 이벤트, 변경 사항 또는 게임 내 액션과 관련된 소식을 계속 알려 줍니다.데이터가 사용 가능해지면 바로 사용자에게 알릴 수 있어 수동으로 새로 고치거나 업데이트를 확인하지 않아도 됩니다. 실시간 전략 게임 같이 빈번한 업데이트가 필요한 게임에서 특히 유용합니다.사용자 경험
기존 폴링 기법보다 효율성을 높이기 위해 WebSocket을 사용하여 메시지를 푸시합니다.클라이언트는 새 데이터가 있는지 서버에 계속해서 묻는 대신, 데이터가 사용 가능해졌을 때 서버에서 새 데이터를 전송할 때까지 기다리면 됩니다. 이렇게 되면 불필요한 네트워크 트래픽이 감소하여 지연이 줄어듭니다.효율적인 네트워크 사용
푸시 모델의 확장성을 사용하여 많은 사용자가 참여하는 게임을 지원합니다.Cloud Code에서 푸시 메시지를 사용하여 연결된 모든 클라이언트에 한 번에 업데이트를 보내 수많은 플레이어가 참여하는 멀티플레이어 게임에서 운영 비용과 요청의 양을 줄일 수 있습니다.확장성과 비용
이벤트 기반 모델을 사용하여 다양한 유형의 메시지에 대한 게임의 응답을 커스터마이즈합니다.수신하는 메시지의 MessageType 프로퍼티에 따라 다양한 게임 액션을 트리거할 수 있습니다.커스터마이즈 기능
Unity 생태계의 일부로서 Cloud Code를 다른 Unity 서비스와 함께 원활하게 사용합니다.Unity Authentication 서비스를 사용하여 플레이어 인증을 처리하고 Unity 게임 엔진 내에서 메시지를 처리할 수 있습니다.원활한 연동

모듈 생성

다음 코드 예시는 두 메서드가 포함된 모듈의 기본 구조를 보여 줍니다.

  • SendPlayerMessage: 연결된 특정 플레이어에게 메시지를 보냅니다.
  • SendProjectMessage: 프로젝트에서 연결된 모든 플레이어에게 메시지를 브로드캐스트합니다.

Unity.Services.CloudCode.Apis 패키지는 푸시 메시지를 보내는 데 사용되는 인터페이스인 PushClient 인스턴스를 제공합니다.

C#

using Microsoft.Extensions.DependencyInjection;
using Unity.Services.CloudCode.Core;
using Unity.Services.CloudCode.Apis;

namespace PushExample
{
    public class PushExample
    {
        [CloudCodeFunction("SendPlayerMessage")]
        public async Task<string> SendPlayerMessage(IExecutionContext context, PushClient pushClient, string message, string messageType, string playerId)
        {
            var response = await pushClient.SendPlayerMessageAsync(context, message, messageType, playerId);
            return "Player message sent";
        }

        [CloudCodeFunction("SendProjectMessage")]
        public async Task<string> SendProjectMessage(IExecutionContext context, PushClient pushClient, string message, string messageType)
        {
            var response = await pushClient.SendProjectMessageAsync(context, message, messageType);
            return "Project message sent";
        }
    }

    public class ModuleConfig : ICloudCodeSetup
    {
        public void Setup(ICloudCodeConfig config)
        {
            config.Dependencies.AddSingleton(PushClient.Create());
        }
    }
}

모듈을 배포하는 방법을 알아보려면 Hello World 배포 페이지를 참고하십시오.

Unity 에디터 설정

Cloud Code SDK는 메시지를 구독할 수 있는 인터페이스를 제공합니다. 특정 플레이어 또는 전체 플레이어를 위해 메시지를 구독할 수 있습니다.

Unity 에디터에서 Cloud Code를 사용하려면 먼저 Cloud Code SDK를 설치하고 Unity Gaming Services 프로젝트를 Unity 에디터에 연결해야 합니다.

프로젝트 연결

Unity Gaming Services 프로젝트를 Unity 에디터에 연결합니다. Unity Dashboard에서 UGS 프로젝트 ID를 확인할 수 있습니다.

  1. Unity 에디터에서 Edit > Project Settings > Services를 선택합니다.

  2. 프로젝트를 연결합니다.
    프로젝트에 Unity 프로젝트 ID가 없는 경우 다음 단계를 진행합니다.

    1. Create a Unity Project ID > Organizations를 선택한 다음 드롭다운에서 조직을 선택합니다.
    2. Create project ID를 선택합니다.


    기존 Unity 프로젝트 ID가 있는 경우 다음 단계를 진행합니다.

    1. Use an existing Unity project ID를 선택합니다.
    2. 드롭다운에서 조직과 프로젝트를 선택합니다.
    3. Link project ID를 선택합니다.

이렇게 하면 Unity 프로젝트 ID가 표시되고 프로젝트가 Unity 서비스에 연결됩니다. UnityEditor.CloudProjectSettings.projectId 파라미터를 사용하여 Unity 에디터 스크립트에서 프로젝트 ID에 액세스할 수도 있습니다.

SDK 설치

다음과 같이 Unity 에디터용 최신 Cloud Code 패키지를 설치합니다.

  1. Unity 에디터에서 Window > Package Manager를 엽니다.
  2. 패키지 관리자에서 Unity Registry 목록 뷰를 선택합니다.
  3. com.unity.services.cloudcode를 검색하거나 목록에서 Cloud Code 패키지를 찾습니다.
  4. 패키지를 선택하고 Install을 클릭합니다.

참고: Cloud Code SDK 버전 2.4.0 이상에서 메시지를 구독할 수 있습니다.

참고: Unity 패키지 관리자 인터페이스를 익히려면 Package Manager 창 기술 자료를 참고하십시오.

SDK 설정

다음과 같이 Cloud Code SDK를 시작합니다.

  1. Cloud Code 서비스 대시보드 페이지를 통해 서비스를 활성화합니다.
  2. Cloud Code와 Authentication SDK를 모두 설치합니다.
  3. Edit > Project Settings > Services를 선택하여 Unity 에디터 내에서 클라우드 프로젝트에 로그인합니다.
  4. Unity 에디터에서 새 C# Monobehaviour 스크립트를 생성합니다. Unity 매뉴얼의 스크립트 생성 및 사용을 참고하십시오.
  5. 스크립트에서 await UnityServices.InitializeAsync()를 사용하여 Core SDK를 초기화합니다.
  6. 스크립트에서 Authentication SDK를 초기화합니다.

참고: Cloud Code 서비스에 액세스하려면 플레이어에게 유효한 플레이어 ID와 액세스 토큰이 있어야 합니다. Cloud Code API를 사용하려면 먼저 Authentication SDK로 플레이어를 인증해야 합니다. 다음 코드 스니핏을 사용하여 익명으로 인증하거나 Authentication 기술 자료에서 자세한 내용과 기타 로그인 방법을 확인할 수 있습니다.

C#

await AuthenticationService.Instance.SignInAnonymouslyAsync();

메시지 구독

특정 플레이어 또는 전체 플레이어를 위해 메시지를 구독할 수 있습니다. 다음 코드 스니핏을 Unity 프로젝트의 MonoBehaviour 스크립트에 대한 가이드로 사용할 수 있습니다.

이 스크립트는 익명 플레이어로 인증하며 플레이어별, 프로젝트별 메시지 모두를 구독하고 다양한 유형의 이벤트를 처리합니다.

C#

using System;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Unity.Services.Authentication;
using Unity.Services.CloudCode;
using Unity.Services.CloudCode.Subscriptions;
using Unity.Services.Core;
using UnityEngine;
namespace CloudCode
{
	public class CloudCodePushExample : MonoBehaviour
	{
    	async void Start()
        {
            await UnityServices.InitializeAsync();
            await AuthenticationService.Instance.SignInAnonymouslyAsync();
            Debug.Log(AuthenticationService.Instance.PlayerId);
            await SubscribeToPlayerMessages();
            await SubscribeToProjectMessages();
        }
        // This method creates a subscription to player messages and logs out the messages received,
        // the state changes of the connection, when the player is kicked and when an error occurs.
        Task SubscribeToPlayerMessages()
        {
            // Register callbacks, which are triggered when a player message is received
            var callbacks = new SubscriptionEventCallbacks();
            callbacks.MessageReceived += @event =>
            {
                Debug.Log(DateTime.Now.ToString("yyyy-MM-dd'T'HH:mm:ss.fffK"));
                Debug.Log($"Got player subscription Message: {JsonConvert.SerializeObject(@event, Formatting.Indented)}");
            };
            callbacks.ConnectionStateChanged += @event =>
            {
                Debug.Log($"Got player subscription ConnectionStateChanged: {JsonConvert.SerializeObject(@event, Formatting.Indented)}");
            };
            callbacks.Kicked += () =>
            {
                Debug.Log($"Got player subscription Kicked");
            };
            callbacks.Error += @event =>
            {
                Debug.Log($"Got player subscription Error: {JsonConvert.SerializeObject(@event, Formatting.Indented)}");
            };
            return CloudCodeService.Instance.SubscribeToPlayerMessagesAsync(callbacks);
        }
        // This method creates a subscription to project messages and logs out the messages received,
        // the state changes of the connection, when the player is kicked and when an error occurs.
        Task SubscribeToProjectMessages()
        {
            var callbacks = new SubscriptionEventCallbacks();
            callbacks.MessageReceived += @event =>
            {
                Debug.Log(DateTime.Now.ToString("yyyy-MM-dd'T'HH:mm:ss.fffK"));
                Debug.Log($"Got project subscription Message: {JsonConvert.SerializeObject(@event, Formatting.Indented)}");
            };
            callbacks.ConnectionStateChanged += @event =>
            {
                Debug.Log($"Got project subscription ConnectionStateChanged: {JsonConvert.SerializeObject(@event, Formatting.Indented)}");
            };
            callbacks.Kicked += () =>
            {
                Debug.Log($"Got project subscription Kicked");
            };
            callbacks.Error += @event =>
            {
                Debug.Log($"Got project subscription Error: {JsonConvert.SerializeObject(@event, Formatting.Indented)}");
            };
            return CloudCodeService.Instance.SubscribeToProjectMessagesAsync(callbacks);
        }
	}
}

플레이어에게 메시지 전송

플레이어에게 메시지를 보내려면 모듈에서 SendPlayerMessage 또는 SendProjectMessage 함수를 호출합니다.

모듈을 실행하는 방법을 알아보려면 모듈 실행을 참고하십시오.

Unity Runtime에서 실행

CloudCodeService 인스턴스의 CallModuleEndpointAsync 메서드를 통해 다른 플레이어에게 메시지를 보낼 수 있습니다. 모듈 이름과 함수 이름을 처음 두 개의 인자로, 필수 파라미터가 있는 딕셔너리를 세 번째 인자로 사용해야 합니다.

예를 들어 플레이어에게 메시지를 보내려면 다음을 호출하면 됩니다.

var sendPlayerMessageResult = await CloudCodeService.Instance.CallModuleEndpointAsync<string>("PushExample", "SendPlayerMessage",
	new Dictionary<string, object> {{"message", "hello with a player message from PushExample!"}, {"messageType", "testType"}, {"playerId", "<other-unity-player-ID>"}});

참고: 이 사용 사례에서 액세스 제어 정책을 생성하여 엔드포인트에 대한 플레이어 액세스를 제한할 수 있습니다. 예를 들어 플레이어가 게임에서 다른 모든 플레이어에게 프로젝트 메시지를 보내는 SendProjectMessage 모듈 함수를 호출하지 못하도록 할 수 있습니다.

이벤트

플레이어와 프로젝트별 구독 모두에 다음과 같은 4개의 이벤트 핸들러가 있습니다.

  • MessageReceived: 플레이어가 새 메시지를 수신하면 트리거됩니다.
  • ConnectionStateChanged: 연결 상태가 변경되면 트리거됩니다.
  • Kicked: 서버가 메시지로부터 플레이어를 강제로 구독 취소하면 트리거됩니다. 이때 WebSocket 연결이 종료되지는 않으며, 게임 클라이언트가 메시지를 다시 구독하지 못하도록 차단하지도 않습니다.
  • Error: 연결 처리에서 오류가 발생하거나 플레이어가 메시지를 수신하면 트리거됩니다.

메시지 엔벨로프

IMessageReceivedEvent는 플레이어가 푸시 서비스로부터 수신하는 메시지를 나타내는 인터페이스입니다. Cloud Code가 WebSocket 연결을 통해 메시지를 보내면 이벤트가 트리거됩니다.

IMessageReceivedEvent 인터페이스의 페이로드는 아래 표를 참고하십시오.

프로퍼티설명예시
SpecVersion수신한 메시지 엔벨로프의 규격 버전입니다. 이 프로퍼티를 사용하면 클라이언트가 메시지를 올바르게 처리할 수 있습니다.1.0
Id메시지에 대한 고유 ID입니다. 이 프로퍼티를 사용하여 메시지를 트래킹하거나 기록합니다.4f88f657-27da-4b1d-a013-9033dbc7b48b
Source메시지 엔벨로프의 소스입니다. 메시지의 출처를 나타내며 메시지를 디버깅하거나 라우팅하는 데 사용할 수 있습니다. 소스는 항상 Cloud Code의 도메인입니다.https://cloud-code.service.api.unity.com
Type메시지의 엔벨로프 유형입니다. 이 프로퍼티는 메시지에 포함된 데이터 유형을 나타내며, 이 프로퍼티를 통해 클라이언트가 처리 방식을 결정할 수 있습니다. 값은 항상 Cloud Code 메시지 유형입니다.com.unity.services.cloud-code.push.v1
Time메시지 생성 날짜 및 시간입니다. 이 프로퍼티를 사용하여 메시지를 기록하거나 지연을 계산할 수 있습니다.2023-09-19T10:26:40.436878688Z
ProjectId메시지가 연결된 프로젝트의 ID입니다.b6670776-9fd3-4d66-8bf4-63fb1112dc95
EnvironmentId메시지의 대상인 환경의 ID입니다. 이 프로퍼티를 사용하여 데브, 스테이징, 프로덕션 같이 서로 다른 개발 환경을 구별할 수 있습니다.a4bc2571-d1e7-4507-9cc9-80b687d48d8f
CorrelationId관련된 메시지의 배열을 트래킹하는 데 사용할 수 있는 ID입니다. 예를 들어 여러 메시지가 대화 또는 워크플로를 구성하는 경우 상관 관계 ID를 공유할 수 있습니다.afbd7c6e-e999-4ca2-86fc-3c908ba83bf2
MessageCloud Code에서 플레이어로 전송되는 실제 메시지 내용입니다.‘hello world!’
MessageType플레이어가 수신하는 메시지의 유형입니다. Type과 유사하지만 엔벨로프가 아닌 메시지 내용과 관련됩니다.‘정보’

네트워크 사용량과 비용 고려 사항

메시지를 클라이언트에 푸시하기 위해 Cloud Code WebSocket 기능을 사용하는 경우 네트워크 사용량과 관련 비용에 관해 중요한 고려 사항이 있습니다.

송신 비용

모듈에서 클라이언트에 보내는 각 메시지는 네트워크 대역폭을 소비하며 이는 모듈의 송신 데이터 총량에 영향이 미칩니다. Cloud Code는 WebSocket 연결을 통한 메시지 푸시와 관련된 네트워크 사용량을 Cloud Code 송신 비용에 더합니다.

애플리케이션을 설계하고 메시지를 보낼 시기와 방식을 결정할 때 이 점을 염두에 두어야 합니다. 과도하거나 불필요하게 큰 메시지로 인해 송신 비용이 증가할 수 있습니다.

Cloud Code 가격 책정에 대해 자세히 알아보려면 비용 페이지를 참고하십시오.

메시지 크기 제한

Cloud Code는 WebSocket 연결을 통해 전송되는 메시지의 크기를 10KB로 제한합니다. 따라서 특히 더 복잡하거나 데이터가 많은 애플리케이션의 경우 보내는 데이터의 크기를 관리해야 합니다.

아래 방법을 사용하면 플레이어에게 최신 정보를 제공하며 비용과 네트워크 사용량도 낮게 유지할 수 있습니다.

데이터 비교 분석 전송

대량의 데이터나 게임 상태의 중요한 변경 사항을 전달해야 하는 경우 전체 페이로드가 아닌 데이터 비교 분석을 보낼 수 있습니다. 비교 분석은 기존 상태에 적용하는 일련의 변경 사항으로, 대부분 전체 상태 데이터보다 크기가 훨씬 작습니다.

데이터에 대한 HTTP 요청 표시

WebSocket 메시지를 넛지 메커니즘으로 사용하여 새 데이터가 사용 가능해졌음을 클라이언트에 알리고 전체 데이터 세트를 가져오기 위한 HTTP 요청을 생성하도록 메시지를 표시할 수 있습니다. 전체 데이터 세트가 크고 업데이트가 자주 필요하지 않은 경우, 또는 HTTP를 통해 데이터를 가져오는 것이 더 효율적이거나 비용 효율적인 경우에 이 방법을 사용할 수 있습니다.