Custom Campaign Selection

Info: This feature is available in brXM 13.1.0 and later.

Overview

You can implement a custom heuristic to select which campaign to serve when multiple campaigns are active at the same time.

Default Behavior for Concurrent Campaigns

When multiple campaigns are running simultaneously for the same channel, Bloomreach Content uses a default selection heuristic. By default, the system serves the campaign with the shortest running period to visitors.

For example, if today is February 13 and the following campaigns are active:

1. Campaign 1: Started February 12, ends February 28
2. Campaign 2: Started February 9, ends February 14
3. Campaign 3: Started February 7, ends February 28

Campaign 2 is selected because it is active and has the shortest duration. This is the default campaign selection logic.

You can override this logic by implementing a custom heuristic. For instance, you might want to serve different campaigns based on visitor location, such as showing one campaign to users in the US and another to users in Europe.

Implementing a Custom Campaign Selector

You can inject a single custom campaign selector per HST Site web application by providing a custom HstSiteProvider implementation. Register this implementation as a Spring bean in an XML file located at:

src/main/resources/META-INF/hst-assembly/overrides

For example, in custom-hst-site-provider.xml:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd">

  <bean class="com.myproject.campaigns.LocationBasedHstWebSiteProvider"/>

</beans>
copy

Your custom class must implement org.hippoecm.hst.container.site.HstSiteProvider. The following example shows a provider that selects campaigns based on visitor location:

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

import com.onehippo.cms7.services.wpm.project.Project;
import com.onehippo.cms7.services.wpm.project.ProjectService;
import com.onehippo.cms7.services.wpm.project.ProjectState;

import org.hippoecm.hst.configuration.site.HstSite;
import org.hippoecm.hst.container.site.HstSiteProvider;
import org.hippoecm.hst.core.request.HstRequestContext;
import org.onehippo.cms7.services.HippoServiceRegistry;

public class LocationBasedHstWebSiteProvider implements HstSiteProvider {

    private final ProjectService projectService;

    public LocationBasedHstWebSiteProvider() {
        projectService = HippoServiceRegistry.getService(ProjectService.class);
    }

    @Override
    public HstSite getHstSite(final HstSite core, 
                              final Map<String, HstSite> branches, 
                              final HstRequestContext requestContext) {

        if (branches.isEmpty()) {
            return core;
        }

        final List<Project> eligibleCampaigns = new ArrayList<>();
        for (Project project : projectService.getProjects().values()) {
            if (ProjectState.RUNNING.equals(project.getState())) {
                eligibleCampaigns.add(project);
            }
        }

        final String ip = HstRequestUtils
                          .getFarthestRemoteAddr(requestContext.getServletRequest());
        // TODO implement your own geoIpService returning a Location object
        final Location location = geoIPService.getLocation(ip);

        final String contentinentCode = location.getContinentCode();

        for (Project eligibleCampaign : eligibleCampaigns) {
            
            // if there is a continent match with project name, serve that campaign
            if (contentinentCode.equals(eligibleCampaign.getName())) {
                
                final HstSite hstSite = branches.get(eligibleCampaign.getId());
                if (hstSite == null) {
                    return core;
                }
                return hstSite;
            }
        }
        
        // no continent match....serve either some eligibleCampaign or return core

        return core;
    }
}
copy

This example selects a campaign based on the visitor's continent, using a custom geoIpService to determine location from the IP address. Adjust the logic to match your specific campaign selection requirements.