Loading...
Area: Episerver CMS
Applies to versions: 10 and higher

Example: Creating custom criteria for defining visitor groups

Recommendations [hide]

(Thanks to Ted & Gustaf for this example.)

In this example, you develop a criteria for categorizing visitors according to whether a specific cookie exists in the session. One usage scenario could be to check for a cookie that says that the visitor has previously completed a purchase on the website; that is, is a returning customer.

The example uses the following steps:

  1. Creating the settings and criterion classes
  2. Implementing the settings class
  3. Implementing the criterion class
  4. Testing the new criterion

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 visitor belongs to the visitor group.

You should create the two classes in a suitable folder structure:

Implementing the settings class

The only setting required for this visitor group criterion is the cookie name you should look for.

  1. First, make the CookieExistsCriterionSettings class inherit the CriterionModelBase class:
    public class CookieExistsCriterionSettings : CriterionModelBase
  2. Add a public property to let editors specify the cookie name:
    [Required]
    public string CookieName { get; set; }
  3. 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 saving a criterion for a visitor group.

    The abstract CriterionModelBase class requires you to implement the Copy() method. Because you are not using complex reference types, you can implement it by returning a shallow copy as shown (see Developing custom visitor group criteria for more information):

    public override ICriterionModel Copy()
    {
       return ShallowCopy();
    }

This is the complete CookieExistsCriterionSettings class:

public class CookieExistsCriterionSettings : CriterionModelBase
{
    [Required]
    public string CookieName { get; set; }

    public override ICriterionModel Copy()
    {        
         return ShallowCopy();
    }
}

Implementing the criterion class

  1. Make the CookieExistsCriterionclass inherit the abstract CriterionBaseclass with the settings class as the type parameter:
    public class CookieExistsCriterion : CriterionBase<CookieExistsCriterionSettings>
  2. Add a VisitorGroupCriterion attribute to set the category, name, and description of our criterion (for more available VisitorGroupCriterion properties, see the Developing custom visitor group criteria):
    [VisitorGroupCriterion(   
       Category = "Technical",
       DisplayName = "Cookie Exists",
       Description = "Checks if a specific cookie exists")]
  3. The abstract CriterionBase class requires you to implement an IsMatch() method which determines whether the current user matches this visitor group criterion. You should check if a specific cookie exists based on the criterion settings:
    public override bool IsMatch(IPrincipal principal, HttpContextBase httpContext)
    { 
        return httpContext.Request.Cookies[Model.CookieName] != null;
    }

The criterion class appears as follows:

[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: You access the criterion settings instance through the Modelproperty.

Testing the new criterion

To test the criterion, create a new visitor group using the new cookie criterion.

  1. Set the cookie name to .EPiServerLogin, the name of the cookie created when a user logs in to Episerver:

  2. Select some content in the editor that should only be displayed to users currently logged in to Episerver.  (See the Episerver User Guide for information about applying personalization to content.)

  3. Click Personalized Content  PersonalizedContent.png and select the new Episerver User visitor group.

    This content is now only displayed to users logged into Episerver:

    After publishing the page, you see this:

    However, if you log out of EPiServer, you no longer see the personalized content.

Do you find this information helpful? Please log in to provide feedback.

Last updated: Nov 09, 2016

Recommendations [hide]