Characteristics

Available characteristics

The following characteristics are available:

Characteristic	Description	Collector	Scorer Class Name *)
Day of the week	The current day of the week (Sunday, Monday, etc.)	DayOfWeekCollector	DayOfWeekScorer
Document types	The document types a visitor has seen	DocumentTypesCollector	VectorScorer
City	The city a visitor comes from	GeoIPCollector	CityScorer
Country	The country a visitor comes from	GeoIPCollector	CountryScorer
Continent	The continent a visitor comes from	GeoIPCollector	ContinentScorer
Groups	The user groups a visitor belongs to	GroupsCollector	GroupsScorer
Page views	The URLs a visitor has requested	PageViewsCollector	PageViewsScorer
Referrer	The URL of the previous site a visitor has visited	ReferrerCollector	MatchesTermScorer
Returning visitor	Whether a visitor is returning or new	ReturningVisitorCollector	ReturningVisitorScorer
Tags	The tags on documents that a visitor has seen	TagsCollector	VectorScorer

*) All scorers in the table above are located in the package com.onehippo.cms7.targeting.scoring.

Backend configuration

The backend configuration of a characteristic specifies how the Relevance Module can collect data for that characteristic.

Characteristics are configured in the repository at

/targeting:targeting/targeting:characteristics

Each child node specifies one characteristic. The node name is the ID of the characteristic. Each characteristic node has two mandatory properties:

• targeting:collector The ID of the collector of this characteristic.

• targeting:scorerClassName The Java class of the scorer implementation of this characteristic. The scorer should use the same targeting data type as created by the collector.

Frontend configuration

The frontend configuration of a characteristic specifies its characteristic plugin. Each characteristic configured in the backend should also have a characteristic plugin for the frontend.

Characteristic plugins are configured in the repository at:

/hippo:configuration/hippo:frontend/cms/hippo-targeting

Each characteristic plugin is configured in one child node of type 'frontend:pluginconfig'. The node name does not matter, but it is good practice to name it 'characteristic-<ID of your characteristic>'. Each characteristic plugin node can have the following properties:

• characteristic (String, mandatory) The ID of the characteristic.

• plugin.class (String, mandatory) The Java class name of the characteristic plugin

• collector (String, mandatory) The ID of the collector of the characteristic.

• visitor.characteristic.visible (Boolean, optional) Whether or not to show this characteristic is the list of visitor characteristics in the Visitor Analysis tab. Default: true

A characteristic plugin can define more configuration properties to customize the plugin.

Java API

com.onehippo.cms7.targeting.frontend.plugin.geo.CityCharacteristicPlugin

Characteristic plugin for the 'city' characteristic. Configured by default.

com.onehippo.cms7.targeting.frontend.plugin.geo.CountryCharacteristicPlugin

Characteristic plugin for the 'country' characteristic. Configured by default.

com.onehippo.cms7.targeting.frontend.plugin.geo.ContinentCharacteristicPlugin

Characteristic plugin for the 'continent' characteristic. Configured by default.

com.onehippo.cms7.targeting.frontend.plugin.CharacteristicPlugin

Base class for characteristic plugins.

Plugin configuration properties:

• collector(String, mandatory) The ID of the collector of the characteristic.

• characteristic (String, mandatory)
  The ID of the characteristic.

• plugin.class (String, mandatory)
  The Java class name of the characteristic plugin

• visitor.characteristic.visible (Boolean, optional)
  Whether or not to show this characteristic is the list of visitor characteristics in the Visitor Analysis tab.
  Default: true

com.onehippo.cms7.targeting.frontend.plugin.documenttype.DocumentTypeCharacteristicPlugin

Plugin for a characteristic backed by a DocumentTypesCollector. Provides a custom target group column for rendering and editing document types (i.e. JCR types). The multiple String configuration properties 'type.prefix.includes' and 'type.prefix.excludes' determine which document types are shown to the user. The UI will show the i18n name of each document type, but store the JCR type in the target group.

Additional plugin configuration properties:

• type.prefix.includes (multiple String)
  List of JCR type prefixes that should be available in the document type column. For example, use 'mynamespace:' to include all JCR types in a certain namespace. When no included prefixes are configured no types will be available in the document type column, and a warning will be logged.

• type.prefix.excludes (multiple String)
  List of JCR type prefixes that should be excluded from the list of included types.

com.onehippo.cms7.targeting.frontend.plugin.pageviews.PageViewsCharacteristicPlugin

Characteristic plugin for the 'pageviews' characteristic. Configured by default.

com.onehippo.cms7.targeting.frontend.plugin.dayofweek.DayOfWeekCharacteristicPlugin

Characteristic plugin for the 'dayofweek' characteristic. Does not need any additional configuration other than setting the default CharacteristicPlugin configuration properties.

com.onehippo.cms7.targeting.frontend.plugin.referrer.ReferrerCharacteristicPlugin

Characteristic plugin for the 'referrer' characteristic. Does not need any additional configuration other than setting the default CharacteristicPlugin configuration properties.

com.onehippo.cms7.targeting.frontend.plugin.returningvisitor.ReturningVisitorCharacteristicPlugin

Characteristic plugin for the 'returningvisitor' characteristic. Does not need any additional configuration other than setting the default CharacteristicPlugin configuration properties.

com.onehippo.cms7.targeting.frontend.plugin.groups.GroupsCharacteristicPlugin

Characteristic plugin for the 'groups' characteristic. Besides the default configuration options the CharacteristicPlugin requires the configuration of this additional property:

• excludes(multiple String)
  A list of regular expression patterns to match groups against that should not be shown as options to the user.

Javascript API

The following Javascript functions and classes are available for creating your own characteristic plugin implementation.

