Trigger structure

Understand the structure of a trigger configuration that defines what to invoke when an event fires.

Read time 5 minutes

Last updated 12 days ago

A trigger configuration defines what should be invoked when an event is fired. The structure differs depending on whether the action is Cloud Code or a webhook.

Important

You can't edit a trigger after you create it. To change a trigger, delete it and create a new one.

Cloud Code trigger

A Cloud Code trigger invokes a script or module when the event fires. It uses

actionType: cloud-code

and an

actionUrn

that identifies the script or module.


{  "name" : "example-trigger",  "eventType" : "com.unity.services.{{SERVICE_NAME}}.{{EVENT_NAME}}.v{{EVENT_VERSION}}",  "actionUrn" : "urn:ugs:cloud-code:{{SCRIPT}}",  "actionType" : "cloud-code",  "filter": "data['parameter'] == 'value'"}

```
name
```
: The name of the trigger. It must be unique per project.
```
eventType
```
: Matches the trigger to an event. It is composed of the
```
eventName
```
and
```
eventVersion
```
fields, corresponding to the
```
eventName
```
and
```
payloadVersion
```
fields in the event configuration.
```
actionUrn
```
: What is invoked when the trigger fires. For example,
```
urn:ugs:cloud-code:TestScript
```
invokes the
```
TestScript
```
Cloud Code script, or
```
urn:ugs:cloud-code:TestModule/TestFunction
```
invokes the
```
TestFunction
```
function in the
```
TestModule
```
Cloud Code module.
```
actionType
```
: Set to
```
cloud-code
```
for Cloud Code triggers.
```
filter
```
: Optional. A condition that must be met for the trigger to fire. For more information, refer to Filters.

Scoped trigger events

Each Cloud Code event and module can declare a scope type, such as

Player

, that indicates the context in which the action runs. To configure a trigger with a scoped module action, the scope types need to be compatible. The following rules apply when you select a module endpoint:

If the endpoint has no scope type, you can use the endpoint regardless of the event's scope type.
If the endpoint declares a scope type, the event scope type must be the same.

Event	Service	Scope type
`signed-up`	Authentication	`Player`
`signed-in`	Authentication	`Player`
`key-saved`	Cloud Save	`Player`
`score-submitted`	Leaderboards	`Player`
`reset`	Leaderboards	None
`player-action`	Moderation	`Player`

For more information about scoped Cloud Code events, refer to Stateful Cloud Code.

Webhook trigger

A webhook trigger sends an HTTP request to an external URL when the event fires. The webhook trigger configuration requires the following fields:

```
actionType: webhook
```
```
actionUrn: urn:ugs:webhook
```
```
webhook
```
: An object containing the request details:
- ```
url
```
  (Required): The destination URL.
- ```
method
```
  (Optional): The HTTP method (for example
```
POST
```
  or
```
GET
```
  ). Defaults to
```
POST
```
  .
- ```
headers
```
  (Optional): Custom key-value pairs for the request.
- ```
payloadTemplate
```
  (Conditional): The request body template. Required for all content types except
```
application/json
```
  . For
```
application/json
```
  , you may omit it to forward the full event payload as-is.

You can inspect and replay failed webhook deliveries from the dead letter queue.


{  "name" : "example-webhook-trigger",  "eventType" : "com.unity.services.leaderboards.score-submitted.v1",  "actionUrn" : "urn:ugs:webhook",  "actionType" : "webhook",  "webhook": {    "url": "https://example.com/events",    "method": "POST",    "headers": { "Content-Type": "application/json" },    "payloadTemplate": "{\"event\": \"score-submitted\", \"data\": {{.}}}"  }}

For full webhook configuration and template syntax, refer to Webhooks.

Overlap with events

Triggers are associated with events. When an event is fired, the associated trigger is invoked. The event and the trigger must share the same

eventName

and

payloadVersion

configuration.

Note

The

eventType

maps an event to a trigger.

Scheduled events

Given the following schedule configuration:


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

And the following trigger configuration:


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

You can associate the trigger with the event type by setting the

eventType

field in the trigger configuration to the

eventName

and

payloadVersion

fields in the schedule configuration.

When the schedule configuration is deployed, the schedule is triggered at the specified time, sending an event to the Triggers service, which in turn invokes the associated Cloud Code resource.

UGS events

Given you want to associate a trigger with an event type from UGS, you need to specify the event type in the trigger configuration.

For example, if you want to fire a trigger on the Authentication: Signed Up event, you can create the following trigger configuration:


{  "name" : "example-trigger",  "eventType" : "com.unity.services.player-auth.signed-up.v1",  "actionUrn" : "urn:ugs:cloud-code:my-script",  "actionType" : "cloud-code"}

Every time a user signs up, the trigger is fired, invoking the

my-script

Cloud Code script.

Multiple triggers per event type

You can associate the same event type with multiple triggers, so a single event, such as one scheduled event, can invoke many actions at once.

Note

The current limit for the number of triggers per event type is 32.

The relationship also works the other way: an event type can have no triggers at all. A schedule that you create before any trigger consumes it, or whose triggers you later delete, still fires. There's just nothing listening for its event until you add a matching trigger.

For example, you can create two triggers that invoke when a user signs up.

The first trigger invokes the

add-cloud-save-data

script to add a Cloud Save data entry for the authenticated user:


{  "name" : "auth-cloud-save",  "eventType" : "com.unity.services.player-auth.signed-up.v1",  "actionUrn" : "urn:ugs:cloud-code:add-cloud-save-data",  "actionType" : "cloud-code"}

The second trigger invokes the

add-economy-items

endpoint from

Economy

module to add a virtual item to the authenticated user:


{  "name" : "auth-economy",  "eventType" : "com.unity.services.player-auth.signed-up.v1",  "actionUrn" : "urn:ugs:cloud-code:Economy/add-economy-items",  "actionType" : "cloud-code"}

Every time a user signs up, both triggers fire and invoke the associated Cloud Code resources.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Triggers

Triggers Admin API

Scheduler Admin API

Triggers

Trigger structure

Cloud Code trigger

Scoped trigger events

Event

Service

Scope type

Webhook trigger

Overlap with events

Scheduled events

UGS events

Multiple triggers per event type

Additional resources