Filters

Use filters to determine whether to execute a trigger and avoid unnecessary trigger execution.

Read time 2 minutes

Last updated a day 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

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

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.

Documentation

Development

User Acquisition

Monetization

Industry