Filters: a closer look
Introduction.
Filters are optional conditions that can be attached to rules. While a rule determines the general mechanism for triggering a question (e.g., a recurring schedule or a location event), a filter adds an additional constraint that must also be satisfied before the question is shown.
Multiple filters can be attached to a single rule. When more than one filter is present, all of them must be satisfied simultaneously — along with the rule's own conditions — for the question to fire.
Not all filter types are available for every rule type. The compatible rule types are listed for each filter below.
Time interval.
A time interval filter restricts a rule to only fire during a specific window of the day, based on the participant's local time.
Parameters:
- Start hour (24-hour format): The earliest full hour at which the rule is allowed to fire. Accepts integers from 0 to 23. Required.
- End hour (24-hour format): The latest full hour at which the rule is allowed to fire. Accepts integers from 0 to 23. Optional.
Logic: Ask this question when the participant's context matches the rule and all associated filters, and, additionally, the time of day is between the full hours of the start hour and the end hour.
Compatible rule types: All rule types, except Upon random time and UI observer.
Location proximity.
A location proximity filter restricts a rule to only fire when the participant is within a specified distance from a given coordinate. This filter is not available for GPS-based rules, since those are already inherently location-bound.
Parameters:
- Latitude: The latitude of the target location. Accepts values between -90 and 90, with up to 7 decimal places. Required.
- Longitude: The longitude of the target location. Accepts values between -180 and 180, with up to 7 decimal places. Required.
- Maximum distance from location (meters): The radius around the target coordinate within which the participant must be located. Accepts integers between 1 and 10,000. Required.
Logic: Ask this question when the participant's context matches the rule and all associated filters, and, additionally, the participant is within the specified number of meters of the given latitude and longitude.
Compatible rule types: Bluetooth rules, Beacon rules, BLE rules, Activity rules, Empatica E4 rules, Upon recurring time interval (cron), and Upon random time.
Most recent answer to specified question.
This filter restricts a rule to only fire when the participant's most recent response to a particular question matches one or more specified answer choices.
Parameters:
- Question required to have been answered prior: The question whose most recent answer will be evaluated. Required.
- ID(s) of the required response(s): The specific answer choice(s) that the participant's most recent response must match. Required.
Logic: Ask this question when the participant's context matches the rule and all associated filters, and, additionally, the most recent response to the specified question was one of the specified choices.
Compatible rule types: All rule types, except Upon random time and UI observer.
Throttle (rate limiter).
The throttle filter is a rate-limiting mechanism. Unlike other filters, it does not evaluate the participant's current context; instead, it suppresses rule firings based on how recently or how frequently a labeled group of rules has already fired.
Rules that share the same throttle label are treated as a single group for the purposes of rate limiting. This makes it possible to cap the combined firing rate across multiple rules at once, regardless of which specific rule would otherwise be triggered.
Parameters:
- Throttle group label: A text label shared by the group of rules you want to rate-limit together. Any non-empty string. Required.
- Minimum gap between firings (minutes): The minimum number of minutes that must have elapsed since any rule with the same throttle label last fired. Accepts integers between 0 and 1440. Required.
- Maximum firings per day: The maximum number of times rules sharing the same throttle label may fire within a single calendar day. Accepts integers between 1 and 1000. Required.
Logic: Suppress this rule if any rule sharing the same throttle label has fired within the past B minutes, or if rules with that label have already fired C or more times today.
Compatible rule types: All rule types.
Example
Below, we create an arrival beacon-based rule and add a Throttle filter so the question can fire at most once every 10 minutes.
Parameters:
- Throttle group label:
10MinutesAn arbitrary label used to group throttle filters. Since this example only uses one filter, you can think of the label as mostly just a name.
Minimum gap between firings:
10 minutes.The rule, and any other rule using the same throttle group label, cannot fire more than once every 10 minutes.Maximum firings per day:
999We do not want a daily limit, so we set this to a very high value.
