Criteria Conditions
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.
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.
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.
This condition has the following form:
activityData:field,operator,operandWhen 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.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.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 togt: greater thangte: greater than or equal tolt: less thanlte: less than or equal to
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}.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:
{
"category": "ABC123",
"attributes": {
"color": "red",
"quantity": 4
}
}
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.
This condition has the following form:
betweenHours:from,durationWhen 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.This condition has the following form:
dayOfMonth:dayWhen 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.This condition has the following form:
dayOfWeek:dayWhen 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.This condition has the following form:
dayOfYear:dayWhen 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.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.
This condition has the following form:
month:monthWhen 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.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.
This condition is similar to
activityData. It has the following form: playerData:field,operator,operandWhen 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.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.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 togt: greater thangte: greater than or equal tolt: less thanlte: less than or equal to
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}.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:
{
"category": "ABC123",
"attributes": {
"preferred_currency": "usd",
"balance": 100
}
}
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.
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.
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.
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.
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.
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.
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.
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.
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:
{
"operator": "and",
"groups": [
{
"operator": "or",
"conditions": [
"betweenHours:8,4",
"betweenHours:13,4"
]
},
{
"conditions": [
"dayOfWeek:6"
]
}
]
}
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.Last modified 1yr ago