Customize Visitor Analysis UI

Warning: The example on this page applies to Bloomreach Content version 17.1 and earlier. Starting with version 17.2, the UI uses Angular by default instead of ExtJS. For information about customizing the Angular-based UI, see the Characteristics documentation.

You can fully customize the right-side panel of the visitor analysis UI, which displays details for the selected visitor. You can rearrange existing UI components and add custom components to display visitor data collected by your own collectors.

Configuration

Configure a custom visitor details panel class at the following JCR location:

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

By default, the plugin class is com.onehippo.cms7.targeting.frontend.VisitorDetailsPanel.

A typical custom plugin class looks 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 additional resources here, such as custom CSS.
    }

}
copy

The layout for the visitor details panel is defined in the associated JavaScript class. The default layout is as follows:

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);
    }
});
copy

In brXM 11.1, the ExtJS class Hippo.Targeting.MatchingPersonas was renamed to Hippo.Targeting.MatchingSegments. The original class remains for backward compatibility but is deprecated and will be removed in version 12.

UI Components

The following ExtJS components are available for use in custom visitor details panels. The xtype of each component matches its name. Key targeting-specific properties are listed for each component.

Hippo.Targeting.Journey

Displays the visitor's customer journey, including all visited URLs.

Extends: Ext.grid.GridPanel

Hippo.Targeting.MatchingSegments

Displays the segments that match the selected visitor. Shows the name and match percentage for each segment.

Extends: Ext.grid.GridPanel

Hippo.Targeting.PersonaStore

A wrapper around Hippo.Targeting.VisitorDetailsStore that provides simplified access to matched segments data.

Extends: Ext.data.JsonStore

Hippo.Targeting.Spacer

An invisible component that occupies a square area on the screen. Use this to create spacing between components.

Extends: Ext.BoxComponent

Properties:

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

Hippo.Targeting.TermsFrequencyChart

Displays a pie chart for a set of terms and their frequencies.

Extends: Ext.Panel

Properties:

• characteristic (String): Name of a characteristic backed by an AbstractTermsFrequencyCollector.
• fieldName (String): Field name in the visitorDetailsStore to use. Defaults to the characteristic name.

Hippo.Targeting.VisitorCharacteristics

Displays all visitor characteristics for plugins where the visitor.characteristic.visible property is set to true and targeting data has been collected for the selected visitor. The characteristic plugin’s implementation determines whether data is collected, using the isCollected method.

Extends: Ext.grid.GridPanel

Hippo.Targeting.VisitorDetailsRightColumn

Represents the right column in the default visitor details panel layout. This is a panel with an anchor layout. Items are wrapped in an internal Ex.Container to provide a vertical scrollbar when needed.

Extends: Ext.Panel

If the items property is not configured, the column is empty. Default width: 332 pixels.

Hippo.Targeting.VisitorDetailsRightColumnPanel

A base class for custom panels in the right column of the visitor details panel. This is a standard Ext panel with minor adjustments for consistent appearance, such as spacing between the title and body and a collapse button in the top-right corner.

Extends: Ext.Panel

If the items property is not configured, the panel is empty.

Hippo.Targeting.VisitorDetailsStore

A store for the REST response from /site/_targeting/visitors/<visitorID>/details. The store contains a single record with a field for each characteristic’s targeting data. The field name matches the characteristic ID. The store also includes a personaScores field containing the segments matched by the visitor.

By default, the configuration includes the following characteristics: city, country, and pageviews. The available fields are:

• city: Visitor's city
• country: Visitor's country
• pageviews: Set of visited URLs
• personaScores: Array of objects representing matched segments. Used by Hippo.Targeting.PersonasStore.

Extends: Hippo.Targeting.JsonStore

Events:

• changevisitor (String visitorId): Triggered when a user selects a new visitor.
  visitorId: ID of the new visitor.

• loaddetails (Ext.data.Record record): Triggered when new visitor details are loaded.
  record: Contains the loaded data.

• cleardetails(): Triggered when no visitor details are available (no visitor selected or details could not be loaded).

The visitor details panel creates a visitor details store with the Ext storeID visitordetails. Other UI components can retrieve this store as follows:

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

Custom UI Components

You can include any custom ExtJS component in a visitor analysis panel. Typically, a custom component receives the visitor details store in its constructor and subscribes to its events (changevisitor, loaddetails, and cleardetails) to update its display when visitor data changes. For example:

var visitorDetailsStore = Ext.StoreMgr.lookup('visitordetails');
visitorDetailsStore.on('loaddetails', function (record) {
    var myCharacteristicData = record.get('mycharacteristic')
    // Display the data as needed
}, this);
visitorDetailsStore.on('cleardetails', function () {
    // Display a 'no data available' message
}, this);
copy

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

Parameters for the event:

• characteristic (String): Name of the characteristic to create the target group in.
• name (String): Name of the new target group.
• properties (Array): Array of property objects defining property names and values for the new target group.

Example code to create a new target group:

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

Firing this event switches focus to the 'Characteristics' tab and opens the editor for the specified characteristic with the provided name and properties. The new target group is not persisted until the user clicks the 'Save' button in the target group editor. Saving the new target group creates 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]
copy