Events#

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.

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.

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

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 1. This allows different triggers to be set up for different payload versions of the same event.

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.

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.

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.