Filter Expressions #

Filters are a powerful tool for segmenting your player base into distinct audiences based upon any desired criteria using the default, computed, and custom properties.

Filter expressions can use any combination of the following:

  • String - A string of characters enclosed in double or single quotes. For example "hello world".
  • Number - A number, for example 123. Digit separators can be used to improve readability. For example 1_000_000.
  • Boolean - A boolean value, either true or false.
  • Array - A list of values enclosed in square brackets. For example [1, 2, 3].
  • Map - A list of key-value pairs enclosed in curly braces. For example {"key": "value"}.
  • Nil - The absence of a value, represented by the keyword nil.

Operators #

The following operators are available for use in filter expressions:

Arithmetic #

OperatorDescription
+Addition
-Subtraction
*Multiplication
/Division
%Modulus
**Exponentiation

Comparison #

OperatorDescription
==Equal to
!=Not equal to
<Less than
<=Less than or equal to
>Greater than
>=Greater than or equal to

Logical #

OperatorDescription
&& or andAND
|| or orOR
! or notNOT

String #

OperatorDescriptionExample
+ConcatenationPropertiesCustom("firstName", "John") + " " + PropertiesCustom("lastName", "Doe")
matchesRegular expression matchProperties("countryCode", "US") matches "^(US|CA|GB)$"
containsString contains substringProperties("email", "") contains "heroic"
startsWithString starts with substringPropertiesCustom("installVersion", "1.0.0") startsWith "2.0.0"
endsWithString ends with substringProperties("email", "") endsWith "@heroiclabs.com"

Functions #

Functions can be used in your filter expressions to perform more complex operations, and are called using the () syntax. The following functions are available:

FunctionDescription
Now(): numberReturns the current time in seconds since epoch.
Duration(string): numberReturns a duration in seconds.
Properties(string, object): objectReturns the properties of an identity, or default value.
PropertiesComputed(string, object): objectReturns the computed properties of an identity, or default value.
PropertiesCustom(string, object): objectReturns the custom properties of an identity, or default value.
SemverMatch(string, string): booleanReturns true if the version matches the provided version / version range.

SemverMatch expressions #

For the SemverMatch function, the following operators are supported:

OperatorDescription
==Equal to
!=Not equal to
<Less than
<=Less than or equal to
>Greater than
>=Greater than or equal to
(empty space)AND, can be used to link multiple ranges in one expression
||OR, can be used to link multiple ranges in one expression

Examples #

The following examples demonstrate the use of filter expressions to create custom audiences.

AudienceFilter ExpressionDescription
Recently ActiveNow() - updateTime < Duration("30d")All identities that have been updated in the last 30 days.
New PlayersNow() - createTime <= Duration("2d")All identities that have been created in the last 2 days.
Existing PlayersNow() - updateTime < Duration("2d")All identities with a play session in the last 2 days.
Dormant PlayersNow() - updateTime > Duration("7d") and Now() - updateTime < Duration("14d")All identities with a last play session between 7 and 14 days ago.
Churned PlayersNow() - updateTime >= Duration("14d")All identities with a last play session more than 14 days ago, an so have likely churned.
Veteran PlayersPropertiesComputed("sessionStartCount", 0) >= 100All identities with 100 or more play sessions.
All SpendersPropertiesComputed("purchaseCompletedCount", 0) > 0All identities that have made at least one purchase.
Non-SpendersPropertiesComputed("purchaseCompletedCount", 0) < 1All identities that have not made any purchases.
Recent SpendersNow() - PropertiesComputed("purchaseCompletedSeenLast", 0) < Duration("7d") and PropertiesComputed("purchaseCompletedCount", 0) > 0All identities that have made a purchase in the last 7 days.
Level 10+PropertiesComputed("levelCompleted", 0) >= 10All identities that have reached level 10 or higher. Assumes a levelCompleted event has been created.
Client VersionsSemverMatch(">1.0.0 <2.0.0", PropertiesCustom("clientVersion", "1.0.0"))All clients greater than version 1.0.0 and less than 2.0.0.