# 支持的 UGS 事件

> Learn about the events emitted by Unity Gaming Services that you can use to trigger Cloud Code scripts or modules.

Unity Gaming Services（Unity 游戏服务）会发出事件来提供有关玩家活动和游戏状态的信息。根据这些事件可以创建具有相应事件类型的触发器配置来触发 Cloud Code 脚本或模块。

请参阅[触发器结构](../tutorials/define-triggers/trigger-structure)以查看事件与触发器配置的匹配方式。

> **Note:**
>
> **注意：** 本页介绍从 UGS 发出的事件。Scheduler 服务也会发出可用于触发 Cloud Code 脚本或模块的事件。请参阅[计划事件](../tutorials/schedule-events/rest-api)以查看有关如何创建计划配置的指南。

请参阅下表以查看 Unity Gaming Services（Unity 游戏服务）发出的事件列表：

| 服务             | 事件名称                     | 发出时间                                                   |
| -------------- | ------------------------ | ------------------------------------------------------ |
| 身份验证           | [注册](#signed-up)         | 玩家注册 Authentication 服务。创建的玩家也已登录，发出[登录](#signed-in)事件。 |
| 身份验证           | [登录](#signed-in)         | 玩家登录 Authentication 服务或刷新其令牌。                          |
| Leaderboards   | [重置](#reset)             | 排行榜重置。                                                 |
| Leaderboards   | [提交分数](#score-submitted) | 玩家将分数提交到排行榜。                                           |
| Cloud Save     | [保存键](#key-saved)        | 为玩家或实体保存 Cloud Save 键。                                 |
| Moderation（审核） | [玩家操作](#player-action)   | 玩家操作被审核。                                               |

## 身份验证##authentication

[Authentication 服务](/authentication.md)提供的事件可帮助您提高新玩家的参与度、提供登录奖励以及奖励回归玩家。

如果您从 Unity Runtime 对玩家进行身份验证，则会在玩家身份验证流程完成之前触发事件。

### 注册##signed-up

在 Authentication 服务中创建玩家时发出已注册事件。创建的玩家也已登录，发出[登录](#signed-in)事件。

事件类型：`com.unity.services.player-auth.signed-up.v1`

请参阅下表以了解事件有效负载：

| 字段           | 描述                                 | 类型  |
| ------------ | ---------------------------------- | --- |
| `playerId`   | 一个字母数字字符串，用于识别不同设备和外部提供商的回归玩家和新玩家。 | 字符串 |
| `providerId` | 登录时使用的提供商。                         | 字符串 |
| `createdAt`  | 创建玩家帐户的时间戳，以 RFC3339 格式表示。         | 字符串 |

在事件中使用 `playerId` 调用 [Get Player 终端](https://services.docs.unity.com/player-auth/v1/#tag/Player-authentication/operation/getplayer)来获取完整的玩家信息。

请参阅[使用示例：使用默认配置值初始化新注册的玩家](../tutorials/use-cases/initialize-new-players)，查看关于如何使用此事件的示例。

### 登录##signed-in

在玩家登录 Authentication 服务或刷新其令牌时发出已登录事件。

事件类型：`com.unity.services.player-auth.signed-in.v1`

请参阅下表以了解事件有效负载：

| 字段                | 描述                                 | 类型  |
| ----------------- | ---------------------------------- | --- |
| `playerId`        | 一个字母数字字符串，用于识别不同设备和外部提供商的回归玩家和新玩家。 | 字符串 |
| `providerId`      | 登录时使用的提供商。                         | 字符串 |
| `createdAt`       | 创建玩家帐户的时间戳，以 RFC3339 格式表示。         | 字符串 |
| `lastLoginAt`     | 玩家上次登录的时间戳，以 RFC3339 格式表示。         | 字符串 |
| `previousLoginAt` | 玩家登录的上一个日期的时间戳，以 RFC3339 格式表示。     | 字符串 |

在事件中使用 `playerId` 调用 [Get Player 终端](https://services.docs.unity.com/player-auth/v1/#tag/Player-authentication/operation/getplayer)来获取完整的玩家信息。

## Leaderboards##leaderboards

[Leaderboards 服务](/leaderboards.md)提供的事件可帮助您提高玩家参与度。

### 重置##reset

在排行榜重置时发出已重置事件。

事件类型：`com.unity.services.leaderboards.reset.v1`

请参阅下表以了解事件有效负载：

| 字段                     | 描述        | 类型  |
| ---------------------- | --------- | --- |
| `leaderboardId`        | 排行榜 ID。   | 字符串 |
| `leaderboardVersionId` | 排行榜版本 ID。 | 字符串 |

您可以使用此事件来奖励排行榜上排名靠前的玩家，或将玩家升级和降级到不同的等级。

请参阅[使用示例：在赛季结束时用游戏内货币奖励排名靠前的玩家](../tutorials/use-cases/reward-top-players)，查看关于如何使用此事件的示例。

### 提交分数##score-submitted

当玩家将分数提交到排行榜时，Leaderboards 服务会发出提交分数事件。

事件类型：`com.unity.services.leaderboards.score-submitted.v1`

请参阅下表以了解事件有效负载：

| 字段              | 描述                       | 类型     |
| --------------- | ------------------------ | ------ |
| `leaderboardId` | 分数提交到的排行榜 ID。            | 字符串    |
| `updatedTime`   | 提交分数的时间戳，以 RFC3339 格式表示。 | 字符串    |
| `playerId`      | 玩家 ID。                   | 字符串    |
| `playerName`    | 玩家名称。                    | 字符串    |
| `rank`          | 玩家的排名。                   | 整型     |
| `score`         | 提交的分数。                   | double |
| `tier`          | 玩家的等级。未分级的排行榜为空字符串。      | 字符串    |
| `bucketId`      | 存储桶 ID。未分组的排行榜为空字符串。     | 字符串    |

您可以使用此事件来提高玩家参与度。例如，您可以在玩家处于排行榜上的前列时通知他们，或者奖励达到特定排名的玩家。

请参阅[使用示例：向分数被超过的玩家发送推送消息](../tutorials/use-cases/higher-score-message)，查看关于如何使用此事件的示例。

## Cloud Save##cloud-save

[Cloud Save](/cloud-save.md) 服务提供的一个事件可以在玩家的项更新时通知玩家以帮助您提高玩家参与度。

### 保存键##key-saved

在 Cloud Save 中保存玩家或实体的项时发出保存键事件。

事件类型：`com.unity.services.cloud-save.key-saved.v1`

请参阅下表以了解事件有效负载：

| 字段              | 描述                                                     | 类型   |
| --------------- | ------------------------------------------------------ | ---- |
| `id`            | 与事件关联的玩家或实体的 ID。对应于 `idType`。                          | 字符串  |
| `idType`        | 项设置 ID 类型，`custom` 或 `player`。                         | 字符串  |
| `key`           | Cloud Save 项的键。                                        | 字符串  |
| `valueIncluded` | Cloud Save 项的值是否包含在事件中。仅返回大小小于 128b 的值。                | bool |
| `value`         | Cloud Save 项的值。仅返回大小小于 128b 的值。                        | 对象   |
| `writeLock`     | Cloud Save 项的写锁定。                                      | 字符串  |
| `accessClass`   | 项的访问类。这可以是 `default`、`public`、`private` 或 `protected`。 | 字符串  |
| `modifiedDate`  | 项的修改日期，以 RFC3339 格式表示。                                 | 字符串  |

您可以使用此事件在玩家的项更新时通知玩家以提高玩家参与度。

## Moderation（审核）##moderation

[Moderation 服务](/safe-text/overview.md)提供可帮助您管理玩家行为的事件。您可以在 Cloud Code 中定义自定义操作，当通过 Moderation 服务审核玩家操作时会执行这些自定义操作。例如，您可以在 Cloud Code 中定义一个自定义操作，以便在发出事件时禁止玩家进入特定的游戏模式。

> **Note:**
>
> **注意：** Moderation 类型的 Cloud Code 脚本支持通过工作流程[管理自定义操作](/safe-text/custom-actions.md)并为您提供一个入门模板。默认情况下，无法从游戏客户端运行这些脚本。如需了解更多信息，请参阅[脚本类型](/cloud-code/scripts/how-to-guides/script-types.md)。

### 玩家操作##player-action

审核玩家操作时会发出玩家操作事件。

事件类型：`com.unity.services.moderation.player-action-event.v1`。

请参阅下表以了解事件有效负载：

| 字段                  | 描述                                                         | 类型        |
| ------------------- | ---------------------------------------------------------- | --------- |
| `playerActionId`    | 与事件相关的玩家操作的 UUID。                                          | 字符串       |
| `incidentId`        | 应用了此玩家操作的审核事件的 UUID。                                       | 字符串       |
| `eventType`         | 与操作关联的事件类型。如果玩家操作正在应用，则值为 `apply`；如果玩家操作正在撤销，则值为 `revoke`。 | 字符串       |
| `actionName`        | 正在应用的玩家操作类型的标识符。                                           | 字符串       |
| `actionDisplayName` | 正在应用的玩家操作类型的显示名称。                                          | 字符串       |
| `actionReason`      | 玩家操作被应用或撤销的原因。                                             | 字符串       |
| `actionComment`     | 仲裁者提供的注释，说明应用或撤销该操作的原因。                                    | 字符串       |
| `moderatorName`     | 负责此玩家操作的仲裁者。                                               | 字符串       |
| `playerUasId`       | 受影响玩家的 UAS ID。                                             | 字符串       |
| `playerName`        | 受影响玩家的用户名。如果无法获取玩家名称，该值将填充与 `playerUasId` 相同的值。            | 字符串       |
| `oneTimeAction`     | 定义此玩家操作是否是一次性操作。                                           | bool      |
| `createdAt`         | 创建玩家操作的时间戳，以 RFC3339 格式表示。                                 | 字符串       |
| `expiresAt`         | 玩家操作到期的时间戳，以 RFC3339 格式表示。如果玩家操作是永久性或一次性操作，可以为 null。       | 字符串或 null |
| `deactivatedAt`     | 撤销玩家操作的时间戳，以 RFC3339 格式表示。如果玩家操作尚未被撤销，可以为 null。            | 字符串或 null |
| `externalIds`       | 玩家外部 ID 的映射。键为提供商 ID，值为外部 ID。                              | 对象        |