Documentation

Support

Cloud Code

Use modules

Use scripts

Use Triggers

Open Unity Dashboard

Cloud Code

Get started

Follow this workflow to set up Triggers and automate rewarding top players from Leaderboards.
Read time 6 minutesLast updated 18 hours ago
This section describes all the steps you need to get started with Triggers. The sample below demonstrates how to use Triggers to reward players the top five players from Leaderboards with an seasonal trophy in Cloud Save using a one-time schedule event emitted by the Scheduler.

Video Walkthrough

Watch the video below to see a walkthrough of the steps to create a trigger in the Unity Dashboard.

Typical workflow

To get started with Triggers, follow these steps:
  1. Create a Cloud Code script or module to be run on event: Define game logic to execute when the event is fired.
  2. Schedule an event to change the state of a resource: Define when the event is fired.
  3. Configure a trigger to execute the Cloud Code module endpoint on event: Define which Cloud Code script or module is executed when the event is fired.
  4. Validate the result: Check that the Cloud Code script or module has been executed.

Prerequisites

The steps assume you have already created a Unity Gaming Services project in the Unity Dashboard. You must first create a service account with required access roles and configure the UGS CLI.

Authenticate using a Service Account

Before you can call the Scheduling and Triggers services, you must authenticate using a Service Account.
  1. Navigate to the Unity Dashboard.
  2. Select Administration > Service Accounts.
  3. Select the New button and enter a name and description for the Service Account.
  4. Select Create.
Add Product roles and create a key:
  1. Select Manage product roles.
  2. Add the following roles to the Service Account:
    • From the LiveOps dropdown, select Triggers Configuration Editor, Triggers Configuration Viewer, Scheduler Configuration Editor, Scheduler Configuration Viewer, and Leaderboards Admin.
    • From the Admin dropdown, select Unity Environments Viewer.
  3. Select Save.
  4. Select Add Key.
  5. Encode the Key ID and Secret key using base64 encoding. The format is “key_id:secret_key”. Note this value down.
For more information, refer to Authentication.

Configure the UGS CLI

Follow the steps below to get stated with the UGS CLI:
  1. Install the UGS CLI.
  2. Configure your Project ID and Environment as such:
    ugs config set project-id <your-project-id>

    ugs config set environment-name <your-environment-name>
  3. Authenticate using the Service account you created earlier. Refer to Get Authenticated.

Set up Leaderboards

To follow this sample, you should create a leaderboard. You can use the UGS CLI to deploy the following 
leaderboard.lb
file. It defines a leaderboard with ascending sort order and keeps the best score. Run the 
new-file
command to create a leaderboard configuration locally: 
ugs leaderboards new-file leaderboard
The file name corresponds to the leaderboard ID. Update the 
leaderboard.lb
file with the following configuration: 
{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/leaderboards.schema.json",  "SortOrder": "asc",  "UpdateType": "keepBest",  "Name": "leaderboard"}
Deploy the file using the UGS CLI tool: 
ugs deploy leaderboard.lb
Now that you have created a leaderboard, you can add scores to it.

Optional: Add scores to the leaderboard

You can run the following Cloud Code script to add scores to the leaderboard from the Unity Dashboard. Make sure to regenerate the Player ID token on every test run to generate a score for a new player.

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

Set up Cloud Code

To use Triggers, you should define a Cloud Code module or a Cloud Code script. The module or script is executed when a trigger is fired. The sample below integrates Leaderboards and Cloud Save with Cloud Code to reward the top five players from the leaderboard with a seasonal trophy.

Cloud Code C# module

Define a 
SchedulerHelloWorld
module with a function that takes in string arguments 
key
and 
value
. The module endpoint 
RewardPlayers
retrieves the top five players from the leaderboard and sets the Cloud Save data for each player with the specified key and value. 
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());        }    }}
Deploy the module. Refer to Deploying Hello World to learn how to deploy a module.

Cloud Code JavaScript script

You can achieve the same outcome by creating a Cloud Code script. Create a 
SchedulerHelloWorld
script with required string arguments 
key
and 
value
:

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);};
Publish the script. Refer to Deploying Hello World to learn how to deploy a script.

Schedule an event

After you have defined your Cloud Code script or module, you can create a schedule to determine when the top five players are rewarded with a trophy. The sample below defines a one-time schedule that grant players a seasonal trophy. Run the 
new-file
command to create a schedule configuration locally: 
ugs scheduler new-file schedule-config
Update the 
schedule-config.sched
file with the following configuration: 
{  "$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\"}"    }  }}
The 
payload
of the event carries the Cloud Code parameters that are passed to the Cloud Code script or module. Modify the 
schedule
field to change the date and time when the event is triggered. Deploy the configuration using the UGS CLI tool: 
ugs deploy schedule-config.sched
You should get a response similar to the following: 
Deployed:schedule-config.sched
Now you have a schedule that triggers an event at a specific time. However, the events are not yet connected to your Cloud Code script or module.

Configure a trigger

To connect your Cloud Code resource to the schedule, create a trigger. The trigger executes the Cloud Code module or script when the event is fired, for example, when the schedule is triggered. Run the 
new-file
command to create a trigger configuration locally: 
ugs triggers new-file triggers-config
If you created a Cloud Code module, update the 
triggers-config.tr
file with the following configuration: 
{  "$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"    }  ]}
If you created a Cloud Code script, update the 
triggers-config.tr
file with the following configuration: 
{  "$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"    }  ]}
Deploy the configuration using the UGS CLI tool: 
ugs deploy triggers-config.tr
You should get a response similar to the following: 
Deployed:triggers-config.tr
Now you have a trigger that executes your Cloud Code script or module when the event is fired.

Validate the result

To validate the result, you can inspect the top players before and after the event is fired.
  1. Navigate to the Unity Dashboard.
  2. Select Products > Leaderboards.
  3. Select the Overview section.
  4. Select the 
    leaderboard
    leaderboard.
  5. Select the Entries tab.
  6. Note down one of the top player IDs.
To validate that the player data has been updated, you can check the Cloud Save data for the player:
  1. From the Unity Dashboard, select Products > Player Management.
  2. In the search field, enter the player ID you noted down earlier and select Find Player.
  3. Navigate to the Cloud Save > Data section.
  4. You should find the 
    seasonal-trophy
    key with the value 
    2023-08-28
    .
You can also inspect the Cloud Code logs to check that the Cloud Code script or module has been executed.
  1. In the Unity Dashboard, open Cloud Code.
  2. Select Logs.
The Logs page shows log entries from the 
SchedulerHelloWorld
module or script.