Customize Visitor Analysis UI

The right-side part of the visitor analysis UI, which shows the details of the selected visitor, can be customized completely. It is possible to rearrange the existing UI components, and to include your own UI components that display visitor data collected by a custom collector .

Configuration

A custom visitor details panel class can be configured at:

/hippo:configuration/hippo:frontend/cms/hippo-targeting/visitor-details-panel
- plugin.class = ...

The default plugin class is com.onehippo.cms7.targeting.frontend.VisitorDetailsPanel.

The plugin class itself will look something like this:

VisitorDetailsPanel.java:

@ExtClass("Example.VisitorDetailsPanel")
public class VisitorDetailsPanel extends BaseVisitorDetailsPanel {

    public VisitorDetailsPanel(IPluginContext context,
                               IPluginConfig config) {
        super(context, config);
        add(JavascriptPackageResource.getHeaderContribution(
                      VisitorDetailsPanel.class, "VisitorDetailsPanel.js"));
        // add more resources here, e.g. for custom CSS.
    }

}

The layout of the visitor details panel is specified in the Javascript class. The default layout looks like:

VisitorDetailsPanel.js:

Ext.namespace('Example');

Example.VisitorDetailsPanel = Ext.extend(Hippo.Targeting.BaseVisitorDetailsPanel, {

    constructor: function (config) {
        Ext.apply(config, {
            items: [
                {
                    xtype: 'Hippo.Targeting.Journey'
                },
                {
                    xtype: 'Hippo.Targeting.Spacer'
                },
                {
                    xtype: 'Hippo.Targeting.VisitorDetailsRightColumn',
                    items: [
                        {
                            xtype: 'Hippo.Targeting.MatchingSegments'
                        },
                        {
                            xtype: 'Hippo.Targeting.VisitorCharacteristics'
                        }
                    ]
                }
            ]
        }
        Example.VisitorDetailsPanel.superclass.constructor.call(this, config);
    }
});

UI Components

The following ExtJS components are available when creating your own visitor details panel. The name of each component is also its xtype. For each component, we list the most important targeting-specific properties.

Hippo.Targeting.Journey

Shows the customer journey of the visitor, i.e. all visited URLs.

Extends: Ext.grid.GridPanel

Hippo.Targeting.MatchingSegments

Shows the segments with which the selected visitor has a match. For each segment, the name and match percentage are shown.

Extends: Ext.grid.GridPanel

Hippo.Targeting.PersonaStore

Wrapper around a Hippo.Targeting.VisitorDetailsStore that provides easy access to the data of matched segments.

Extends: Ext.data.JsonStore

Hippo.Targeting.Spacer

Invisible component that only takes up a square of screen space. Can be used to create a visible gap between components.

Extends: Ext.BoxComponent

Properties:

• size( int)
• The width and height of the spacer in pixels. Default: 39

Hippo.Targeting.TermsFrequencyChart

Shows a pie graph for a set of terms and their frequency.

Extends: Ext.Panel

Properties:

• characteristic ( String) The name of a characteristic backed by an AbstractTermsFrequencyCollector

• fieldName ( String) The name of the field to in the visitorDetailsStore to use. Default value: the characteristic name.

Hippo.Targeting.VisitorCharacteristics

Shows all visitor characteristics of all characteristic plugins that have the configuration property visitor.characteristic.visible set to ' true', and for which targeting data has been collected for the selected visitor. The latter is determined by the method isCollected of the visitor characteristic implementation of the characteristic plugin.

Extends: Ext.grid.GridPanel

Hippo.Targeting.VisitorDetailsRightColumn

The right column in the default layout of the visitor details panel. Its a panel with an anchor layout. The items of the panel will be wrapped in an internal Ex.Container to ensure a nice vertical scrollbar when not enough vertical screen space is available.

Extends: Ext.Panel

When no ' items' property is configured, the column will be empty. The default width is 332 pixels.

Hippo.Targeting.VisitorDetailsRightColumnPanel

Convenience base class for custom panels in the right column in the default layout of the visitor details panel. It is a normal Ext panel with some little tweaks to make it look consistent in the right column. For example, it will have a small gap between the title and body, and a collapse button in the top-right corner.

Extends: Ext.Panel

When no ' items' property is configured, the panel will be empty.

Hippo.Targeting.VisitorDetailsStore

Store around the REST response from ' /site/_targeting/visitors/<visitorID>/details'. The store contains a single record with a field for the targeting data of each characteristic. The field's name is the characteristic ID. Besides the targeting data for all characteristics, the store also contains the field ' personaScores' that contains the segments a visitor matches with.

Since the default configuration contains the characteristics ' city', ' country', and ' pageviews', the fields available by default in every record are:

• 'city': the city the visitor comes from

• 'country': the country the visitor comes from

• 'pageviews': the set of visited URLs

• ' personaScores': an array of Objects that represent the segments a visitor matches with. These data are used by the Hippo.Targeting.PersonasStore.

Extends: Hippo.Targeting.JsonStore

Events:

• changevisitor( String visitorId)
  Called when a user selects a new visitor in the list of visitors.
  visitorId: the ID of the new visitor.

• loaddetails( Ext.data.Record record)
  Called when new visitor details have been loaded into the store.
  record: contains the loaded data

• cleardetails()
  Called when no visitor details are available. This means no visitor is selected, or no details could be loaded.

The visitor details panels creates a visitor details store itself with the Ext storeID ' visitordetails'. The visitor details store can therefore be retrieved by other UI components via:

var visitorDetailsStore = Ext.StoreMgr.lookup('visitordetails');

Custom UI components

Any custom ExtJS component can be included in a custom visitor analysis panel. Such a custom component will most likely get the visitor details store in its constructor, and subscribe to its events ( changevisitor, loaddetails, and cleardetails) for notifications about new visitor data to show. For example:

var visitorDetailsStore = Ext.StoreMgr.lookup('visitordetails');
visitorDetailsStore.on('loaddetails', function (record) {
    var myCharacteristicData = record.get('mycharacteristic')
    // TODO: display data
}, this);
visitorDetailsStore.on('cleardetails', function () {
    // TODO: show 'no data available' somehow
}, this);

Custom components can also trigger the creation of a new target group in the 'Characteristics' tab by firing a ' storetargetgroup' event.

This event takes the following parameters:

• characteristic ( String): the name of the characteristic to create the targetgroup in

• name ( String): the name of the new targetgroup

• properties ( Array): the array of property objects that define the property names and values of the new targetgroup

For example:

Example of creating a new characteristic in code:

var name = "New Target Group";
var properties = [
    {
        name: 'Foo',
        value: 42
    },
    {
        name: 'Bar',
        value: 23
    }
];
self.fireEvent('storetargetgroup', 'mycharacteristic', name, properties)

Firing the event will switch the focus to the 'Characteristics' tab and open the editor of the ' mycharacteristic' characteristic with the provided name and properties. Note that the new target group will not be persisted until the user actually clicks the 'Save' button of the target group editor. Saving the new target group in the example as-is would create the following node structure in the repository:

/targeting:targeting/targeting:characteristics
          /mycharacteristic/<some generated target group node name>
- jcr:primaryType = targeting:targetgroup
- targeting:name = New Target Group
- targeting:propertynames = Foo
                            Bar
- targeting:propertyvalues = 42
                             23