Characteristics

Note: For definitions of characteristic, target group, target group renderer and editor, and scorer, see Relevance Concepts and Terminology.

Available Characteristics

The following characteristics are available in the Relevance Module:

Characteristic	Description	Collector	*Scorer Class Name )**
Day of the week	The current day of the week (Sunday, Monday, etc.)	`DayOfWeekCollector`	`DayOfWeekScorer`
Document types	Document types viewed by the visitor	`DocumentTypesCollector`	`VectorScorer`
City	The visitor's city	`GeoIPCollector`	`CityScorer`
Country	The visitor's country	`GeoIPCollector`	`CountryScorer`
Continent	The visitor's continent	`GeoIPCollector`	`ContinentScorer`
Groups	User groups associated with the visitor	`GroupsCollector`	`GroupsScorer`
Page views	URLs requested by the visitor	`PageViewsCollector`	`PageViewsScorer`
Referrer	The URL of the previous site visited	`ReferrerCollector`	`MatchesTermScorer`
Returning visitor	Indicates if the visitor is returning or new	`ReturningVisitorCollector`	`ReturningVisitorScorer`
Tags	Tags on documents viewed by the visitor	`TagsCollector`	`VectorScorer`

*) All scorer classes listed above are in the com.onehippo.cms7.targeting.scoring package.

Note: By default, only the city, country, continent, and page views characteristics are preconfigured. To enable additional characteristics and target groups, add the Collectors Bundle to your project.

Backend Configuration

Configure characteristics in the repository at:

/targeting:targeting/targeting:characteristics

Each child node under this path represents a characteristic. The node name serves as the characteristic's ID. Each characteristic node must include the following properties:

targeting:collector: The collector ID for this characteristic.
targeting:scorerClassName: The fully qualified Java class name of the scorer implementation. The scorer must use the same targeting data type produced by the collector.

Frontend Configuration

Frontend configuration defines the characteristic plugin for each characteristic. Every backend-configured characteristic should have a corresponding frontend plugin.

Configure characteristic plugins in the repository at:

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

Each plugin is defined in a child node of type frontend:pluginconfig. The node name is arbitrary, but using characteristic-<ID> is recommended for clarity. Each plugin node can include the following properties:

characteristic (String, required): The characteristic ID.
plugin.class (String, required): The Java class name of the characteristic plugin.
collector (String, required): The collector ID for this characteristic.
visitor.characteristic.visible (Boolean, optional): Controls visibility in the Visitor Analysis tab. Default: true.
Since 17.2
frontend:editorType (String, optional): Specifies the built-in Angular editor. Valid values: property-names, checkbox-group, radio-group. Default: property-names.

You can add additional properties to customize the plugin as needed.

Java API

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

This is the base class for characteristic plugins.

Since 17.2:

Use enrichFrontendOptions(Map options) instead of onRenderProperties(JSONObject properties).
The getIcon() method is now public.

Plugin configuration properties:

characteristic (String, required): The characteristic ID.
plugin.class (String, required): The Java class name of the characteristic plugin.
collector (String, required): The collector ID.
visitor.characteristic.visible (Boolean, optional): Controls visibility in the Visitor Analysis tab. Default: true.
Since 17.2
frontend:editorType (String, optional): Specifies the Angular editor. Valid values: property-names, checkbox-group, radio-group, text-field, page-views, external-segments. Default: property-names.

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

Plugin for the city characteristic. This plugin is configured by default.

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

Plugin for the country characteristic. This plugin is configured by default.

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

Plugin for the continent characteristic. This plugin is configured by default.

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

Plugin for characteristics using a DocumentTypesCollector. Use the type.prefix.includes and type.prefix.excludes properties to control which document types are available. The UI displays the i18n name, but stores the JCR type in the target group.

Additional configuration properties:

type.prefix.includes (multiple String): JCR type prefixes to include in the document type column. For example, use mynamespace: to include all types in a namespace. If not set, no types are available and a warning is logged.
type.prefix.excludes (multiple String): JCR type prefixes to exclude from the included types.

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

Plugin for the pageviews characteristic. Configured by default.

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

Plugin for the dayofweek characteristic. No additional configuration is required beyond the standard CharacteristicPlugin properties.

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

Plugin for the referrer characteristic. No additional configuration is required beyond the standard CharacteristicPlugin properties.

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

Plugin for the returningvisitor characteristic. No additional configuration is required beyond the standard CharacteristicPlugin properties.

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

Plugin for the groups characteristic. In addition to the standard configuration, set:

excludes (multiple String): Regular expression patterns for groups to exclude from the options shown to users.

Upgrade Path to 17.2

