Criteria Conditions
Last updated
Last updated
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 |
---|---|---|---|
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,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:
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 to
gt
: greater than
gte
: greater than or equal to
lt
: less than
lte
: 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:
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,duration
When applied, this condition will filter out any activities that are not between the hours specified.
This condition has the following arguments:
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: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:
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: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:
The argument, day
, may be any integer from 1
to 7
.
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:
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:
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:month
When applied, this condition will filter out any activities that did not occur during the specified month.
This condition has the following arguments:
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:
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,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:
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 to
gt
: greater than
gte
: greater than or equal to
lt
: less than
lte
: 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:
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:
So, at the "top", your criteria conditions definition can have the following properties:
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:
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.
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|