시작하기
Follow this workflow to set up Triggers and automate rewarding top players from Leaderboards.
읽는 시간 3분최근 업데이트: 3달 전
이 섹션에서는 Triggers를 시작하는 데 필요한 모든 단계를 설명합니다. 아래 샘플은 Triggers를 사용하여 리더보드의 상위 플레이어 5명에게 Scheduler에 의해 발생되는 일회성 일정 이벤트를 통해 Cloud Save에서 시즌 트로피를 수여하는 방법을 보여 줍니다.
동영상 가이드
Unity Dashboard에서 트리거를 생성하는 단계를 자세히 알아보려면 아래의 동영상을 참고하십시오.일반적인 워크플로
다음 단계를 따라 Triggers를 시작합니다.- 이벤트에서 실행할 Cloud Code 스크립트 또는 모듈 생성: 이벤트가 발생할 때 실행할 게임 로직을 정의합니다.
- 리소스 상태를 변경하는 이벤트 일정 예약: 이벤트가 발생할 시점을 정의합니다.
- 이벤트에서 Cloud Code 모듈 엔드포인트를 실행할 트리거 구성: 이벤트가 발생할 때 실행할 Cloud Code 스크립트 또는 모듈을 정의합니다.
- 결과 확인: Cloud Code 스크립트 또는 모듈이 실행되었는지 확인합니다.
참고
참고: Triggers에서 다른 서비스에서 발생된 이벤트를 사용할 수도 있습니다. 자세한 내용은 이벤트 섹션을 참고하십시오.
필수 조건
이 단계는 Unity Dashboard의 Unity Gaming Services 프로젝트를 이미 생성했다고 가정합니다. 먼저 필요한 액세스 역할로 서비스 계정을 생성하고 UGS CLI를 구성해야 합니다.서비스 계정을 사용하여 인증
Scheduling 및 Triggers 서비스를 호출하려면 먼저 서비스 계정을 사용하여 인증해야 합니다.- Unity Dashboard로 이동합니다.
- Administration > Service Accounts를 선택합니다.
- New 버튼을 선택하고 서비스 계정의 이름과 설명을 입력합니다.
- Create를 선택합니다.
- Manage product roles를 선택합니다.
- 다음 역할을 서비스 계정에 추가합니다.
- LiveOps 드롭다운에서 Triggers Configuration Editor, Triggers Configuration Viewer, Scheduler Configuration Editor, Scheduler Configuration Viewer, Leaderboards Admin을 선택합니다.
- Admin 드롭다운에서 Unity Environments Viewer를 선택합니다.
- LiveOps 드롭다운에서 Triggers Configuration Editor, Triggers Configuration Viewer, Scheduler Configuration Editor, Scheduler Configuration Viewer, Leaderboards Admin을 선택합니다.
- Save를 선택합니다.
- Add Key를 선택합니다.
- base64 인코딩을 사용하여 Key ID와 Secret key를 인코딩합니다. 포맷은 ‘key_id:secret_key’입니다. 이 값을 기록해 둡니다.
UGS CLI 구성
다음 단계를 따라 UGS CLI를 시작합니다.- UGS CLI를 설치합니다.
-
다음과 같이 프로젝트 ID와 환경을 구성합니다.
ugs config set project-id <your-project-id>
ugs config set environment-name <your-environment-name> - 이전에 생성한 서비스 계정을 사용하여 인증합니다. 인증 받기를 참고하십시오.
Leaderboards 설정
이 샘플을 따르려면 리더보드를 생성해야 합니다. UGS CLI를 사용하여 다음leaderboard.lbnew-file파일 이름은 리더보드 ID와 상응합니다. 다음 구성을 사용하여ugs leaderboards new-file leaderboard
leaderboard.lb다음과 같이 UGS CLI 툴을 사용하여 파일을 배포합니다.{ "$schema": "https://ugs-config-schemas.unity3d.com/v1/leaderboards.schema.json", "SortOrder": "asc", "UpdateType": "keepBest", "Name": "leaderboard"}
리더보드를 생성했으므로 이제 점수를 추가할 수 있습니다.ugs deploy leaderboard.lb
선택 사항: 리더보드에 점수 추가
다음 Cloud Code 스크립트를 실행하여 점수를 Unity 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# 모듈
문자열 인자keyvalueSchedulerHelloWorldRewardPlayers모듈을 배포합니다. 모듈을 배포하는 방법을 알아보려면 Hello World 배포를 참고하십시오.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()); } }}
참고
참고: UGS CLI를 사용하여 모듈을 배포하는 경우 서비스 계정 역할 를 추가해야 합니다.
Cloud Code EditorCloud Code JavaScript 스크립트
Cloud Code 스크립트를 생성해서도 똑같은 결과물을 얻을 수 있습니다. 다음과 같이 필수 문자열 인자인keyvalueSchedulerHelloWorldJavaScript
스크립트를 퍼블리시합니다. 스크립트를 배포하는 방법을 알아보려면 Hello World 배포를 참고하십시오.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);};
참고
참고: UGS CLI를 사용하여 스크립트를 배포하는 경우 서비스 계정 역할 와 를 추가해야 합니다.
Cloud Code Script PublisherCloud Code Editor이벤트 일정 예약
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\"}" } }}
payloadschedule다음과 유사한 응답이 표시됩니다.ugs deploy schedule-config.sched
이제 특정 시간에 이벤트를 트리거하는 일정이 만들어졌습니다. 하지만 이벤트가 아직 Cloud Code 스크립트 또는 모듈에 연결되지 않았습니다.Deployed: schedule-config.sched
트리거 구성
Cloud Code 리소스를 일정에 연결하려면 트리거를 생성합니다. 일정이 트리거되는 등 이벤트가 발생하면 트리거가 Cloud Code 모듈 또는 스크립트를 실행합니다.new-fileCloud Code 모듈을 생성한 경우, 다음 구성으로ugs triggers new-file triggers-config
triggers-config.trCloud Code 스크립트를 생성한 경우, 다음 구성으로{ "$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" } ]}
triggers-config.tr다음과 같이 UGS CLI 툴을 사용하여 구성을 배포합니다.{ "$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 deploy triggers-config.tr
이제 이벤트가 발생할 때 Cloud Code 스크립트 또는 모듈을 실행하는 트리거를 만들었습니다.Deployed: triggers-config.tr
결과 확인
결과를 확인하려면 이벤트 발생 전후의 상위 플레이어를 검사하면 됩니다.- Unity Dashboard로 이동합니다.
- Products > Leaderboards를 선택합니다.
- Overview 섹션을 선택합니다.
- 리더보드를 선택합니다.
leaderboard - Entries 탭을 선택합니다.
- 상위 플레이어 ID 중 하나를 기록해 둡니다.
- Unity Dashboard에서 Products > Player Management를 선택합니다.
- 검색 필드에 앞서 기록해 둔 플레이어 ID를 입력하고 Find Player를 선택합니다.
- Cloud Save > Data 섹션으로 이동합니다.
- 키와 함께
seasonal-trophy값을 확인할 수 있습니다.2023-08-28
- Unity Dashboard에서 Cloud Code를 엽니다.
- Logs를 선택합니다.
SchedulerHelloWorld