Heroic Labs Documentation

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 #

OperatorDescription
+Concatenation
matchesRegular expression match
containsString contains substring
startsWithString starts with substring
endsWithString ends with substring

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.
createTime(): numberReturns the creation time of an identity.
updateTime(): numberReturns the last update time of an identity.

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.