Develop a Collector Plugin

Overview

Starting with version 17.2, the collector plugin extension point uses an Angular-based editor in the Experience manager. For earlier versions, custom ExtJS code was required. For details on ExtJS-based plugins, see Develop a Collector Plugin with ExtJS.

This guide describes how to develop a collector plugin for Bloomreach Content 17.2 or higher. The plugin enables you to override collector data using the Alter Ego feature in the Experience manager.

Use Case

Implement a collector plugin on Bloomreach Content 17.2+ to allow CMS users to override collector data via the Alter Ego functionality.

Alter Ego Functionality

The Alter Ego feature allows CMS users to impersonate a visitor with specific characteristics. In the Experience manager, the 'As viewed by' menu always includes the 'Alter Ego' option. When selected, the system collects targeting data while previewing the channel and displays targeted content accordingly. The 'Edit Alter Ego' button opens a window where users can override collected targeting data with specific values. For example, a user can select a particular location instead of using the location detected by the Relevance Module.

To enable data overrides, you must provide a collector plugin that allows editing the JSON representation of the targeting data. The Java collector plugin registers metadata and frontend options. The Alter Ego UI uses these options and the collector ID to display the appropriate editor.

This page outlines the steps to implement a collector plugin.

Configuration

Collector plugins are configured in the repository at:

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

Each collector plugin is defined in a child node of type frontend:pluginconfig. Name the node using the format collector-<ID of your collector>.

Each collector plugin node requires the following properties:

collector (String, required): The ID of the collector.
plugin.class (String, required): The fully qualified Java class name of the collector plugin.

You can define additional configuration properties to customize the plugin. These extra properties are passed to the Angular frontend as options and can be enriched in Java.

Example: GroupsCollectorPlugin

The Groups collector plugin allows users to modify the groups a visitor belongs to. The GroupsCollector returns group membership as a comma-separated string. The plugin presents a checkbox group, enabling selection of one or more groups.

The plugin consists of a Java class and a .properties file, or a set of language-specific properties files (for example, GroupsCollectorPlugin_nl.properties).

The following example is a simplified version of the GroupsCollectorPlugin from the Relevance Module.

Java Class

GroupsCollectorPlugin.java:

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.regex.Pattern;

import com.onehippo.cms7.targeting.frontend.plugin.CollectorPlugin;

import org.hippoecm.frontend.plugin.IPluginContext;
import org.hippoecm.frontend.plugin.config.IPluginConfig;
import org.onehippo.cms7.services.HippoServiceRegistry;
import org.onehippo.repository.security.SecurityService;

/**
 * Plugin for the groups collector. Available plugin properties:
 * <ul>
 * <li>groups: multi-value String property, each string specifies
 *     a selectable group</li>
 * </ul>
 */
@SuppressWarnings("unused")
public class GroupsCollectorPlugin extends CollectorPlugin {

    private final List<Pattern> excludes;

    public GroupsCollectorPlugin(final IPluginContext context,
                                 final IPluginConfig config) {
        super(context, config);

        final String[] excludesConfig = config.getStringArray("excludes");
        excludes = new ArrayList<>();
        if (excludesConfig != null) {
            for (String exclude : excludesConfig) {
                excludes.add(Pattern.compile(exclude));
            }
        }
    }

    @Override
    public void enrichFrontendOptions(final Map<String, Object> options) {
        options.put("groups", listGroups());
    }

    private List<String> listGroups() {
        final SecurityService securityService = HippoServiceRegistry.getService(SecurityService.class);
        final List<String> groups = new ArrayList<>();
        securityService.getGroups(0, 0).forEach(group -> {
            if (!isExcluded(group.getId())) {
                groups.add(group.getId());
            }
        });
        return groups;
    }

    private boolean isExcluded(final String group) {
        if (group.equals("everybody")) {
            return true;
        }
        for (Pattern exclude : excludes) {
            if (exclude.matcher(group).matches()) {
                return true;
            }
        }
        return false;
    }
}

Properties File(s)

The .properties file provides i18n labels. The key collector-description is displayed as the description of the collector in the 'Edit Alter Ego' window.

GroupsCollectorPlugin.properties:

collector-description=is in the user group

To support multiple languages, add language-specific files such as GroupsCollectorPlugin_nl.properties.

Java API

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

Base class for collector plugins.

Configuration properties:

collector (String, required): The ID of the collector.
plugin.class (String, required): The fully qualified Java class name of the collector plugin.

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

Enables editing the current day of the week.

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

Enables editing the visitor's location.

Configuration properties:

locations (multiple String): List of location strings shown as selectable options in the editor. Each string must use the format "city | country | latitude | longitude".

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

Enables editing the groups a visitor belongs to.

Configuration properties:

excludes (multiple String): List of regular expression patterns. Groups matching these patterns are excluded from the selectable options in the editor.

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

Enables editing the referrer URL.

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

Enables editing whether the visitor is new or returning.

Built-in Alter Ego Editors

Angular-based editors are available for several built-in collectors. If your custom collector does not use one of the following IDs: groups, documenttypes, engagement, dayofweek, returningvisitor, tracking, referrer, pageviews, or geo, the editor will display a JSON textarea for editing.

Upgrade Checklist for 17.2

To upgrade custom collectors for use with version 17.2, complete the following steps:

In the Java class:

Remove all @ExtClass annotations and ExtJS plugin classes.
Change the getIcon() method from protected to public.
Replace any onRenderProperties overrides with
public void enrichFrontendOptions(Map<String, Object> options).
Remove any renderHead overrides.
Remove unused imports.

Remove any ExtJS JavaScript or CSS resources previously added in renderHead.

In the associated properties file(s), remove entries used only by ExtJS JavaScript files.