开始使用

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

阅读时间11 分钟

最后更新于 5 个月前

本节介绍开始使用 Triggers 所需的所有步骤。

以下示例演示了如何使用 Triggers 在 Cloud Save 中根据 Scheduler 发出的一次性计划事件向 Leaderboards 排行榜前五名玩家授予相应的赛季奖杯。

视频演示

观看下面的视频，了解在 Unity Dashboard（Unity 后台）中创建触发器的具体步骤。

无效的视频链接

链接必须是有效的嵌入式 YouTube 链接。

了解详情

典型工作流程

要开始使用 Triggers，请执行以下步骤：

创建一个要在事件发生时运行的 Cloud Code 脚本或模块：定义触发事件时要执行的游戏逻辑。
计划一个事件以更改资源的状态：定义触发事件的时间。
配置一个触发器以在事件发生时执行 Cloud Code 模块终端：定义触发事件时要执行的 Cloud Code 脚本或模块。
验证结果：检查是否已执行 Cloud Code 脚本或模块。

注意

注意：还可以将 Triggers 用于其他服务发出的事件。如需了解更多信息，请参阅事件一节。

先决条件

以下步骤假定您已经在 Unity Dashboard 中创建了 Unity Gaming Services（Unity 游戏服务）项目。

必须首先创建具有所需访问角色的服务帐户，并配置 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”。请记下此值。

如需了解更多信息，请参阅身份验证。

配置 UGS CLI

按照以下步骤操作以开始使用 UGS CLI：

安装 UGS CLI。

按如下方式配置 Project 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 集成在一起，向排行榜前五名的玩家授予赛季奖杯。

Cloud Code C# 模块

定义一个

SchedulerHelloWorld

模块，其中包含一个接受字符串参数

key

和

value

的函数。

模块终端

RewardPlayers

从排行榜中获取前五名玩家，并使用指定的键和值为每个玩家设置 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 脚本或模块后，您可以创建一个计划来确定向前五名玩家授予奖杯的时间。

以下示例定义了一个向玩家授予赛季奖杯的一次性计划。

运行

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 之一。

要验证玩家数据是否已更新，可以检查玩家的 Cloud Save 数据：

在 Unity Dashboard 中，选择 Products（产品）> Player Management（玩家管理）。
在搜索字段中，输入您先前记下的玩家 ID，然后选择 Find Player（查找玩家）。
导航到 Cloud Save > Data（数据） 部分。
您应该会发现值为
```
2023-08-28
```
的
```
seasonal-trophy
```
键。

还可以检查 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

计划事件

配置触发器

验证结果