사용 사례 샘플: 시즌 종료 시 상위 플레이어에게 게임 내 재화로 보상 제공

Reward your top players with in-game currency at the end of a season using Triggers.

읽는 시간 3분

최근 업데이트: 12시간 전

이 사용 사례 샘플은 시즌 종료 시 상위 플레이어에게 게임 내 재화로 보상을 제공하는 방법을 보여 줍니다. 샘플에서는 Leaderboards 서비스에서 발생하는

reset

이벤트를 사용하고, Economy에서 게임 내 재화로 상위 플레이어에게 보상을 제공합니다.

필수 조건

먼저 필수 액세스 역할로 서비스 계정을 생성하고 UGS CLI를 구성해야 합니다.

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

Triggers 서비스를 호출하려면 먼저 서비스 계정을 사용하여 인증해야 합니다.

Unity Cloud Dashboard로 이동합니다.
Administration > Service Accounts를 선택합니다.
New 버튼을 선택하고 서비스 계정의 이름과 설명을 입력합니다.
Create를 선택합니다.

다음과 같이 제품 역할을 추가하고 키를 만듭니다.

Manage product roles를 선택합니다.
다음 역할을 서비스 계정에 추가합니다.
- LiveOps 드롭다운에서 다음 역할을 선택합니다.
  - Triggers 구성 편집자
  - Triggers 구성 조회자
  - Economy 리소스 편집자
  - Economy 리소스 조회자
  - Leaderboards 관리자
  - Leaderboards 조회자
  - Cloud Code 모듈을 배포 중인 경우 다음 역할을 추가합니다.
    - Cloud Code 편집자
    - Cloud Code 조회자
  - Cloud Code 스크립트를 배포 중인 경우 다음 역할을 추가합니다.
    - Cloud Code 편집자
    - Cloud Code 조회자
    - Cloud Code 퍼블리셔
- Admin 드롭다운에서 Unity Environments Viewer를 선택합니다.
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>

앞서 인증된 서비스 계정을 사용하여 인증을 받습니다. 인증 받기를 참고하십시오.

reset 이벤트 확인

리더보드가 초기화되면 Leaderboards 서비스에서

reset

이벤트가 발생합니다. 이벤트 페이로드의 예시는 다음과 같습니다.


{  "leaderboardId": "string",  "leaderboardVersionId": "string"}

이벤트 페이로드는 Cloud Code에 파라미터로 전달됩니다. 자세한 내용은 Leaderboards의 초기화 이벤트를 참고하십시오.

배포 파일 생성

이 샘플에서는 UGS CLI를 사용하여 서비스별로 구성 파일을 배포하여 구현합니다. 사용 사례 샘플을 구현하려면 다음 파일을 설정해야 합니다.

```
COIN.ecc
```
: Economy 재화 구성을 포함합니다.
```
leaderboard.lb
```
: Leaderboards 구성을 포함합니다.
```
triggers-config.tr
```
: Triggers 구성을 포함합니다.
리더보드가 초기화될 때 상위 플레이어에게 게임 내 재화로 보상을 지급하는 로직을 정의하는 Cloud Code 모듈이나 스크립트입니다.

reward-top-players

라는 폴더를 만들어 모든 파일을 저장합니다. 한번에 모든 파일을 배포할 수 있습니다.

Economy 설정

게임 내 재화를 사용해 상위 플레이어에게 보상하려면 Economy에서 가상 재화를 만들어야 합니다. UGS CLI를 사용해 Economy config 파일을 만듭니다.


ugs economy currency new-file COIN.ecc

다음 콘텐츠를

COIN.ecc

파일에 추가합니다.


