기술 자료

지원

Cloud Code

Cloud Code

시작하기

Follow this workflow to set up Triggers and automate rewarding top players from Leaderboards.
읽는 시간 3분최근 업데이트: 12시간 전
이 섹션에서는 Triggers를 시작하는 데 필요한 모든 단계를 설명합니다. 아래 샘플은 Triggers를 사용하여 리더보드의 상위 플레이어 5명에게 Scheduler에 의해 발생되는 일회성 일정 이벤트를 통해 Cloud Save에서 시즌 트로피를 수여하는 방법을 보여 줍니다.

동영상 가이드

Unity Dashboard에서 트리거를 생성하는 단계를 자세히 알아보려면 아래의 동영상을 참고하십시오.

잘못된 비디오 링크

링크는 임베드된 유효한 YouTube 링크여야 합니다.

자세히 보기

일반적인 워크플로

다음 단계를 따라 Triggers를 시작합니다.
  1. 이벤트에서 실행할 Cloud Code 스크립트 또는 모듈 생성: 이벤트가 발생할 때 실행할 게임 로직을 정의합니다.
  2. 리소스 상태를 변경하는 이벤트 일정 예약: 이벤트가 발생할 시점을 정의합니다.
  3. 이벤트에서 Cloud Code 모듈 엔드포인트를 실행할 트리거 구성: 이벤트가 발생할 때 실행할 Cloud Code 스크립트 또는 모듈을 정의합니다.
  4. 결과 확인: Cloud Code 스크립트 또는 모듈이 실행되었는지 확인합니다.

필수 조건

이 단계는 Unity Cloud Dashboard의 Unity Gaming Services 프로젝트를 이미 생성했다고 가정합니다. 먼저 필요한 액세스 역할로 서비스 계정을 생성하고 UGS CLI를 구성해야 합니다.

서비스 계정을 사용하여 인증

Scheduling 및 Triggers 서비스를 호출하려면 먼저 서비스 계정을 사용하여 인증해야 합니다.
  1. Unity Cloud Dashboard로 이동합니다.
  2. Administration > Service Accounts를 선택합니다.
  3. New 버튼을 선택하고 서비스 계정의 이름과 설명을 입력합니다.
  4. Create를 선택합니다.
다음과 같이 제품 역할을 추가하고 키를 만듭니다.
  1. Manage product roles를 선택합니다.
  2. 다음 역할을 서비스 계정에 추가합니다.
    • LiveOps 드롭다운에서 Triggers Configuration Editor, Triggers Configuration Viewer, Scheduler Configuration Editor, Scheduler Configuration Viewer, Leaderboards Admin을 선택합니다.
    • Admin 드롭다운에서 Unity Environments Viewer를 선택합니다.
  3. Save를 선택합니다.
  4. Add Key를 선택합니다.
  5. base64 인코딩을 사용하여 Key ID와 Secret key를 인코딩합니다. 포맷은 ‘key_id:secret_key’입니다. 이 값을 기록해 둡니다.
자세한 내용은 인증을 참고하십시오.

UGS CLI 구성

다음 단계를 따라 UGS CLI를 시작합니다.
  1. UGS CLI를 설치합니다.
  2. 다음과 같이 프로젝트 ID와 환경을 구성합니다.
    ugs config set project-id <your-project-id>

    ugs config set environment-name <your-environment-name>
  3. 이전에 생성한 서비스 계정을 사용하여 인증합니다. 인증 받기를 참고하십시오.

Leaderboards 설정

