Events

Understand how the Scheduler service and Unity Gaming Services produce events that Triggers service processes.

Read time 4 minutes

Last updated a day ago

The Scheduler service and Unity Gaming Services produce events. The events are then sent over to the Triggers service, which matches the events to a configuration, then executes the corresponding action—either a Cloud Code script or module, or a webhook HTTP request to an external URL.

Emitted events

The Scheduler service and Unity Gaming Services emit events that you can wire triggers to.

Emitted by	Customizable	Event payload	Emitted on	Use case
Unity Gaming Services	No	Predefined with event-specific payload and versioning	Change of player or game state	Use events emitted by UGS when you want to trigger Cloud Code scripts or modules as a response to a state change in your game or for a player.
Scheduler service	Yes	Created by user in a schedule configuration	On user defined set or recurring moment in time	Use events emitted by the Scheduler service when you want to control when a Cloud Code script or module is triggered.

Delivery semantics

By default, events have at-least-once delivery semantics. This means that all events are guaranteed to be processed once, but could potentially be processed multiple times in the event of a network issue. To avoid this, the recommended best practice is to create idempotent Cloud Code scripts and modules.

Event structure

All events contain an event type, payload version and carry a payload.

Field	Description	Example
`eventType`	The event type is a string that contains the emitting service, the event name and the payload version. The event type is also used in the trigger configuration create an association.	`com.unity.services.scheduler.example-event.v1`
`payloadVersion`	The payload version is an integer that denotes the version of the payload.	1
`payload`	The payload is a string that contains the event data. It is passed onto Cloud Code as script or module parameters.	`"{\"someBoolean\": true, \"someString\": \"something\"}"`

The event type differs slightly depending on whether it is emitted by the Scheduler service or by UGS.

Event type	Emitted by	Payload version	Payload
`com.unity.services.scheduler.example-event.v1`	Scheduler service	1	User-defined
`com.unity.services.player-auth.signed-up.v1`	Authentication service	1	Predefined
`com.unity.services.player-auth.signed-in.v1`	Authentication service	1	Predefined
`com.unity.services.cloud-save.key-saved.v1`	Cloud Save service	1	Predefined
`com.unity.servics.leaderboards.reset.v1`	Leaderboards service	1	Predefined
`com.unity.servics.leaderboards.score-submitted.v1`	Leaderboards service	1	Predefined

You can customize the events emitted by the Scheduler service by defining the event name, payload version and payload in the schedule configuration. The UGS emitted events have a different payload structure depending on the event type and cannot be customized. Refer to Supported UGS events for more information on what each event type returns.

Payload versioning

Payload versioning helps to avoid breaking changes. Every event includes payload versioning for the event payload. For example,

com.unity.services.player-auth.signed-up.v1

is an event type emitted by the Authentication service with a payload version of

. This allows different triggers to be set up for different payload versions of the same event.

Note

Payload versioning is supported for both scheduled events and events emitted by UGS. However, while you can customize the payload version and content for scheduled events, you cannot customize events emitted by UGS.

Scheduled event payload

Events emitted by the Scheduler service have a customizable payload. The payload is defined in the schedule configuration. For example, if you want to add a new field to the scheduled event payload, you can create a new version of the payload, and create a trigger to use the new version of the payload. A schedule configuration may look like this:


{"name" : "recurring-schedule","eventName": "example-event","type": "recurring","schedule": "0 0 * * *","payloadVersion": 1,"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"}

The sample above results in an event type of

com.unity.services.scheduler.example-event.v1

. You can set up a trigger for this event type:


{"name" : "example-trigger","eventType" : "com.unity.services.scheduler.example-event.v1","actionUrn" : "urn:ugs:cloud-code:my-script","actionType" : "cloud-code"}

If you want to add a new field to the event payload, you can create a new version of the payload, and create a trigger to use the new version of the payload.


{"name" : "recurring-schedule","eventName": "example-event","type": "recurring","schedule": "0 0 * * *","payloadVersion": 2,"payload": "{\"someBoolean\": true, \"someString\": \"something\", \"someNewField\": \"something else\"}"}

Which results in an event type of

com.unity.services.scheduler.example-event.v2

. This allows you wire a new trigger to the new event type.

Scheduled events

To emit a scheduled event, you must create a schedule configuration. Refer to Schedule events for more information. By deploying schedule configurations, you can create events that are emitted at a set or recurring moment in time. The following is a sample schedule configuration:


{"name" : "example-schedule","eventName": "example-event","type": "recurring","schedule": "0 0 * * *","payloadVersion": 1,"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"}

```
name
```
: The name of the schedule. It must be unique per project.
```
eventName
```
: The project-scoped name of the event, used to compose event type for a trigger.
```
type
```
: The type of the schedule. It must be
```
one-time
```
or
```
recurring
```
.
```
schedule
```
: Specifies when an event should be fired. It must be a timestamp or a cron expression, depending on the
```
type
```
field.
```
payloadVersion
```
: Integer denoting the version of the payload, used to compose event type for a trigger.
```
payload
```
: The
```
JSON
```
object that is used as the event payload to forward parameters to Cloud Code script or module.

Note

Limits apply. Refer to Limits for more information.

One-time schedule

A one-time schedule is a single event that is executed at a specific time. It may look like this:


{"name" : "one-time-schedule","eventName": "example-event","type": "one-time","schedule": "2020-01-01T00:00:00Z","payloadVersion": 1,"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"}

The

schedule

field is a RFC3339 timestamp that defines when the event is triggered.

Note

The timestamp must be declared in the future.

Recurring schedule

A recurring schedule is a series of events that is executed at a specific time interval. It may look like this:


{"name" : "recurring-schedule","eventName": "example-event","type": "recurring","schedule": "0 0 * * *","payloadVersion": 1,"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"}

The

schedule

field is a cron expression that defines when the event is triggered.

Overlap with Triggers

Refer to Triggers structure to check how events are tied to triggers.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Triggers

Triggers

Events

Emitted events

Emitted by

Customizable

Event payload

Emitted on

Use case

Delivery semantics

Event structure

Field

Description

Example

Event type

Emitted by

Payload version

Payload

Payload versioning

Scheduled event payload

Scheduled events

One-time schedule

Recurring schedule

Overlap with Triggers