31 votes

Personalisation Groups

Introduction

Personalisation Groups is an Umbraco package intended to allow personalisation of content to different groups of site visitors.  It comes with some document types, data types and custom property editors to allow you to define groups based on given criteria and an extension method on IPublishedContent to allow you to show or hide content according to these criteria in your templates.

It comes with a number of criteria, namely:

  • Authentication status
  • Cookie key presence/absence and value matching
  • Country (via IP matching)
  • Day of week
  • Number of site visits
  • Pages viewed
  • Querystring
  • Referral
  • Region (via IP matching)
  • Session key presence/absence and value matching
  • Time of day
  • Umbraco member group
  • Umbraco member profile field
  • Umbraco member type

And is extensible so you can write your own.

Please note this package is marked as beta, primarily as whilst it is being used by others, it's not yet been used in a production setting myself.

That said, I think it's reasonably solid and have had some good reports, so feel free to take a look and use as you see fit.

For more detailed information on use, extending the package, troubleshooting info or to review and/or contribute to the source code, see the documentation and source code repository at Github: https://github.com/AndyButland/UmbracoPersonalisationGroups

Using the package

Installation

Firstly install the package in the usual way.  

Once installed you'll find a few additional components:

  • Personalisation Groups Folder is a document type purely used to organise your personalisation groups.  By default you can create it at root and within it create further instances of itself.
  • Personalisation Group is a document type where the group itself is created.  You can place these inside the folders.  It comes with a single property called Group definition of a data type also provided with this package.
  • Personalisation group definition the data type provided to allow the definition of personalisation group, based on a new property editor provided in the dll installed with the package.
  • Personalisation group picker is an data type instance of the multi-node tree picker property editor, for the selection of groups for given piece of content

There's also a NuGet installer if you prefer to use that:

PM> Install-Package UmbracoPersonalisationGroups

However this will only install the dll, not the document types and data types.  As such I'd reccommend if you do want to use NuGet for ease of updates, do the following:

  • Install the package from our.umbraco.org
  • Then install from NuGet to get the dll as a package reference

Example usage

  • Within the Content section, create a root node of type Personalisation Groups Folder, called Personalisation Groups
  • Switch to Developer and find the Personalisation group picker data type.  Set the root node to be the node you just created.
  • Back to Content, as a child of the node you just created, create a node of type Personalisation Group called, for example, Weekday morning visitors
  • Set the Match option to All
  • Set the Duration option to Page (or., if you select other options here, the groups will become "sticky". For example if someone comes to your home page that's personalised based on a querystring parameter, if they then return to the page by default they will no longer match the group (as the querystring value is no longer there). But selecting Session or Visitor you can make the visitor stick to the group they matched originally).
  • Add a new criteria of type Day of week and tick the boxes for Monday to Friday.
  • Add a second criteria of type Time of day and add a range of 0000 to 1200
  • Save and publish
  • Now go to Settings and find the document type for a piece of content you want to personalise.  For example with the Fanoe Starter Kit you could select the Blog Post document type
  • Add a new field of type Personsalisation group picker with an alias of personalisationGroups
    If you don't like this alias you can use a different one, but you will also need to add the following appSetting key to your config file: <add key="personalisationGroups.groupPickerAlias" value="myCustomAlias"/> 
  • Back to Content again, find or create a page of this document type and pick the "Weekday morning visitors" personalisation group
  • Finally you need to amend your template to make use of the personalisation group via new extension method that will be available on instances of IPublishedContent, named ShowToVisitor(), as described below.

Templating

Personalising repeated content

A typical example would be to personalise a list of repeated content to only show items that are appropriate for the current site visitor.  Here's how you might do that:

  @foreach (var post in Model.Content.Children.Where(x => x.ShowToVisitor()))
{
   <h2>@post.Name</h2>
        }

With a little more work you can also personalise an individual page.  One way to do this would be to create sub-nodes of a page of a new type called e.g. Page Variation.  This document type should contain all the fields common to the parent page that you might want to personalise - e.g. title, body text, image - and an instance of the Personalisation group picker.

You could then implement some logic on the parent page template to pull back the first of the sub-nodes that match the current site visitor.  If one is found, you can display the content from that sub-node rather than what's defined for the page.  And if not, display the default content for the page.  Something like:

@{
var personalisedContent = Model.Content.Children.Where(x => x.ShowToVisitor()).FirstOrDefault();
string title, bodyText;
if (personalisedContent != null) 
{
title = personalisedContent.Name;
bodyText = personalisedContent.GetPropertyValue<string>("bodyText");
}
else 
{
title = Model.Content.Name;
bodyText = Model.Content.GetPropertyValue<string>("bodyText");
}
}

<h1>@title</h1>
<p>@bodyText</p>

Notes on particular criteria

Country

The country criteria uses the free GeoLite2 IP to country database which you can download from: http://dev.maxmind.com/geoip/geoip2/geolite2/ and made available by Maxmind.com.  It'll look for it in /App_Data/GeoLite2-Country.mmdb or at the path specified in the following appSetting:

    <add key="personalisationGroups.geoLocationCountryDatabasePath" value="/my/custom/relative/path"/>

Extending the package

Personalisation groups comes with a number of built-in criteria but may not have everything you want to use.  However it can be extended relatively easily.

One way to do this would be to use one of the "low-level" built-in criteria, such as the ones that look for a cookie or session value.  If your application code can set a given cookie or session key value when a particular action occurs you want to personalise on, you can just do that and use them.

Or you can create your own criteria.  This involves writing some server-side code that implements a given interface as well as some custom angular views and controllers.  There's more detail on this here: https://github.com/AndyButland/UmbracoPersonalisationGroups#how-to-extend-it

And several examples in the source code you can use for reference: https://github.com/AndyButland/UmbracoPersonalisationGroups/tree/master/Zone.UmbracoPersonalisationGroups/Criteria

 

Screenshots

Archived files

Documentation

Source code

Package owner

Andy Butland

Andy Butland

Andy has 1748 karma points

Package Compatibility

This package is compatible with the following versions as reported by community members who have downloaded this package:
Works on Umbraco Cloud
7.12.x (untested)
7.11.x (untested)
7.10.x (untested)
7.9.x (untested)
7.8.x (untested)
7.7.x (untested)
7.6.x (100%)
7.5.x (100%)
7.4.x (100%)
7.3.x (100%)
7.2.x (100%)
7.1.x (untested)
7.0.x (untested)
6.1.x (untested)
6.0.x (untested)

You must login before you can report on package compatibility.

Package Information

  • Package owner: Andy Butland
  • Created: 02/05/2015
  • Current version 0.3.4
  • .net Version 4.5
  • License MIT
  • Downloads: 3765

External resources