Hippo.Targeting.TargetGroupColumn.register(xtype, class)

Registers a Javascript class as a target group column xtype.

Hippo.Targeting.TargetGroupColumn

Base class for target group columns. A target group column can define its own renderer and/or editor for a target group.

Extends: Ext.grid.Column

Properties:

• renderer (Mixed)
  Optional interceptor method that transforms an array of property objects to rendered data. See Ext.grid.Column.renderer for details.

• editor (Ext.form.Field)
  Optional form field for editing target group properties.

Hippo.Targeting.TargetGroupCheckboxGroup

Checkbox group for editing a target group. The default implementation maps the name of each checkbox to a target group property name, but subclasses can provide their own implementation of the methods convertPropertiesToCheckedArray and convertCheckedBoxesToProperties to customize this behavior.

Extends: Ext.form.CheckboxGroup

Methods:

• convertPropertiesToCheckedArray(Array properties) : Array
  Converts an array of property objects to an array of booleans that indicates which checkboxes should be checked. The default implementation assumes the target group property names map to the names of the checkboxes.
  
  Parameters:
  properties (String): an array of property objects. Each property object has the String properties 'name' and 'value'.
  
  Returns:
  An array of booleans. The Nth boolean indicates whether the Nth checkbox should be checked or not.

• convertCheckedBoxesToProperties(Array checkedBoxes) : Array
  Converts an array of Ext.form.Checkbox objects to an array of property objects. The default implementation saves the name of each checked box as a target group property name.
  
  Parameters:
  checkedBoxes (Array): an array of Ext.form.Checkbox objects that are currently checked.
  
  Returns:
  An array of property objects. Each property object should have the String properties 'name' and 'value'. Use an empty string if the value is not important.

Hippo.Targeting.TargetGroupTextField

Text field for editing a target group. Subclasses should provide their own implementation of the methods convertPropertiesToValue and convertValueToProperties, which convert an array of property objects to a string
value and back, respectively.

Extends: Ext.form.TextField

Methods:

• convertPropertiesToValue(Array properties) : String
  Converts an array of property objects to a string value. This default implementation returns an empty string. Subclasses should
  override this method to implement their own conversion.
  
  Parameters:
  properties (String): an array of property objects. Each property object has the String properties 'name' and 'value'.
  
  Returns:
  The text representation of the properties a user will see and edit

• convertValueToProperties(String value) : Array
  Converts a string value to an array of property objects. This default implementation returns an empty array. Subclasses should override this method to implement their own conversion.
  
  Parameters:
  value (String): the string value entered by the user.
  
  Returns:
  An array of property objects. Each property object should have the String properties 'name' and 'value'. Use an empty string if the value is not important.

Hippo.Targeting.CharacteristicPlugin

Base class for characteristic plugins. A characteristic plugin can define its own visitor target group and target group column.

Extends: Ext.util.Observable

Properties:

• renderer (Function, optional)
  Optional interceptor method that transforms an array of property objects to rendered data. See Ext.grid.Column.renderer for details.

• editor(Ext.form.Field, optional)
  Optional form field for editing target group properties. Note that the value provided to setValue and returned by getValue is not a String (as with normal Ext.form.Fields), but an array of 'property objects'. Each property object consists of a 'name' and a 'value'.

• targetGroupColumn(Object, optional)

  Instead of specifying a renderer and editor directory, you can also specify a configuration object for a column that in turn defines the editor and renderer. It must at least contain the property 'xtype' with the xtype of the target group column class, but can also contain other properties that are passed to the constructor of the target group column class. Using the renderer and editor directly is recommended, as it simplifies you code.

  Default:

  {
   xtype: 'Hippo.Targeting.PropertyNamesColumn'
  }

• visitorCharacteristic (Object, optional)
  Configuration object for the visitor characteristic of this characteristic plugin. Must at least contain the property 'xtype' with the xtype of the visitor characteristic class, but can also contain other properties that are passed to the constructor of the visitor characteristic class. When omitted, no visitor characteristic will be shown.

  Default:

  {
   xtype: 'Hippo.Targeting.VisitorCharacteristic'
  }

Hippo.Targeting.TargetingDataPropertyCharacteristic

Visitor characteristic that reads a specific property from the targetingData object, and returns that as both the target group name and value.

Extends: Hippo.Targeting.VisitorCharacteristic

Properties:

• targetingDataProperty
  The name of the property of the targetingData object to use

Hippo.Targeting.TermsFrequencyCharacteristic

Visitor characteristic for a characteristic backed by an com.onehippo.cms7.targeting.collectors.AbstractTermsFrequencyCollector.It reads the property targetingData.termFrequencies, uses a comma-separated list of term names as the returned target group name. Subclasses can override the method getTermName to customize the displayed name of each term. The returned target group properties contain a property name for each term.

Extends: Hippo.Targeting.VisitorCharacteristic

Hippo.Targeting.VisitorCharacteristic

Base class for a visitor characteristic, which inspects a targetingData object and returns a target group for it. The structure of the targeting data reflects the getters of the TargetingData Java object created by the collector of the characteristic that uses this visitor characteristic. Subclasses should override the methods isCollected, getTargetGroupName, and getTargetGroupProperties.

Extends: Ext.util.Observable

Methods:

• isCollected(targetingData): Boolean
  Returns true when the targetingData object contains a characteristic, false otherwise.

• getTargetGroupName(targetingData): String
  Returns the human-readable name of the target group

• getTargetGroupProperties(targetingData): Array
  Returns the properties of the target group, i.e. an array of 'property objects'. Each property object has of a 'name' and a 'value'. Use an empty string when the value does not matter.