Special Filters
Some filters need to be represented in a special format due to their unique requirements. These special filters are:
| • | Special Filter: licenseStatus |
| • | Special Filter: os |
| • | Special Filter: geography |
| • | Special Filter: gpu |
| • | Special filters: optOut and backOff |
| • | Special Filter: lifetimeEventUsage |
| • | Special Filter: reachOutDeliveries |
The licenseStatus filter is made up of 4 sub-values: activated, blacklisted, expired and whitelisted. These are presented as boolean values. Unlike other filters, this filter is presented as an array of JSON objects. Each object can contain a subset (or all) of these 4 boolean values.
Consider the following example. In this example, for a client to be included, the license has to either be activated AND whitelisted, or else it can be not whitelisted AND expired. In other words, ( (activated AND whitelisted) OR ((NOT)whitelisted AND expired) ).
{
"licenseStatus":
[
{
"activated": true,
"whitelisted": true
},
{
"whitelisted": false,
"expired": true
}
]
}
The os filter is made up of 3 granularity levels. These are platform, version, and edition. These are meant to split the OS name into levels of detail as required by the user. Consider the following:
| • | platform: Microsoft Windows |
| • | version: Microsoft Windows 7 |
| • | edition: Microsoft Windows 7 Professional |
If a filter is set on the version “Microsoft Windows 7”, the result would include all editions of Windows 7. One or more of these granularity levels may be specified. If more than 1 granularity level is specified, the values are ORed together.
In the following example, all editions of “Microsoft Windows 7” are included, and also “Microsoft Windows Vista Home Premium”:
{
"type": "string",
"version": "Microsoft Windows 7",
"edition": "Microsoft Windows Vista Home Premium"
}
In the following example, the type is stringArray. Note that an array needs to be passed if the type is set as such, even if it is to contain only 1 element. In this case, the version can be either “Microsoft Windows 7” or “Microsoft Windows 8” (which are ORed together). Also, clients running on “Microsoft Windows XP Professional” are to be included.
{
"type": "stringArray",
"version": ["Microsoft Windows 7", "Microsoft Windows 8"],
"edition": ["Microsoft Windows XP Professional"]
}
The geography filter is made up of 3 granularity levels. These are continent, country, and usState.
The usState value applies only to United States. Continents and countries are presented in 2-letter codes. Countries follow ISO standard 3166-1 alpha-2. US states are presented in ISO 3166-2:US format.
In the following example, the clients have to be either:
| • | In the continents Asia or Oceania |
| • | In the country Germany |
| • | In the US states New York, New Jersey, or Kansas |
{
"type": "stringArray",
"continent": ["AS", "OC"],
"country": ["DE"],
"usState": ["US-NY", "US-NJ", "US-KS"]
}
Important:In this filter, the type can be string or stringArray. Regular expressions are not supported in geography filters.
The gpu filter is made up of 2 granularity levels. These are vendor and model. Both are represented as string values.
In the following example, the clients have to have a GPU:
| • | From the vendors NVIDIA or Intel |
| • | With the model AMD Radeon HD 4600 |
{
"type": "stringArray",
"vendor": ["NVIDIA", "Intel"],
"model": ["AMD Radeon HD 4600"]
}
Special filters: optOut and backOff
The opt-out mechanism was introduced in SDK version 5.1.0. With this feature, vendors can have their application report to the Usage Intelligence servers that a user does not want to be tracked. Using this property, vendors can filter out installations that were opted-out.
Similarly, backoff filtering was introduced with version 5.0.0. Backoff is when a product account runs over-quota and the server starts rejecting data. Although filtering for backed-off installations was introduced with version 5, it was also backported to previous versions. However, when a new installation with an SDK prior to version 5 tries to register with the server and is rejected, it is not marked as being once backed-off when it is eventually accepted by the server. With version 5 onwards, the server flags an installation as being historically backed-off in such cases.
Both backOff and optOut filters are made up of 2 boolean sub-values: historical and current.
| • | The historical value refers to installations that were once backed-off or opted-out. These may include installations that are still currently backed-off or opted-out. |
| • | The current value refers to the status during the last time that the client called the server. Therefore, if an installation was opted-out yesterday but got opted-in today, it will be marked as historically opted-out but not currently opted-out. |
In the following example, for a client to be included, the optOut status has to either be historical AND not current, or else it can be not historical (i.e. users have to be currently opted-in but used to be opted-out at some point or never opted out).
{
"optOut":
[
{
"historical": true,
"current": false
},
{
"historical": false
}
]
}
Special Filter: lifetimeEventUsage
Using lifetime event usage filters, clients can be filtered based on whether a particular event or set of events occurred or not within the client’s lifetime. Alternatively, one can set a filter based on the number of times an event has occurred.
In the following example, clients that are included must have done the “File Operations - Open” event at least 5 times to be counted.
{
"category": "File Operations",
"name": "Open",
"min": 5
}
In the following example, clients must have done either “File Operations - Open” or “File Operations - Save” for a combined total of between 10 to 50 times.
{
"combiArray": [
{
"categoryType": "string",
"nameType": "string",
"category": "File Operations",
"name": "Open"
},
{
"categoryType": "string",
"nameType": "string",
"category": "File Operations",
"name": "Save",
}
],
"min": 10,
"max": 50
}
In the following example, clients must have done any event within the “File Operations” category for a combined total of not more than 100 times. This is done using a regular expression in the name.
{
"combiArray": [
{
"categoryType": "string",
"nameType": "regex",
"category": "File Operations",
"name": ".*"
}
],
"max": 100
}
Special Filter: reachOutDeliveries
Using ReachOut delivery filters, clients can be filtered based on whether a particular ReachOut message or a combination of ReachOut messages were delivered or not within the client’s lifetime.
The filter consists of a JSON array that includes one or more objects. Each object is a combination of delivered and undelivered campaigns, and the different combinations are ORed together. Therefore, it is possible to show users that either received ReachOut message 1 but not 2, or else received 3 but not 4 as in the following example:
In the following example, we are looking for clients who either received campaign 1 but not 2, OR received campaign 2 but not 3.
[
{"auto": {"delivered": ["1"], "undelivered":["2"]}},
{"auto": {"delivered": ["2"], "undelivered":["3"]}}
]
The above example contains only “auto” ReachOut campaigns. Manual campaigns can be specified using “manual” instead of “auto” as in the above example. Each object can contain a mix of “auto” and “manual” campaigns.