Visitor groups and custom criteria in EPiServer

In this post we look at how to create new custom criteria for defining visitor groups in EPiServer.

  • 24 October 2011
  • 0

Introduction to visitor groups

Visitor groups were introduced with EPiServer CMS 6 R2 and enable categorization of visitors to your site in order to adapt site content for groups of users.

A visitor group is technically an arbitrary number of visitor group criteria which define the group. A site visitor that matches enough of these criteria is considered part of the visitor group.

Visitor groups can be used to specify that specific content within rich-text content (XHTML properties edited through the TinyMCE editor) should be visible to specific groups of users.

However, visitor groups are implemented all across the latest R2 releases of EPiServer products, meaning you can use it with add-ons such as EPiServer Composer to heavily adapt site content and layout for specific user groups. If B2B Adapt is used, you could for example make specific site content visible for users that come from certain types of businesses, for example companies in the automotive industry. That is powerful.

Creating a new visitor group

Visitor groups are created in the EPiServer UI by going to Visitor Groups on the CMS tab:

Visitor Groups menu option on the CMS tab

To create a new visitor group we simply click the Create button:

Creating a new visitor group

We give our visitor group a name and and an optional description:

Giving a visitor group a name and description

If we look on the right side we see available visitor group criteria:

Available visitor group criteria

We can simply drag and drop these to start defining our visitor group:

Adding a new visitor group criterion

If we were to add additional visitor group criteria we could specify that a certain threshold should be met in order for a visitor to be considered part of a visitor group. By default all criteria must be met.

Setting match requirements for a visitor group

When we’re done we simply click Save, and we’ll see our newly created visitor group:

List of created visitor groups

Specifying personalized content on a page

Now we can select specific content on our site…

Defining personalized content in TinyMCE

…and click the Personalized Content button…

Personalized Content plugin in TinyMCE

…which allows us to select which visitor group(s) this content should be visible to:

Selecting visitor groups for content in TinyMCE

We can now see that this part of the content is specific to the People in France visitor group:

Personalized content block in TinyMCE

Previewing personalized content

The personalized content will now only be visible to visitors in France. So, by default the content will not be displayed:

Previewing personalized content

However, we can select a visitor group to preview the page as it will be displayed to visitors within a specific visitor group:

Previewing content as a specific visitor group

Create a new custom visitor group criterion

EPiServer ships with a set of default visitor group criteria available when creating new visitor groups, but to really take advantage of personalization custom visitor group criteria should be implemented to match your organization’s requirements.

For this example we’ll develop a criteria for categorizing visitors according to whether or not a specific cookie exists in the session. One usage scenario could be to check if a cookie exists which says that the visitor has previously completed a purchase on the website, ie a returning customer.

Add assembly references

Add references to the EPiServer assemblies EPiServer.ApplicationModules and System.ComponentModel.Composition (the version shipped with EPiServer CMS). Since we want to use attributes for server-side validation (more on this later) we also add a reference to System.ComponentModel.DataAnnotations (standard .NET version).

Assembly references required for developing custom visitor group criteria

Creating the settings and criterion classes

All visitor group criteria require a settings class and a criterion class. The settings class is used to persist any settings available to editors when creating new visitor groups. The criterion class contains the logic to determine whether or not a user belongs to the visitor group.

Let’s create our two classes in a suitable folder structure:

Creating a criterion and a settings class

Implement the settings class

The only setting required for this criterion is the cookie name we should look for.

First, we make our CookieExistsCriterionSettings class inherit the CriterionModelBase class:

Inheriting the CriterionModelBase class

Next we add a public property to allow editors to specify the cookie name (we make the setting required by making use of a data annotation attribute, which is why we referenced the System.ComponentModel.DataAnnotations assembly earlier):

Adding a criterion settings property

If you need custom validation logic when a criterion is saved you can make your settings class implement the IValidateCriterionModel interface (this is optional). By implementing that interface’s Validate method you can customize how settings are validated before a criterion can be saved for a visitor group.

The abstract CriterionModelBase class requires us to implement the Copy() method. Since we’re not using any complex reference types we can simply implement it by returning a shallow copy like so (see this EPiServer tech note for more information on this):

Implementing the required Copy method

So, this is our complete CookieExistsCritertionSettings class:

public class CookieExistsCriterionSettings : CriterionModelBase
    public string CookieName { get; set; }
    public override ICriterionModel Copy()
        return ShallowCopy();

Implementing the criterion class

To start us off we’ll make our CookieExistsCriterion class inherit the abstract CriterionBase class with our settings class as the type parameter:

Inheriting the CriterionBase class

Next we add a VisitorGroupCriterion attribute to set the category, name, and description of our criterion (for more available VisitorGroupCriterion properties, see the tech note on EPiServer World):

Adding a VisitorGroupCriterion attribute

The abstract CriterionBase class requires us to implement an IsMatch() method which determines whether or not the current user matches this visitor group criterion. In this case we should check if a specific cookie exists based on the criterion settings:

Implementing the IsMatch method

So, our rather trivial criterion class looks like this in its entirety:

   Category = "Technical",
   DisplayName = "Cookie Exists",
   Description = "Checks if a specific cookie exists")]
public class CookieExistsCriterion : CriterionBase<CookieExistsCriterionSettings>
    public override bool IsMatch(IPrincipal principal, HttpContextBase httpContext)
        return httpContext.Request.Cookies[Model.CookieName] != null;

Note that we access the criterion settings instance through the Model property.

Testing the new criterion

First, create new visitor group which makes use of our new cookie criterion. We’ll set the cookie name to “.EPiServerLogin”, the name of the cookie created when a user logs in to EPiServer:

Adding a cookie exists criterion

First, select some content in TinyMCE that should only be displayed to users currently logged in to EPiServer (there are obviously better ways of doing this, but for the sake of demonstration we’ll go for this approach):

Defining personalized content in TinyMCE

Next, click the Personalized Content button and select the new EPiServer User visitor group:

Specifying visitor groups

This content will now only be displayed to users logged in to EPiServer:

Personalized content placeholder in TinyMCE

After publishing the page we see this:

Personalized content being displayed

However, if we log out of EPiServer…

Logging out from EPiServer

…we’ll no longer see the personalized content:

Personalized content not displayed


Unable to implement the IsMatch method of the CriterionBase class

If your project won’t compile, and the error messages says that the inherited abstract member IsMatch has not been implemented, make sure to check out this post on why the abstract CriterionBase class cannot be implemented.

Visitor groups not showing up in TinyMCE

If you don’t see any visitor groups when trying to specify personalized content in TinyMCE, make sure you’re running Internet Explorer or Firefox (the supported browsers). If you’re running for example Chrome no visitor groups will be visible. Thanks Stein-Viggo Grenerse for pointing this out to me! :)

Additional resources

There’s a tech note on developing custom visitor group criteria on EPiServer World which covers using separate MVC views for editing criteria, as well as additional implementation options.

You can download the EPiServer CriteriaPack from Codeplex (also available on NuGet) for additional visitor group criteria, for example to create a visitor group based on the visitor’s IP address:

Create a visitor group based on an IP range