How to Build Your Own Segmentation Filters to Use With, e.g.: The Reporting API
Analytics are great because they provide answers to all sorts of questions:
- How many people visited my Website?
- When did they visit?
- Where did they come from?
But while analytics give us some answers, they also create many more questions:
- Of the people who came to the site, how many visited from the US?
- Of the US visitors, how many came from search engines?
- And how much items were purchased by just those visitors?
Segmentation allows you to narrowly focus attention on only the visitors you want to analyze, and probe deeper to make better decisions.
Segments
Segments consist of two parameters: are
(who they are, i.e: visitor Properties) and did
(what they did i.e: visitor actions) and each segment contains an operator and a list of filters. Reports and Searches support a segments and they consist of an array of the segments
defined below.
{
"are": {
"operator": "AND", // AND or OR
"filters": []
},
"did": {
"operator": "AND", // AND, OR or THEN
"filters": []
}
}
"Are" Filters
The are
filters are simple constraints that cover the Custom Visitor Data. This filter below will narrow the query response down to those from companies that have more than 300
employees and are at the trial
stage.
{
are: {
"operator": "AND",
"filters": [{
"scope": "visitors",
"key": "company size",
"match": "gte",
"value": 300
}, {
"scope": "visitors",
"key": "stage",
"match": "match",
"value": "trial"
}]
}
}
"Did" Filters
Every did filter consists of 4 objects:
- action
- aggregation
- timeframe
- visit
action
Action defines the action targetd in this behavioral filter. For example, if you want to filter people who made a payment
, the action object should define the action payment and its constrains.
action:{
"operator": "AND",
"filters": [{
"scope": "actions",
"key": "name",
"match": "match",
"value": "payment"
}, {
"scope": "actions",
"key": "amount",
"match": "gt",
"value": "10"
}]
}
aggregation
The action constraints are extended with aggregation rules which must be matched. For example, you may want to spot people who committed the action payment
at least 3 times, or those people who committed the action payment
where the sum of amount
(which is a property inside every payment
action) to be greater than $100.
Count aggregation example
The method count
takes scope
as an extra parameter which is action
by default. It enabled you to count occurrences by actions or limiting the count to one per visit.
aggregation: {
"method": "count",
"scope": "actions", // or visits (to count once per visit)
"match": "gte", // equivalent to "greater than or equals" or "at least"
"value": 3
}
Sum aggregation example
The method sum
takes an extra parameter titled by
which is the target key that should be used to sum amounts. For example, in a payment
event, you need to use the amount
key.
aggregation: {
"method": "sum",
"by": "amount", // property of the action matching in "actions"
"match": "gte", // equivalent to "greater than or equals" or "at least"
"value": 100
}
timeframe
You must define a time frame for every behavioral filter. Time frames can be defined using one of 2 methods: relative dates (days ago) and absolute dates.
Example of a relative time frame
The example below defines a timeframe relative to the time you’re querying the Woopra engines: From 29 to 0 days ago. Which means last 30 days including today.
timeframe: {
"method": "relative",
"from": 29,
"to": 0
}
Example of an absolute time frame
The example below defines a timeframe that is absolute. You must define two dates in the format of yyyy-mm-dd.
timeframe: {
"method": "absolute",
"from": "2013-01-01",
"to": "2013-01-31"
}
visit
The visit parameter defines the visit constraints that should be matched. If a visit that contains a matching action but does not match with the visit constraints, the matching actions will be ignored. The visit constraints object consists of two properties: operator and filters.
visit: {
"operator": "AND",
"filters": [{
"scope": "visits",
"key": "browser",
"match": "contains",
"value": "chrome"
}]
}
Match Comparators
Key | Description | Data Type |
---|---|---|
match | Exactly Matches | string |
starts | Starts With | string |
contains | Contains | string |
ends | Ends With | string |
notmatch | Does Not Match | string |
notstarts | Does Not Start With | string |
notends | Does Not End With | string |
notcontains | Does Not Contain | string |
regexp | Entire String Matches Regular Expression | string |
empty | Empty | string/any |
notempty | Not Empty | string/any |
eq | Equals | number |
lt | Less Than | number |
gt | Greater than | number |
gte | Greater Than or Equals | number |
lte | Less Than or Equals | number |
neq | Not equals | number |
Full Segments Example
segments: [{
"are": {
"operator": "AND",
"filters": [{
"scope": "visitors",
"key": "company size",
"match": "gte",
"value": 300
}, {
"scope": "visitors",
"key": "stage",
"match": "match",
"value": "trial"
}]
},
"did": {
"operator": "AND",
"filters": [{
action: {
"operator": "AND",
"filters": [{
"scope": "actions",
"key": "name",
"match": "match",
"value": "payment"
}]
},
aggregation: {
"method": "sum",
"by": "amount", // property of the action matching in "actions"
"match": "gte", // equivalent to "greater than or equals" or "at least"
"value": 100
},
timeframe: {
"method": "relative",
"from": 29,
"to": 0
},
visit: {
"operator": "AND",
"filters": [{
"scope": "visits",
"key": "city",
"match": "match",
"value": "San Francisco"
}]
}
}]
}
}]