Filters#

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.

Usage#

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.