Criteria Conditions

Search…
Criteria Conditions
Description
Conditions are common to both criteria and criteria groups. They can be used to filter a player's activities before applying any criteria rules.
Criteria condition administration is currently only supported via API. We hope to have our admin UI updated to support criteria condition administration in the near future.
Examples
In order to help illustrate the difference between using criteria conditions and not using them, let's consider a simple example.
Let's say that you have an achievement, "The Closer". This achievement has a single criterion, "Closed 10 Sales", which is tied to your "Close a Sale" action and has rule, gte:sum,10.
Without any criteria conditions applied, each time you report player activity for action, "Close a Sale", r4nkt will look to see if the player has closed ten or more sales. If so, then the achievement's lone criterion will be met and the player will earn a badge for "The Closer".
Now, you can create another achievement called "Last Minute Super Closer" that has the same criterion, "Closed 10 Sales". You can give the achievement's criteria group the following condition: dayOfMonth:last. Now, whenever you report player activity for action, "Close a Sale", r4nkt will find all of the "Close a Sale" activities that a player has reported on the last day of any month. The sum of each activity's amount is taken and, if it meets or exceeds 10, then the achievement's lone criterion will be met and the player will earn a badge for "Last Minute Super Closer".
So, the difference is that without criteria conditions, all related player activities are considered. With criteria conditions, only those activities that match the conditions you specified will be taken into account.
Possibilities
Using the same example criterion tied to the "Close a Sale" action, here is a very simple summary of the various combinations of rules and conditions and what they mean:
Condition
Rule
Activities Considered
Criterion Met When
<none>
gte:sum,10
all
The sum of each activity's amount is 10 or more
<none>
gte:amount,10
all
Any single activity's amount is 10 or more
dayOfMonth:1
gte:sum,10
1st of any month
The sum of each activity's amount is 10 or more
dayOfMonth:1
gte:amount,10
1st of any month
Any single activity's amount is 10 or more
As you can see, there are many possibilities. Combining and nesting criteria groups and applying one or more criteria conditions where it makes sense, together with the flexible criteria rules, gives you a great deal of power and flexibility to get more and more of the specific kinds of achievements you want for your users.
Available Criteria Conditions
Activity Data
This condition has the following form: activityData:field,operator,operand
When applied, this condition will filter out any activities according to the arguments that you provide. It filters on activities' custom_data field, specified by field, by comparing it to whatever has been specified in `operand`.
This condition is quite powerful and flexible for two reasons. First, it can "peek into" the custom_data that you provide when you report player activity. Second, it can compare it to "fixed" values or custom data for the current activity or the current activity's player.
This condition has the following arguments:
Name
Type
Default
field
string
-
operator
string
-
operand
integer|string
-
Both field and operator must be strings, while operand may be either an integer or a string.
Field
The field argument refers to custom data in activities. You use the field to refer to any value that may have been stored when reporting player activity. By using "dot" notation, you can refer to nested data elements within the custom_data field.
Operator
The operator simply dictates how the specified activity field will be "compared" to the operand value.
It can be any one of the following values:
eq: equal to
gt: greater than
gte: greater than or equal to
lt: less than
lte: less than or equal to
Operand
The operand is the value that each activity's custom data field, as specified, is compared to in order to determine which activities are considered when applying the affected criteria.
The operand may be a "static" value like 1234 or red. In such cases, only alphanumeric characters are permitted.
The operand may also be a custom data reference, in which case it must be enclosed in curly braces, meaning it would like something like this: {player.some.path}.
Examples
To better illustrate how this criteria condition might look, please consider some simple examples.
First, you might store custom data like this when reporting certain player activity:
1
{
2
  "category": "ABC123",
3
  "attributes": {
4
    "color": "red",
5
    "quantity": 4
6
  }
7
}
Copied!
To refer to these fields you would use the following definitions:
activityData:category,eq,{activity.category}: When applied, this would filter out all activities that do not have the same category as the current activity.
activityData:attributes.color,eq,{player.favorites.color}: When applied, this would filter out all activities that do not match the current player's favorite color.
activityData:attributes.quantity,gte,10: When applied, this would filter out all activities having a quantity of less than 10.
Between Hours
This condition has the following form: betweenHours:from,duration
When applied, this condition will filter out any activities that are not between the hours specified.
This condition has the following arguments:
Name
Type
Default
from
integer
-
duration
integer
-
Both from and duration must be integers.
The argument, from, may be any integer from 0 to 23. It represents the starting time hour.
The argument, duration, may be any integer from 0 to 24. It determines the stopping time hour by taking from and adding duration to it. So, betweenHours:9,8 will look for activities that take place between 9:00 and 17:00.
Currently, the minimum value of duration is 0, but this may be increased to 1 in the future.
Day of Month
This condition has the following form: dayOfMonth:day
When applied, this condition will filter out any activities that are not on the specified day of the month.
This condition has the following arguments:
Name
Type
Default
day
integer|string
-
The argument, day, may be any integer from 1 to 31 , the string, last, or a custom data reference string.
​
When last is used, it will filter on the last day of the month. For example, dayOfMonth:last will filter out any activities that are not on the last day of the month. For January, this will be the 31st. For February, this will be the 28th or 29th, depending on the year.
If specifying values for day that do not make sense, then results may be unexpected. As such, it is inadvisable to use values greater than 28 unless you combine dayOfMonth:31, for example, with other conditions that guarantee the results won't be unexpected, like month:12.
Day of Week
This condition has the following form: dayOfWeek:day
When applied, this condition will filter out any activities that did not occur during the specified day of the week.
This condition has the following arguments:
Name
Type
Default
day
integer
-
The argument, day, may be any integer from 1 to 7.
Day of Year
This condition has the following form: dayOfYear:day
When applied, this condition will filter out any activities that did not occur during the specified day of the year.
This condition has the following arguments:
Name
Type
Default
day
integer|string
-
The argument, day, may be any integer from 1 to 366 or the string, last.
When last is used, it will filter on the last day of the year. For example, dayOfYear:last will filter out any activities that are not on the last day of the year. This will always be December 31st, but you will not need to worry about whether or not it is a leap year. This will be taken into account for you automatically.
Days of Week
This condition has the following form: daysOfWeek:day[,day]
When applied, this condition will filter out any activities that did not occur during the specified days of the week.
This condition has the following arguments:
Name
Type
Default
day
integer
-
The argument, day, may be any integer from 1 to 7.
Any combination of days may be provided, separated by a commas (,). Duplicates will be ignored.
Some examples:
weekdays: daysOfWeek:2,3,4,5,6
weekends: daysOfWeek:1,7
No more than six days are permitted.
Month
This condition has the following form: month:month
When applied, this condition will filter out any activities that did not occur during the specified month.
This condition has the following arguments:
Name
Type
Default
month
integer|string
-
The argument, month, may be any integer from 1 to 12 or a custom data reference string.
Months
This condition has the following form: months:month[,month]
When applied, this condition will filter out any activities that did not occur during the specified months.
This condition has the following arguments:
Name
Type
Default
month
integer|string
-
The argument, month, may be any integer from 1 to 12 or a custom data reference string.
Any combination of months may be provided, separated by a commas (,). Duplicates will be ignored.
Some examples:
typical summer months (in the northern hemisphere 🤓): months:6,7,8
typical summer months (in the southern hemisphere 🙃): months:12,1,2
No more than eleven months are permitted.
Player Data
This condition is similar to activityData. It has the following form: playerData:field,operator,operand
When applied, this condition will allow related activities to be evaluated if it passes. If it does not pass, then it will halt any further evaluation. It compares a given custom_data field for the player, specified by field, to whatever has been specified in operand.
As with activityData, this condition is quite powerful and flexible. First, it can "peek into" the related player's custom_data. Second, it can compare it to "fixed" values, custom data for the current activity, or custom data for the current activity's player.
This condition has the following arguments:
Name
Type
Default
field
string
-
operator
string
-
operand
integer|string
-
Both field and operator must be strings, while operand may be either an integer or a string.
Field
The field argument refers to a player's custom data. You use the field to refer to any value that may have been stored with the current player. By using "dot" notation, you can refer to nested data elements within the custom_data field.
Operator
The operator simply dictates how the specified custom player data field will be "compared" to the operand value.
It can be any one of the following values:
eq: equal to
gt: greater than
gte: greater than or equal to
lt: less than
lte: less than or equal to
Operand
The operand is the value that each player's custom data field, as specified, is compared to in order to determine whether or not further evaluation should be permitted.
The operand may be a "static" value like 1234 or red. In such cases, only alphanumeric characters are permitted.
The operand may also be a custom data reference, in which case it must be enclosed in curly braces, meaning it would like something like this: {player.some.path}.
Examples
To better illustrate how this criteria condition might look, please consider some simple examples.
First, you might store custom data like this on a player:
1
{
2
  "category": "ABC123",
3
  "attributes": {
4
    "preferred_currency": "usd",
5
    "balance": 100
6
  }
7
}
Copied!
To refer to these fields you would use the following definitions:
playerData:category,eq,{activity.category}: When applied, this would pass if the current player category matches the activity category.
playerData:attributes.preferred_currency,eq,{activity.currency}: When applied, this would pass if the current player's preferred currency matches the current activity currency.
playerData:attributes.balance,gte,10: When applied, this would pass if the current player's balance is greater than or equal to 10.
Please note that if the specified player field is not found, this means the condition failed.
Same Date
This condition has the following form: sameDate.
When applied, this condition will filter out any activities that did not occur on the same date as the triggering activity.
Same Day of Month
This condition has the following form: sameDayOfMonth.
When applied, this condition will filter out any activities that did not occur on the same day of the month as the triggering activity.
Same Day of Week
This condition has the following form: sameDayOfWeek.
When applied, this condition will filter out any activities that did not occur on the same day of the week as the triggering activity.
Same Day of Year
This condition has the following form: sameDayOfYear.
When applied, this condition will filter out any activities that did not occur on the same day of the year as the triggering activity.
Same Month
This condition has the following form: sameMonth.
When applied, this condition will filter out any activities that did not occur during the same month as the triggering activity.
Same Week
This condition has the following form: sameWeek.
When applied, this condition will filter out any activities that did not occur during the same week as the triggering activity.
Same Year
This condition has the following form: sameYear.
When applied, this condition will filter out any activities that did not occur during the same year as the triggering activity.
Defining Criteria Conditions
Criteria conditions by themselves are relatively simple and straightforward, but in order to give you the ability to define complex criteria the structure is not quite as simple or straightforward. It is, however, easy enough to understand.
You can apply criteria conditions to your criteria as well as your criteria groups. The structure is the same in either case.
Criteria conditions are json and have the following format:
1
{
2
  "operator": "and",
3
  "groups": [
4
    {
5
      "operator": "or",
6
      "conditions": [
7
        "betweenHours:8,4",
8
        "betweenHours:13,4"
9
      ]
10
    },
11
    {
12
      "conditions": [
13
        "dayOfWeek:6"
14
      ]
15
    }
16
  ]
17
}
Copied!
So, at the "top", your criteria conditions definition can have the following properties:
Name
Type
Default
operator
string
and
groups
collection
-
Currently, operator can have one of the following values: and or or. It is used to determine how the grouped conditions are combined when applying the various conditions.
The groups property is a collection of "condition groups". Currently, you must have between 1 and 3 condition groups.
Each "condition group", then, has the following properties:
Name
Type
Default
operator
string
and
conditions
collection
-
Here, operator is very similar to before. It can be either and or or, and it's used to determine how the actual conditions within the group are applied.
The conditions collection is where you list the various conditions that you would like to have applied. Currently, you must have between 1 and 3 conditions.
Concepts - Previous
Criteria
Next - Concepts
Criteria Groups
Last modified 3mo ago