{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/economy/economy-currency.schema.json",  "initial": 0,  "name": "Coin"}

구성을 통해 가상 재화와

Coin

이름을 정의합니다. 파일 이름은 재화 ID와 상응합니다.

Leaderboards 설정

UGS CLI를 사용해 리더보드 구성 파일을 만듭니다.


ugs leaderboards new-file leaderboard.lb

다음 콘텐츠를

leaderboard.lb

파일에 추가합니다.


{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/leaderboards.schema.json",  "SortOrder": "asc",  "UpdateType": "keepBest",  "Name": "leaderboard"}

구성을 통해 오름차순으로 리더보드를 정의하며 최고 점수를 계속 표시합니다. 파일 이름은 리더보드 ID와 상응합니다.

Cloud Code 설정

리더보드가 초기화될 때 상위 플레이어에게 게임 내 재화로 보상을 지급하는 로직을 정의하려면 Cloud Code 모듈이나 스크립트를 생성해야 합니다.

Cloud Code C# 모듈

Economy 및 Leaderboards 클라이언트 SDK를 사용하여 Economy 서비스, Leaderboards 서비스와 상호 작용할 수 있습니다. UGS CLI를 사용하여 Cloud Code 모듈을 새로 만듭니다.


ugs cc m new-file RewardTopPlayers RewardTopPlayers

그런 다음 샘플 솔루션에 다음 콘텐츠를 추가합니다. 문자열 인수

leaderboardId

를 포함해 모듈 함수를 만듭니다.


using System;using System.Collections.Generic;using System.Threading.Tasks;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.Economy.Model;using Unity.Services.Leaderboards.Model;namespace RewardTopPlayers;public class RewardTopPlayers{    private const string CoinsKey = "COIN";    private const int Amount = 10;    private readonly ILogger<RewardTopPlayers> _logger;    public RewardTopPlayers(ILogger<RewardTopPlayers> logger)    {        _logger = logger;    }    [CloudCodeFunction("IssueReward")]    public async Task Reward(IExecutionContext ctx, IGameApiClient gameApiClient, string leaderboardId, string leaderboardVersionId)    {        var top5Players = await GetTop5(ctx, gameApiClient, leaderboardId, leaderboardVersionId);        foreach (var score in top5Players)        {            try            {                // Retrieve the player's configuration to ensure currency configuration is synced                var configResponse = await gameApiClient.EconomyConfiguration.GetPlayerConfigurationAsync(ctx, ctx.ServiceToken, ctx.ProjectId, score.PlayerId);                var res = await gameApiClient.EconomyCurrencies.IncrementPlayerCurrencyBalanceAsync(ctx, ctx.ServiceToken, ctx.ProjectId,                    score.PlayerId,                    CoinsKey, new CurrencyModifyBalanceRequest(amount: Amount), configResponse.Data.Metadata.ConfigAssignmentHash);                _logger.LogInformation("Incremented balance for playerId {playerId} by {amount}", score.PlayerId, Amount);            }            catch (ApiException e)            {                _logger.LogError(e, "Failed to increment balance for playerId {playerId}. Error: {Error}", score.PlayerId, e.Message);                throw;            }        }    }    public async Task<List<LeaderboardEntry>> GetTop5(IExecutionContext ctx, IGameApiClient gameApiClient, string leaderboardId, string leaderboardVersionId)    {        try        {            var results = await gameApiClient.Leaderboards.GetLeaderboardVersionScoresAsync(ctx, ctx.ServiceToken, new Guid(ctx.ProjectId),                leaderboardId, leaderboardVersionId, 0, 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());        }    }}

Cloud Code JavaScript 스크립트

Cloud Code 스크립트를 생성해서도 똑같은 결과물을 얻을 수 있습니다. UGS CLI를 사용하여 Cloud Code 스크립트를 새로 만듭니다.


ugs cc s new-file RewardTopPlayers.js

그런 다음 샘플 스크립트 파일에 다음 콘텐츠를 추가합니다.

JavaScript


const axios = require("axios");const { CurrenciesApi, ConfigurationApi } = require("@unity-services/economy-2.4");const { LeaderboardsApi } = require("@unity-services/leaderboards-1.1");module.exports = async ({ params, context, logger }) => {  // Get top 5 players from the Leaderboard  const leaderboardsApi = new LeaderboardsApi(context);  const cointAmount = 10;  let result;  try {    result = await leaderboardsApi.getLeaderboardVersionScores(context.projectId, params.leaderboardId, params.leaderboardVersionId, 0, 5);  } catch (err) {    logger.error("Failed to retrieve players from the leaderboard", { "error.message": err.message }, { "leaderboardId": params.leaderboardId });    throw err;  }  const currencyId = "COIN";  const currenciesApi = new CurrenciesApi(context);  const configApi = new ConfigurationApi(context);  // Reward currency to every player  const promises = result.data.results.map(async (score) => {    try {      // Retrieve the player config to get the configAssignmentHash.      // This is needed to ensure the currency is synced      var config = await configApi.getPlayerConfiguration({        playerId: score.playerId,        projectId: context.projectId,      });      await currenciesApi.incrementPlayerCurrencyBalance({        currencyId,        playerId: score.playerId,        projectId: context.projectId,        configAssignmentHash: config.data.metadata.configAssignmentHash,        currencyModifyBalanceRequest: { amount: cointAmount },      });    } catch (err) {      logger.error("Failed to increment currency for player", { "error.message": err.message }, { "affectedPlayerId": score.playerId });      return;    }  });  await Promise.all(promises);};

Triggers 설정

Cloud Code 리소스를 일정에 연결하려면 트리거를 생성합니다. 리더보드가 초기화되는 등의 이벤트가 발생하면 트리거가 Cloud Code 스크립트나 모듈을 실행합니다.


ugs tr new-file triggers-config.tr

Cloud Code 모듈을 생성한 경우, 다음 구성을 사용합니다.


{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",  "Configs": [    {      "Name": "reward-leaderboard",      "EventType": "com.unity.services.leaderboards.reset.v1",      "ActionUrn": "urn:ugs:cloud-code:RewardTopPlayers/IssueReward",      "ActionType": "cloud-code"    }  ]}

Cloud Code 스크립트를 생성한 경우, 다음 구성을 사용합니다.


{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",  "Configs": [    {      "Name": "reward-leaderboard",      "EventType": "com.unity.services.leaderboards.reset.v1",      "ActionUrn": "urn:ugs:cloud-code:RewardTopPlayers",      "ActionType": "cloud-code"    }  ]}

구성 파일 배포

reward-top-players

폴더에 다음 파일이 포함되어 있어야 합니다.

```
COIN.ecc
```
- Economy 재화 구성이 포함되어 있습니다.
```
leaderboard.lb
```
- Leaderboards 구성이 포함되어 있습니다.
```
triggers-config.tr
```
- Trigger 구성이 포함되어 있습니다.

다음 중 하나가 필요합니다.

```
RewardTopPlayers.sln
```
폴더 - Cloud Code 모듈이 포함되어 있습니다.
```
RewardTopPlayers.js
```
폴더 - Cloud Code 스크립트가 포함되어 있습니다.

UGS CLI를 사용하여 한번에 전부 배포할 수 있습니다.


ugs deploy .

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

다음 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 });  }};

이렇게 하면 리더보드에 점수를 추가하고 사용 사례 샘플을 테스트할 수 있습니다.

결과 확인

결과를 확인하려면 리더보드가 초기화되기 전에 리더보드에서 플레이어 ID를 적어 두어야 합니다.

Unity Cloud Dashboard로 이동합니다.
Products > Leaderboards를 선택합니다.
Overview 섹션을 선택합니다.
```
leaderboard
```
리더보드를 선택합니다.
Entries 탭을 선택합니다.
상위 플레이어 ID 중 하나를 기록해 둡니다.

그런 다음 리더보드를 초기화합니다.

Unity Cloud Dashboard로 이동합니다.
Products > Leaderboards를 선택합니다.
Overview 섹션을 선택합니다.
```
leaderboard
```
리더보드를 선택합니다.
Reset Leaderboard를 선택합니다.
Archive current scores를 활성화합니다.

아래 단계를 따라 플레이어가 보상으로 10코인을 받았는지 확인합니다.

Products > Player Management를 선택합니다.
검색 필드에 앞서 기록해 둔 플레이어 ID를 입력하고 Find Player를 선택합니다.
Economy > Currencies 섹션으로 이동합니다. 플레이어가 보상으로 10코인을 받았음을 확인할 수 있으면 성공적으로 완료된 것입니다.

게임 로직에 맞게 리더보드를 초기화하도록 구성하는 방법을 자세히 알아보려면 초기화를 참고하십시오.

기술 자료

엔진

서비스

Grow

산업 분야

지원

Cloud Code

Cloud Code

사용 사례 샘플: 시즌 종료 시 상위 플레이어에게 게임 내 재화로 보상 제공

필수 조건

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

UGS CLI 구성

reset 이벤트 확인

배포 파일 생성

Economy 설정

Leaderboards 설정

Cloud Code 설정

Cloud Code C# 모듈

Cloud Code JavaScript 스크립트

JavaScript

Triggers 설정

구성 파일 배포

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

JavaScript

결과 확인