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:

{
  "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.

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:

{
  "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.

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:

{
  "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.