使用の準備

Follow this workflow to set up Triggers and automate rewarding top players from Leaderboards.

読み終わるまでの所要時間 5 分

最終更新 1日前

このセクションでは、Triggers の使用を準備するために必要なすべてのステップについて説明します。以下のサンプルは、Triggers を使用し、Scheduler によって発行された 1 回限りのスケジュールイベントを使用して Cloud Save で Leaderboards の上位 5 人のプレイヤーにシーズントロフィーを授与する方法を示します。

ビデオウォークスルー

以下のビデオを見て、Unity Dashboard でトリガーを作成するステップのウォークスルーを確認してください。

無効なビデオリンク

リンクは有効な埋め込み YouTube リンクである必要があります。

詳細を見る

典型的なワークフロー

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 設定編集者)、Triggers Configuration Viewer (Triggers 設定閲覧者)、Scheduler Configuration Editor (Scheduler 設定編集者)、Scheduler Configuration Viewer (Scheduler 設定閲覧者)、Leaderboards Admin (Leaderboards 管理者) を選択します。
- Admin (管理者) ドロップダウンから Unity Environments Viewer (Unity 環境閲覧者) を選択します。
Save (保存) を選択します。
Add Key (キーの追加) を選択します。
base64 エンコードを使用して Key ID (キー ID) と Secret key (秘密鍵) をエンコードします。形式は "key_id:secret_key" です。この値をメモしておきます。

詳細については、Authentication を参照してください。

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.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 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 のデプロイを参照してください。

注

ノート: UGS CLI を使用してモジュールをデプロイする場合は、

Cloud Code Editor

の追加のサービスアカウントロールを忘れずに追加してください。

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 のデプロイを参照してください。

注

ノート: UGS CLI を使用してスクリプトをデプロイする場合は、追加のサービスアカウントロール (

Cloud Code Script Publisher

と

Cloud Code Editor

) を忘れずに追加してください。

イベントのスケジュール

Cloud Code スクリプトまたはモジュールを定義した後で、上位 5 人のプレイヤーがいつトロフィーを授与されるかを決定するスケジュールを作成できます。以下のサンプルでは、プレイヤーにシーズントロフィーを授与する 1 回限りのスケジュールを定義します。

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 スクリプトまたはモジュールを実行するトリガーが設定されました。

結果の検証

結果を検証するために、イベント発生の前後に上位プレイヤーを調べることができます。

Unity Dashboard に移動します。
Products (製品) > Leaderboards を選択します。
Overview (概要) セクションを選択します。
```
leaderboard
```
リーダーボードを選択します。
Entries (エントリー) タブを選択します。
上位プレイヤー ID の 1 つを書き留めます。

プレイヤーデータが更新されたことを検証するために、プレイヤーの Cloud Save データを確認できます。

Unity Dashboard から、Products (製品) > Player Management を選択します。
検索フィールドで、前に書き留めておいたプレイヤー ID を入力し、Find player (プレイヤーを検索) を選択します。
Cloud Save > Data (データ) セクションに移動します。
```
seasonal-trophy
```
キーと値
```
2023-08-28
```
が表示されています。

Cloud Code ログを調べて、Cloud Code スクリプトまたはモジュールが実行されたことを確認します。

Unity Dashboard で Cloud Code を開きます。
Logs (ログ) を選択します。

Logs (ログ) ページに、

SchedulerHelloWorld

モジュールまたはスクリプトからのログエントリーが表示されます。

ドキュメント

Development

User Acquisition

Monetization

産業

ドキュメント

Development

User Acquisition

Monetization

産業

Triggers

Triggers

使用の準備

ビデオウォークスルー

典型的なワークフロー

前提条件

サービスアカウントを使用した認証

UGS CLI の設定

Leaderboards の設定

任意: リーダーボードへのスコアの追加

JavaScript

Cloud Code の設定

Cloud Code C# モジュール

Cloud Code JavaScript スクリプト

JavaScript

イベントのスケジュール

トリガーの設定

結果の検証