Documentation

Support

Cloud Code

Use modules

Use scripts

Use Triggers

Open Unity Dashboard

Cloud Code

Filters

Use filters to determine whether to execute a trigger and avoid unnecessary trigger execution.
Read time 2 minutesLast updated 18 hours ago
You can use filters to determine whether to execute a trigger and avoid the unnecessary execution of triggers. You can define the filters in the 
filter
field of a trigger's configuration. You define filters in the 
filter
field of a trigger's configuration. The value of this field is a CEL expression that evaluates to a boolean value. If the expression evaluates to 
true
, the trigger will be executed. For example, the trigger configuration below is only executes when the leaderboard with a 
my-leaderboard
leaderboard ID resets. 
{  "name": "reset-another-leaderboard",  "eventType": "com.unity.services.leaderboards.reset.v1",  "actionType": "cloud-code",  "actionUrn": "urn:ugs:cloud-code:test-script",  "filter": "data['leaderboardId'] == 'my-leaderboard'"}
Triggers use the event payload as the input. The event payload is a JSON object that contains the data relevant to the event. For example, the payload for the 
com.unity.services.leaderboards.reset.v1
event looks like the following: 
{  "leaderboardId": "my-leaderboard",  "leaderboardVersionId": "20230213175322850781977"}

CEL syntax

You need to write filters in CEL (Common Expression Language), an expression language that Google Cloud products use. For more information on CEL, refer to the Language Definition. The samples below show some common CEL expressions that you can use in filters.

Equality

You can set a filter to be true when a field is equal to a specific value. These filters allow you to ensure that a passed-in parameter is a specific value. For example, you can use the following filter to check if the value of 
leaderboardId
is 
my-leaderboard
: 
data['leaderboardId'] == 'my-leaderboard'

Regular expressions

You can use regular expressions to match a field against a pattern. For instance, you can use the following filter to check if the value of 
leaderboardId
starts with 
tiered-leaderboard#
: 
data['leaderboardId'].matches('^tiered-leaderboard#.*')

Nested fields

You can use filters with nested fields. For example, your script or module parameter might look like the following: 
{  "inventory": {    "primaryWeapon": "sword",    "secondaryWeapon": "bow"  }}
You can then use the following filter to check if the value of 
inventory.primaryWeapon
is 
sword
: 
data['inventory']['primaryWeapon'] == 'sword'

Logical operators

You can use logical operators to combine multiple expressions. For example, you can use the following filter to determine when to issue a quest to a player. You issue the quest when the player reaches level 5, or when the player completes the 
collectWood
quest and the current quest is 
buildFence
: 
(data['currentQuest'] == 'buildFence' && data['lastQuest'] == 'collectWood') || data['level'] == 5

Type mismatch

If the type of the value in the event payload doesn't match the type of the value in the filter, the filter returns an error message in logs, and the trigger isn't executed. For example, the following filter checks if the Cloud Save event payload contains a 
value
field that is greater than 5: 
data['value'] > 5
If the value of 
data['value']
is a 
string
, the filter doesn't work as expected. This filter is only evaluated if the 
value
is a number in the event payload.

Type casting

You can cast the type of a value in the event payload to a different type. This can help you avoid type mismatch errors. For example, if you pass in a string value that is a number, you can cast it to a number, and still use it in a filter that expects a number. 
int(data['value']) > 5
However, if the value of 
data['value']
is a string that isn't a number, the filter returns an error message in logs, and the trigger isn't executed. To check available types you can cast to, refer to List of Standard Definitions.