Configure the Facets for Trends

How to Configure the Facets for Trends

The Trends tab of the Audience Perspective offers a list of facets, the visitor characteristics, by which CMS users can select a visitor segment and measure content performance. The facets offered are configurable. The configuration is stored in the repository and can be edited using the Console. It is possible to:

1. Add, remove and reorder facets
2. Change the textual presentation of a facet
3. Configure the field in the Elasticsearch visitor store from which the facet retrieves its data

Configuration

The facet configuration is stored in targeting:facet nodes under the following path:

/targeting:targeting/targeting:trends/targeting:facets

To change, add, remove and reorder facets from the Trends tab, modify, add, remove or reorder the child nodes. Every targeting:facet node has the following properties, all of which are required.

• targeting:facetName (string), keyword-style, used in table headers and the Peak performing [FACET] drop down.
• targeting:filterName (string), more phrase-like, completes the sentence 'When the visitor...'.
• targeting:esField (string), see below.

For example,

facetName = country
filterName = comes from country
esField = requests.collectorData.geo.country

Using Data from Collectors

For data gathered by Collectors, the value of the esField property has the following structure:

requests.collectorData.COLLECTORNAME.FIELDNAME

The COLLECTORNAME is the node name of the collector configuration under /targeting:targeting/targeting:collectors. The FIELDNAME is the name of a String property in that Collector's Targeting Request Data bean, that is, the data returned from the method:

getTargetingRequestData(HttpServletRequest request, boolean newVisitor, boolean newVisit, T previousTargetingData)

For example, in the GeoIPCollector, this method returns a GeoIPTargetingRequestData object 

    public static class GeoIPTargetingRequestData {
        private String country;
        private String city;
        private double latitude;
        private double longitude;

        public void setCountry(final String country) { this.country = country; }
        public String getCountry() { return country; }

        public void setCity(final String city) { this.city = city; }
        public String getCity() { return city; }

        public void setLatitude(double latitude) { this.latitude = latitude; }
        public double getLatitude() { return latitude; }

        public void setLongitude(double longitude) { this.longitude = longitude; }
        public double getLongitude() { return longitude; }
    }

So if this collector is configured under 'geo', useful values for targeting:esField are requests.collectorData.geo.country and requests.collectorData.geo.city.

Note that due to Elasticsearch 2 not allowing dots in field names, collectors that are configured to collect data with dots in their names replace dots with underscores. As a consequence, the esField that you configure should also use underscores. For example, if you collect a cookie named x.y then FIELDNAME in the targeting:esField value would be x_y for your cookie facet.

Using Augmented Request Data

If your project adds additional data to request log entries as described in Augmenting RequestLog data, that data is available under requests.data.FIELDNAME. 

Examples

Examples of esField values for some common collectors and other data on the request log entries:

1. requests.collectorData.categories.terms (looks at category, com.onehippo.cms7.targeting.collectors.TagsCollector)
2. requests.collectorData.geo.country (comes from country, com.onehippo.cms7.targeting.collectors.GeoIPCollector)
3. requests.collectorData.geo.city (comes from city, com.onehippo.cms7.targeting.collectors.GeoIPCollector)
4. requests.collectorData.doccreatedby.terms (created by, com.onehippo.cms7.targeting.collectors.DocumentPropertyCollector)
5. convertedGoals.goalName (converted goal, data from Experiments, not a collector)
6. requests.pathInfo (visited URL, data from the request log entry itself)

Elasticsearch Mapping

To get a complete overview of fields available in your Elasticsearch store, look at http://elasticsearch-location/indexname/_mapping?pretty where elasticsearch-location and indexname match the corresponding values under /targeting:targeting/targeting:datastores/visits. The output is extremely accurate though not very easy to read.