Profiling: Creating custom recognition rules

This article is about profile extensibility in Online Marketing Center. We will talk about how to customize the process of recognizing the visitor profile.

Getting started

Let's start by creating a new project inside Microsoft Visual Studio. Since the extensions that we are going to write don't require any external resources (like images, JavaScript- or CSS-files) we can choose a "Class library" as a project template:

Creating a project

To deploy our extensions we will need to copy the resulting .dll file into the /bin folder of our Dynamicweb installation. No additional tasks needs to be performed in order to register our extensions - the system will automatically find and instantiate them when it's needed.

Next step is to add references to Dynamicweb.dll and other assemblies that contain some APIs that we will need. These are the assemblies that you must reference within your project:

  1. Dynamicweb.dll
  2. Dynamicweb.Controls.dll
  3. Dynamicweb.Modules.dll
Make sure that the runtime/assembly versions are correct (minimum required runtime version is 4.0 and the minimum required assembly version is 8.0):

Adding references

Profile recognition

First, I'd like to explain what the profile recognition is and how it works. The profile recognition is a process of associating a visitor with one or several profiles that were created by the website administrator. Each profile consists of a name, an optional description and a set of rules that the visitor must (fully or partially) satisfy in order for the system to associate him/her with the given profile. There are several standard recognition rules (e.g. "Is logged in" which checks whether visitor is logged in or not, "Website" which checks for a target language/area, "Referrer" which checks the referrer URL and some others). What we will do is we will create a custom recognition rule called "Browser" which will check visitor's user agent name.

Custom recognition rules are simply public types that implement an interface Dynamicweb.Analytics.Profiles.Recognition.IRecognitionRule. This interface consists of two members:

  1. Dynamicweb.Analytics.Profiles.Recognition.RecognitionRuleConstraint Constraint { get; set; }
  2. bool ApplyRule(Dynamicweb.Analytics.Profiles.Recognition.RecognitionRuleContext context)
The first member (Constraint) is used to put some restrictions on how the website administrator can configure the rule. If it's set to null (Nothing in Visual Basic) then the rule will not have any configurable settings.

The second member (ApplyRule) is invoked by the system during the process of recognizing a visitor profile. The method takes an object of type Dynamicweb.Analytics.Profiles.Recognition.RecognitionRuleContext that provides various information about the current visit, current page, etc. The method returns a boolean value indicating whether the given visitor satisfies the rule.

Creating a custom recognition rule

The first thing that we will do is we will add a new class into our project. I called it "BrowserRecognitionRule". Make sure your class is public (has a "public" access modifier) and has a public parameterless constructor.

Next thing that we should do is we should decorate the class with some attributes that the system needs in order to present the rule to the user while editing a profile. There is one required attribute called Dynamicweb.Analytics.Profiles.Recognition.RecognitionRuleIdentity:

Custom recognition rule declaration

As you can see on a picture above I've alredy implemented the required interface. Let's see how it's done.

The first is Constraint property. Our rule will need some settings (e.g. a value that the user can set and that we will use to test the visitor's user agent name against). Since there are no any special requirements on which settings the rule needs we will use the default settings (static property Default on a Dynamicweb.Analytics.Profiles.Recognition.RecognitionRuleConstraint type):

Custom recognition rule initialization

Let's see how to implement the ApplyRule method. The procedure is also pretty straightforward here:

Custom recognition rule applying

As you can see I'm examining the visitor's information in order to retrieve the name of the browser that is used. Next, I need to try to determine whether the browser name matches the criterion configured by the website administrator. I don't have to do it manually because there is a utility type Dynamicweb.Analytics.Profiles.Recognition.RecognitionRuleUtility that exposes methods that can help validating some text against the given recognition rule constraint.

Testing our custom recognition rule

Compile the project and copy the resulting .dll file into the /bin folder of your website. Now let's go to administration interface and test our newly created recognition rule. Navigate to Online Marketing Center and create a new profile called "IE user". Notice that our recognition rule is now available in the list:

Custom recognition rule - backend

Select this rule (by dragging it from the list on the left to the list on the right or by simply doubleclicking it) and set the expected value to "IE" (which states for "Internet Explorer"). The corresponding values for Firefox, Safari and Chrome are "FF", "Safari" and "Chrome". Save your newly created profile.

In order for us to see what profiles did the visitor gain we will insert some global template tags into our master template. These tags output information about the primary and secondary profile:

Profiling - global template tags

Now open Firefox and navigate to website frontend. You will see that zero profile points were assigned to "IE user" profile. Now switch to Internet Explorer and open the same page in it. You will be associated with the "IE user" profile:

Custom recognition rule - result

Note that in my example I had 5 points for satisfying the "Browser" rule so the number that is displayed in brackets is "5". You might have a different setup for this profile so the number can be different.

As you probably know, profiles are just .xml file on disk so you can easily share your profile setups between solutions. But what you should remember is that if you have used some custom recognition rules and you want to use the profile based on these rules on another solution then you must also copy the .dll file that contains types for your custom recognition rules. Otherwise such profiles won't work.

Source code

You can download the C# project with the complete source code for this article from here: OMC extensibility - Profiles.