Supported UGS events

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

Read time 6 minutes

Last updated a day ago

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.

Each event can declare a scope type, which is relevant if you want to trigger a Cloud Code module. Refer to the scoped trigger events section specifically to understand scope type compatibility between events and Cloud Code module endpoints.

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 as it is stored in the leaderboard, which may differ from the submitted value based on the leaderboard's update strategy.	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

Supported UGS events

Service

Event name

Emitted when

Authentication

Signed up

Field

Description

Type

Signed in

Field

Description

Type

Leaderboards

Reset

Field

Description

Type

Score submitted

Field

Description

Type

Cloud Save

Key saved

Field

Description

Type

Moderation

Player action

Field

Description

Type