Supported UGS events
Unity Gaming Services emit events that can provide you with information about player activity and game state. Use these events to trigger Cloud Code scripts or modules by creating a trigger configuration with the corresponding event type.
Refer to Trigger structure to check how an event is matched to the trigger configuration.
Note: This page covers events emitted from UGS. The Scheduler service also emits events you can use to trigger Cloud Code scripts or modules. Refer to Schedule events for guidelines on how to create schedule configurations.
Refer to the table below for a list of events emitted by Unity Gaming Services:
| Service | Event name | Emitted when |
|---|---|---|
| Authentication | Signed up | A player signs up to the Authentication service. A created player is also signed in, emitting a Signed in event. |
| Authentication | Signed in | A player signs into the Authentication service or refreshes their token. |
| Leaderboards | Reset | A leaderboard resets. |
| Leaderboards | Score submitted | A player submits a score to a leaderboard. |
| Cloud Save | Key saved | A Cloud Save key saves for a player or an entity. |
| Moderation | Player action | A player action is moderated. |
Authentication
The Authentication service provides events that can help you drive engagement for new players, provide sign-in bonuses, and reward returning players.
If you are authenticating players from Unity Runtime, the events are fired before the player authentication flow is completed.
Signed up
The signed up event is emitted when a player is created in the Authentication service. A created player is also signed in, emitting a Signed in event.
Event type: com.unity.services.player-auth.signed-up.v1
Refer to the table below for the event payload:
| Field | Description | Type |
|---|---|---|
playerId | An alphanumeric string used to identify returning and new players on different devices and external providers. | string |
providerId | The provider that was used to sign in. | string |
createdAt | A timestamp of when the player account was created in the RFC3339 format. | string |
Obtain the full player information by calling the Get Player endpoint with the playerId in the event.
Refer to Use case sample: Initialize newly signed-up players with default configuration values for an example of how to use this event.
Signed in
The signed in event is emitted when a player signs into the Authentication service, or refreshes their token.
Event type: com.unity.services.player-auth.signed-in.v1
Refer to the table below for the event payload:
| Field | Description | Type |
|---|---|---|
playerId | An alphanumeric string used to identify returning and new players on different devices and external providers. | string |
providerId | The provider that was used to sign in. | string |
createdAt | A timestamp of when the player account was created in the RFC3339 format. | string |
lastLoginAt | A timestamp of when the player last logged in in the RFC3339 format. | string |
previousLoginAt | A timestamp of the previous date the player logged in in the RFC3339 format. | string |
Obtain the full player information by calling the Get Player endpoint with the playerId in the event.
Leaderboards
The Leaderboard service provides events that can help you drive engagement.
Reset
The reset event is emitted when a leaderboard is reset.
Event type: com.unity.services.leaderboards.reset.v1
Refer to the table below for the event payload:
| Field | Description | Type |
|---|---|---|
leaderboardId | The leaderboard ID. | string |
leaderboardVersionId | The leaderboard version ID. | string |
You could use this event to reward top players on a leaderboard, or promote and demote players to different tiers.
Refer to Use case sample: Reward top players with in-game currency at the end of season for an example of how to use this event.
Score submitted
The Leaderboards service emits the score submitted event when a player submits a score to a leaderboard.
Event type: com.unity.services.leaderboards.score-submitted.v1
Refer to the table below for the event payload:
| Field | Description | Type |
|---|---|---|
leaderboardId | The leaderboard ID to which the score was submitted. | string |
updatedTime | The timestamp of the score submission in the RFC3339 format. | string |
playerId | The player ID. | string |
playerName | The player name. | string |
rank | The player's rank. | int |
score | The score submitted. | double |
tier | The player's tier. Empty string for non-tiered leaderboards. | string |
bucketId | The bucket ID. Empty string for non-bucketed leaderboards. | string |
You can use this event to drive engagement. For example, you can notify players when they are outperformed on a leaderboard, or reward players for reaching a certain rank.
Refer to Use case sample: Send a push message to the player whose score was beaten) for an example of how to use this event.
Cloud Save
The Cloud Save service provides an event that can help you drive engagement by notifying players when their item is updated.
Key saved
The key saved event is emitted when an item of a player or an entity in Cloud Save is saved.
Event type: com.unity.services.cloud-save.key-saved.v1
Refer to the table below for the event payload:
| Field | Description | Type |
|---|---|---|
id | The ID of the player or the entity associated with the event. Corresponds to the idType. | string |
idType | The item set ID type, custom or player. | string |
key | The key for the Cloud Save item. | string |
valueIncluded | Whether the value for the Cloud Save item is included in the event. Only values under 128b in size are returned. | bool |
value | The value for the Cloud Save item. Only values under 128b in size are returned. | object |
writeLock | The write lock for the Cloud Save item. | string |
accessClass | The access class of the item. This could be default, public, private or protected. | string |
modifiedDate | The item modified date in the RFC3339 format. | string |
You could use this event to drive engagement by notifying players when their item updates.
Moderation
The Moderation service provides events that can help you manage player behavior. You can define custom actions in Cloud Code to execute when a player action is moderated through the Moderation service. For example, you can define a custom action in Cloud Code to ban a player from a specific game mode when the event is emitted.
Note: Moderation type Cloud Code scripts enable a workflow to manage custom actions and provide you with a template to get started. By default, you can't run these scripts from a game client. For more information, refer to Script types.
Player action
The player action event is emitted when a player action is moderated.
Event type: com.unity.services.moderation.player-action-event.v1.
Refer to the table below for the event payload:
| Field | Description | Type |
|---|---|---|
playerActionId | The UUID of the player action related to the event. | string |
incidentId | The UUID of the moderation incident where this player action was applied. | string |
eventType | The type of event associated with the action. The value will be apply if the player action is being applied, or revoke if it is being revoked. | string |
actionName | The identifier of player action type that is being applied. | string |
actionDisplayName | The display name of player action type that is being applied. | string |
actionReason | The reason why a player action is being applied or revoked. | string |
actionComment | A comment provided by the moderator why the action is being applied or revoked. | string |
moderatorName | The moderator responsible for this player action. | string |
playerUasId | The uas ID of the affected player. | string |
playerName | The username of the affected player. If no player name can be retrieved, this value will be populated with the same value as the playerUasId. | string |
oneTimeAction | Defines whether this player action is a one-time action. | bool |
createdAt | A timestamp of when the player action was created in the RFC3339 format. | string |
expiresAt | A timestamp of when the player action will expire in the RFC3339 format. Can be null if the player action is a permanent, or a one-time action. | string or null |
deactivatedAt | A timestamp of when the player action was revoked in the RFC3339 format. Can be null if the player action has not been revoked. | string or null |
externalIds | A map of the player's external IDs. The key is the provider ID and the value is the external ID. | object |