이 샘플을 따르려면 리더보드를 생성해야 합니다. UGS CLI를 사용하여 다음 
leaderboard.lb
파일을 배포할 수 있습니다. 이는 오름차순으로 리더보드를 정의하며 최고 점수를 계속 표시합니다. 
new-file
커맨드를 실행하여 로컬에서 리더보드 구성을 생성합니다. 
ugs leaderboards new-file leaderboard
파일 이름은 리더보드 ID와 상응합니다. 다음 구성을 사용하여 
leaderboard.lb
파일을 업데이트합니다. 
{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/leaderboards.schema.json",  "SortOrder": "asc",  "UpdateType": "keepBest",  "Name": "leaderboard"}
다음과 같이 UGS CLI 툴을 사용하여 파일을 배포합니다. 
ugs deploy leaderboard.lb
리더보드를 생성했으므로 이제 점수를 추가할 수 있습니다.

선택 사항: 리더보드에 점수 추가

다음 Cloud Code 스크립트를 실행하여 점수를 Unity Cloud Dashboard의 리더보드에 추가할 수 있습니다. 새 플레이어의 점수를 생성하려면 모든 테스트 실행에서 플레이어 ID 토큰을 재생성해야 합니다.

JavaScript

const { LeaderboardsApi } = require("@unity-services/leaderboards-1.1");const _ = require("lodash-4.17");module.exports = async ({ params, context, logger }) => {  const leaderboardsApi = new LeaderboardsApi({ accessToken: context.accessToken });  const leaderboardID = "leaderboard";  var randomScore = _.random(1, 100);  try {    await leaderboardsApi.addLeaderboardPlayerScore(context.projectId, leaderboardID, context.playerId, { score: randomScore });  } catch (err) {    logger.error("Failed to add score to the leaderboard", { "error.message": err.message });  }};

Cloud Code 설정

Triggers 서비스를 사용하려면 Cloud Code 모듈이나 Cloud Code 스크립트를 정의해야 합니다. 트리거가 발동하면 모듈이나 스크립트가 실행됩니다. 아래 샘플에서는 Leaderboards와 Cloud Save를 Cloud Code와 연동하여 리더보드의 상위 플레이어 5명에게 시즌 트로피를 수여합니다.

Cloud Code C# 모듈

문자열 인자 
key
와 
value
가 있는 함수를 사용하여 
SchedulerHelloWorld
모듈을 정의합니다. 모듈 엔드포인트 
RewardPlayers
는 리더보드의 상위 플레이어 5명을 가져와 지정된 키와 값으로 각 플레이어의 Cloud Save 데이터를 설정합니다. 
using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Logging;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.CloudSave.Model;using Unity.Services.Leaderboards.Model;namespace SchedulerHelloWorld;public class SchedulerHelloWorld{    private const string LeaderboardId = "leaderboard";    private readonly ILogger<SchedulerHelloWorld> _logger;    public SchedulerHelloWorld(ILogger<SchedulerHelloWorld> logger)    {        _logger = logger;    }    [CloudCodeFunction("RewardPlayers")]    public async Task RewardPlayers(IExecutionContext ctx, IGameApiClient gameApiClient, string key, string value)    {        var top5Players = await GetTop5(ctx, gameApiClient);        foreach (var score in top5Players)        {            try            {                var response = await gameApiClient.CloudSaveData.SetItemAsync(ctx, ctx.ServiceToken, ctx.ProjectId, score.PlayerId, new SetItemBody(key, value));                _logger.LogInformation("Data saved successfully");            }            catch (ApiException e)            {                _logger.LogError( "Failed to record data for playerId {playerId}. Error: {Error}", score.PlayerId, e.Message);                throw new Exception($"Failed to record data for playerId {score.PlayerId}. Error: {e.Message}");            }        }    }    [CloudCodeFunction("GetTopPlayers")]    public async Task<List<LeaderboardEntry>> GetTop5(IExecutionContext ctx, IGameApiClient gameApiClient)    {        try        {            var results = await gameApiClient.Leaderboards.GetLeaderboardScoresAsync(ctx, ctx.ServiceToken, new Guid(ctx.ProjectId),                LeaderboardId, null, 5);            return results.Data.Results;        }        catch (ApiException e)        {            _logger.LogError(e, "Failed to get top players for leaderboard: {LeaderboardId}. Error: {Error}", LeaderboardId, e.Message);            throw new Exception($"Failed to get top players for leaderboard: {LeaderboardId}. Error: {e.Message}");        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton(GameApiClient.Create());        }    }}
모듈을 배포합니다. 모듈을 배포하는 방법을 알아보려면 Hello World 배포를 참고하십시오.

Cloud Code JavaScript 스크립트

Cloud Code 스크립트를 생성해서도 똑같은 결과물을 얻을 수 있습니다. 다음과 같이 필수 문자열 인자인 
key
와 
value
를 사용하여 
SchedulerHelloWorld
스크립트를 생성합니다.

JavaScript

const { DataApi } = require("@unity-services/cloud-save-1.4");const { LeaderboardsApi } = require("@unity-services/leaderboards-1.1");module.exports = async ({ params, context, logger }) => {  // Get top 5 players from the Leaderboard  const leaderboardId = "my-leaderboard";  const leaderboardsApi = new LeaderboardsApi(context);  const cloudSaveApi = new DataApi(context);  let result;  try {    result = await leaderboardsApi.getLeaderboardScores(context.projectId, leaderboardId, 0, 5);  } catch (err) {    logger.error("Failed to retrieve players from the leaderboard", { "error.message": err.message });    throw err;  }  // Set Cloud Save data for every player  const promises = result.data.results.map(async (score) => {    try {      await cloudSaveApi.setItem(context.projectId, score.playerId, {        key: params.key,        value: params.value,      });    } catch (err) {      logger.error("Failed to update Cloud Save data", { "error.message": err.message }, { "affectedPlayerId": score.playerId });      return;    }  });  await Promise.all(promises);};
스크립트를 퍼블리시합니다. 스크립트를 배포하는 방법을 알아보려면 Hello World 배포를 참고하십시오.

이벤트 일정 예약

Cloud Code 스크립트 또는 모듈을 정의한 후 상위 플레이어 5명에게 트로피를 수여할 시점을 결정하는 일정을 생성할 수 있습니다. 아래 샘플은 플레이어에게 시즌 트로피를 부여하는 일회성 일정을 정의합니다. 
new-file
커맨드를 실행하여 로컬에서 일정 구성을 생성합니다. 
ugs scheduler new-file schedule-config
다음 구성을 사용하여 
schedule-config.sched
파일을 업데이트합니다. 
{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/schedules.schema.json",  "Configs": {    "grant-trophy": {      "EventName": "trophy-for-top-5",      "Type": "one-time",      "Schedule": "2024-08-28T00:00:00Z",      "PayloadVersion": 1,      "Payload": "{\"key\": \"seasonal-trophy\", \"value\": \"2024-08-28\"}"    }  }}
이벤트의 
payload
는 Cloud Code 스크립트 또는 모듈에 전달되는 Cloud Code 파라미터를 포함합니다. 이벤트가 트리거되는 날짜와 시간을 변경하려면 
schedule
필드를 수정합니다. 다음과 같이 UGS CLI 툴을 사용하여 구성을 배포합니다. 
ugs deploy schedule-config.sched
다음과 유사한 응답이 표시됩니다. 
Deployed:schedule-config.sched
이제 특정 시간에 이벤트를 트리거하는 일정이 만들어졌습니다. 하지만 이벤트가 아직 Cloud Code 스크립트 또는 모듈에 연결되지 않았습니다.

트리거 구성

Cloud Code 리소스를 일정에 연결하려면 트리거를 생성합니다. 일정이 트리거되는 등 이벤트가 발생하면 트리거가 Cloud Code 모듈 또는 스크립트를 실행합니다. 
new-file
커맨드를 실행하여 로컬에서 트리거 구성을 생성할 수 있습니다. 
ugs triggers new-file triggers-config
Cloud Code 모듈을 생성한 경우, 다음 구성으로 
triggers-config.tr
파일을 업데이트합니다. 
{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",  "Configs": [    {      "Name": "trophy-reward",      "EventType": "com.unity.services.scheduler.trophy-for-top-5.v1",      "ActionUrn": "urn:ugs:cloud-code:SchedulerHelloWorld/RewardPlayers",      "ActionType": "cloud-code"    }  ]}
Cloud Code 스크립트를 생성한 경우, 다음 구성으로 
triggers-config.tr
파일을 업데이트합니다. 
{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",  "Configs": [    {      "Name": "trophy-reward",      "EventType": "com.unity.services.scheduler.trophy-for-top-5.v1",      "ActionUrn": "urn:ugs:cloud-code:SchedulerHelloWorld",      "ActionType": "cloud-code"    }  ]}
다음과 같이 UGS CLI 툴을 사용하여 구성을 배포합니다. 
ugs deploy triggers-config.tr
다음과 유사한 응답이 표시됩니다. 
Deployed:triggers-config.tr
이제 이벤트가 발생할 때 Cloud Code 스크립트 또는 모듈을 실행하는 트리거를 만들었습니다.

결과 확인

결과를 확인하려면 이벤트 발생 전후의 상위 플레이어를 검사하면 됩니다.
  1. Unity Cloud Dashboard로 이동합니다.
  2. Products > Leaderboards를 선택합니다.
  3. Overview 섹션을 선택합니다.
  4. leaderboard
    리더보드를 선택합니다.
  5. Entries 탭을 선택합니다.
  6. 상위 플레이어 ID 중 하나를 기록해 둡니다.
다음과 같이 플레이어의 Cloud Save 데이터를 확인하면 플레이어 데이터가 업데이트되었는지 검증할 수 있습니다.
  1. Unity Cloud Dashboard에서 Products > Player Management를 선택합니다.
  2. 검색 필드에 앞서 기록해 둔 플레이어 ID를 입력하고 Find Player를 선택합니다.
  3. Cloud Save > Data 섹션으로 이동합니다.
  4. seasonal-trophy
    키와 함께 
    2023-08-28
    값을 확인할 수 있습니다.
Cloud Code 로그에서도 Cloud Code 스크립트나 모듈이 실행되었는지 확인할 수 있습니다.
  1. Unity Cloud Dashboard에서 Cloud Code를 엽니다.
  2. Logs를 선택합니다.
Logs 페이지에 
SchedulerHelloWorld
모듈이나 스크립트의 로그 엔트리가 표시됩니다.