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:
To create a new visitor group we simply click the Create button:
We give our visitor group a name and and an optional description:
If we look on the right side we see available visitor group criteria:
We can simply drag and drop these to start defining our visitor group:
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.
When we’re done we simply click Save, and we’ll see our newly created visitor group:
Specifying personalized content on a page
Now we can select specific content on our site…
…and click the Personalized Content button…
…which allows us to select which visitor group(s) this content should be visible to:
We can now see that this part of the content is specific to the People in France visitor group:
Previewing personalized content
The personalized content will now only be visible to visitors in France. So, by default the content will not be displayed:
However, we can select a visitor group to preview the page as it will be displayed to visitors within 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).
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:
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:
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):
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):
So, this is our complete CookieExistsCritertionSettings class:
public class CookieExistsCriterionSettings : CriterionModelBase
{
[Required]
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:
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):
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:
So, our rather trivial criterion class looks like this in its entirety:
[VisitorGroupCriterion(
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:
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):
Next, click the Personalized Content button and select the new EPiServer User visitor group:
This content will now only be displayed to users logged in to EPiServer:
After publishing the page we see this:
However, if we log out of EPiServer…
…we’ll no longer see the personalized content:
Troubleshooting
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:
