Events
Understand how the Scheduler service and Unity Gaming Services produce events that Triggers service processes.
Read time 4 minutesLast updated 18 hours 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 Cloud Code script or module.
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 |
|---|---|---|
| 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. | |
| The payload version is an integer that denotes the version of the payload. | 1 |
| The payload is a string that contains the event data. It is passed onto Cloud Code as script or module parameters. | |
Event type | Emitted by | Payload version | Payload |
|---|---|---|---|
| Scheduler service | 1 | User-defined |
| Authentication service | 1 | Predefined |
| Authentication service | 1 | Predefined |
| Cloud Save service | 1 | Predefined |
| Leaderboards service | 1 | Predefined |
| Leaderboards service | 1 | Predefined |
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.v11Note
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:The sample above results in an event type of{"name" : "recurring-schedule","eventName": "example-event","type": "recurring","schedule": "0 0 * * *","payloadVersion": 1,"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"}
com.unity.services.scheduler.example-event.v1If 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" : "example-trigger","eventType" : "com.unity.services.scheduler.example-event.v1","actionUrn" : "urn:ugs:cloud-code:my-script","actionType" : "cloud-code"}
Which results in an event type of{"name" : "recurring-schedule","eventName": "example-event","type": "recurring","schedule": "0 0 * * *","payloadVersion": 2,"payload": "{\"someBoolean\": true, \"someString\": \"something\", \"someNewField\": \"something else\"}"}
com.unity.services.scheduler.example-event.v2Scheduled 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\"}"}
- : The name of the schedule. It must be unique per project.
name - : The project-scoped name of the event, used to compose event type for a trigger.
eventName - : The type of the schedule. It must be
typeorone-time.recurring - : Specifies when an event should be fired. It must be a timestamp or a cron expression, depending on the
schedulefield.type - : Integer denoting the version of the payload, used to compose event type for a trigger.
payloadVersion - : The
payloadobject that is used as the event payload to forward parameters to Cloud Code script or module.JSON
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:The{"name" : "one-time-schedule","eventName": "example-event","type": "one-time","schedule": "2020-01-01T00:00:00Z","payloadVersion": 1,"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"}
scheduleNote
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:The{"name" : "recurring-schedule","eventName": "example-event","type": "recurring","schedule": "0 0 * * *","payloadVersion": 1,"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"}
schedule