To upgrade custom characteristic plugins to version 17.2, follow these steps:

In the Java class:

Remove all @ExtClass annotations and ExtJS plugin classes.
Change the getIcon() method from protected to public.
Replace the onRenderProperties override with
public void enrichFrontendOptions(Map<String, Object> options).
Optionally, override getAngularEditorType() or set frontend:editorType in the plugin configuration to select the Angular editor. Valid values: property-names, checkbox-group, radio-group.
Remove any renderHead overrides.
Remove unused imports.

Remove any ExtJS JavaScript or CSS resources that were previously added using renderHead.

In the associated properties files, remove any entries used only by ExtJS JavaScript files.

JavaScript API (Before 17.2)

Before version 17.2, you could use custom ExtJS plugins for rendering custom plugins. Starting with 17.2, built-in Angular editors are used. These editors are identified by the IDs property-names, text-field, checkbox-group, radio-group, page-views, or external-segments, and are set using the frontend:editorType property or by overriding the Java method getAngularEditorType().

The following JavaScript functions and classes are available for implementing custom characteristic plugins.

`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 a custom renderer and/or editor for a target group.

Extends: Ext.grid.Column

Properties:

renderer (Mixed): Optional method to transform an array of property objects into 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 each checkbox name to a target group property name. Subclasses can override 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 indicating which checkboxes should be checked.
- properties (String): Array of property objects, each with name and value properties.
- Returns: Array of booleans, where each value indicates if the corresponding checkbox is checked.
convertCheckedBoxesToProperties(Array checkedBoxes): Array
Converts an array of checked Ext.form.Checkbox objects to an array of property objects.
- checkedBoxes (Array): Array of checked checkbox objects.
- Returns: Array of property objects, each with name and value. Use an empty string for value if not needed.

`Hippo.Targeting.TargetGroupTextField`

Text field for editing a target group. Subclasses should implement convertPropertiesToValue and convertValueToProperties to convert between property arrays and string values.

Extends: Ext.form.TextField

Methods:

convertPropertiesToValue(Array properties): String
Converts an array of property objects to a string value. The default implementation returns an empty string.
- properties (String): Array of property objects, each with name and value.
- Returns: String value for the user to edit.
convertValueToProperties(String value): Array
Converts a string value to an array of property objects. The default implementation returns an empty array.
- value (String): User-entered value.
- Returns: Array of property objects, each with name and value. Use an empty string for value if not needed.

`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 method to transform an array of property objects into rendered data. See Ext.grid.Column.renderer.
editor (Ext.form.Field, optional): Optional form field for editing target group properties. The value provided to setValue and returned by getValue is an array of property objects (name and value), not a string.
targetGroupColumn (Object, optional):
Instead of specifying a renderer and editor directly, you can provide a configuration object for a column that defines the editor and renderer. The object must include the xtype property for the target group column class, and can include other properties for the constructor. Using renderer and editor directly is recommended for simplicity.

Default:
```
{
 xtype: 'Hippo.Targeting.PropertyNamesColumn'
}
```
visitorCharacteristic (Object, optional):
Configuration object for the visitor characteristic. Must include the xtype property for the visitor characteristic class, and can include other properties for the constructor. If omitted, no visitor characteristic is shown.

Default:
```
{
 xtype: 'Hippo.Targeting.VisitorCharacteristic'
}
```

`Hippo.Targeting.TargetingDataPropertyCharacteristic`

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

Extends: Hippo.Targeting.VisitorCharacteristic

Properties:

targetingDataProperty: Name of the property to use from the targetingData object.

`Hippo.Targeting.TermsFrequencyCharacteristic`

Visitor characteristic for characteristics backed by com.onehippo.cms7.targeting.collectors.AbstractTermsFrequencyCollector. Reads the targetingData.termFrequencies property and uses a comma-separated list of term names as the target group name. Subclasses can override getTermName to customize the display name for each term. The returned target group properties include a property name for each term.

Extends: Hippo.Targeting.VisitorCharacteristic

`Hippo.Targeting.VisitorCharacteristic`

Base class for visitor characteristics. A visitor characteristic inspects a targetingData object and returns a target group. The structure of targetingData matches the getters of the TargetingData Java object created by the characteristic's collector. Subclasses should override isCollected, getTargetGroupName, and getTargetGroupProperties.

Extends: Ext.util.Observable

Methods:

isCollected(targetingData): Boolean
Returns true if the targetingData object contains the characteristic; otherwise, returns false.
getTargetGroupName(targetingData): String
Returns the human-readable name of the target group.
getTargetGroupProperties(targetingData): Array
Returns an array of property objects (name and value) for the target group. Use an empty string for value if not required.