Personalisation in WebCenter Sites with the Engage framework

The engage framework is a powerful but little used framework for tailoring content on your site to specific groups of users (or a specific user if you have login capabilities). It comes as part of the WebCenter Sites install but sadly the documentation for it is pretty limited and client uptake of these fairly powerful features is not massive.

This blog will help you get started with Engage, working through an example so that you can deliver personalised content to visitors on your own site.

Types of Personalisation

Engage allows you to drive site Personalisation in two ways:

• User segmentation
• History tracking

User segmentation

User segmentation requires you to know something about the person browsing your site. This information can be obtained from having a site registration that requires a user to fill out some information about themselves or you could decide to infer it from other data, such as click-through from other sites or cookies from other sites with details of previous browsing history.

History tracking

History tracking involves recording which pages on your site the current user has visited and altering the site content based on assumptions about what content they would like to see. For example, if you have a site selling shoes and someone repeatedly visits the trainers section you could add a trainer promotion on the homepage for that user.

Collecting the data

WebCenter Sites has some special tags which allow us to collect data on site visitors and store it in the database. This data can then be utilised in combination with the recommendation asset to prioritise content on sections of the site or totally override promos and banners.

Visitor Attributes

Before we can start collecting information on our site visitors we have to define the kind of data we want to collect and tell WCS about it so it can store it in the DB. We do this through the asset type VisitorAttribute. This is a pretty simple asset type that just consists of a name, description and category.

Name is the only real important thing here as this is what you will reference in your JSP tags. Description is standard, and category is for organisation within the UI. This will come into play when you create your segments, which we’ll come to next.

Typically your visitor attributes will be things like: Age, Gender, Marital Status etc…

Segments

Once you have some information about your visitors you will need to group them into logical segments (unless you plan on providing custom content for every visitor which would be nigh on impossible!) Segments group your visitors allowing you to personalise content to the different groups. Typically a segment would be along the lines of:

• Young consumers
• Professional women
• Older men etc…

A segment is an asset type in WCS. To create a segment you will combine Visitor attributes with logical operators to define rules about what kind of site visitor fits in to a segment. For example, to create a segment that targets older gentlemen, we can create a segment asset called “Older Gents” and specify that site visitors belonging to this segment must have age greater than 45 and have gender equal to male.

Personalising the content

Once we have set up some visitor attributes to record and created some segments to group our users we can start creating some segment-specific content and using recommendation assets to control who sees it.

To utilise the data we’ve collected on our site visitors to provide a personalised experience, we need to re-work how we have written some of our jsp templates. First we need to identify where we want to add personalised content. For a simple example this would typically be a banner or promo on the homepage that advertises something on the site to specific users.

Now you’ve probably coded your template using standard tags, simply loading an attribute of an asset that contains a reference to the promo or banner and then passing the asset id and type to a relevant template to render it. In order to change this to deliver personal content two things need to change:

1. The asset model

We need to remove the single asset attribute and replace it with an attribute that contains a recomendation. Recommendation assets give us the ability to define multiple content assets that can be used in a particular slot on the site. We can add multiple assets of specified types to a recommendation and specify which should be delivered to a particular segement and which should be delivered to all users.

2. The Templates

Once we’ve changed our asset model we then need to change the templates that render the content. We now need to use the commerce context tags to load our recommendation assets and pick the correct content asset to render based on our current users segment.

A simple user segmentation example

Now we’ve had a brief introduction to the basic concepts of how personalisation can be achieved with engage I’m going to walk you through a simple example. Here we’ll add a personalised promo for ‘Young Dudes’ to the homepage of a website for a bar.

1. Lets define our segment and visitor attributes

We want to define a segment for ‘Young dudes’. So what defines a young dude? For a start they need to be male and secondly they need to be between a certain age range to be defined as young. Given this is going to be for a bar I think we can safely say the minimum age should be 18 and as for the maximum age I guess we can go with the BBC’s rule of 25 being the age at where you are no longer considered young. So we are going to define a segment that contains users who are male and who are between the ages of 18 and 25.

To create this segment we need to create the visitor attributes first.

1.1 Create the visitor attributes

First up lets create the attribute that will record the user’s gender:

i. Click content -> new visitor attribute (you might have to enable the Visitor attribute start menu for this.)

ii. Enter the form as follows: name -> gender, description -> gender, Category -> Personal Info (as discussed above this is just used for organising the display when creating segments)

iii. Alright we need another attribute for age so repeat the above steps but specify ‘age’ for name and description rather than ‘gender’, keep the category as Pesonal Info.

1.2 Create the user segment

Now we have our visitor attributes in place we can create our user segment based on them:

i. Click content -> new segment

ii. Enter the following details name -> Young Dudes, Description -> Young Dudes

iii. Now click the detail tab, this is where we describe our segment.

iv. Add gender as a visitor attribute we want to constrain against

v. Add age as another attribute we want to constrain against using AND logic

vi. Set the constrainst to match those of a young dude: gender = male, age between 18 and 25

vii. Hit save and we’ve created our segment!

2. Create our content

We need to have some actual content to provide to our personalised segment and we also need some content to show to our non-personalised users. For this example we will use a simple promo that will be placed on a homepage, but you can use any content type you have in your site. For our segment of ‘Young Dudes’ we are going to have a promo offering a 241 deal on jagerbombs, because we know all the young dudes love a jagerbomb.

We create the promo like so:

We also need some basic un-personalised content, that we will show to anyone not in the Young Dudes segment.

Create a basic promo like so:

3. Create the reccomendation asset

To utilise the personalisation features of engage we need to use the special asset type Recommendation. This asset takes multiple content assets, restricted by type if necessary, and allows us to set content to display by segment.

i. First lets give our recommendation a name: lets call it PromoListSingleSegment (I’m choosing this for descriptive clarity, but feel free to name it whatever you like)

ii. Second, lets restrict what assets can be added to our recommendation. Click the ‘Options’ tab and select your desired asset type from the ‘Pick Type’ drop down. Leave the other options as default. For this example our asset type is content – as this is the type our Promo definition belongs to – this will stop invalid content being added to this recommendation.

iii. Now lets add a segment to the recommendation. Click the ‘Detail’ tab and drag in our ‘Young Dudes’ segment to the ‘Segment Drop Zone’ on the recommendation asset.

iv. Drag our personalised promo into the ‘Young Dudes’ segment section of the reccomendation asset. You will notice there are two percentage boxes on the right hand side saying IN and OUT, these are the confidence levels to use when the user is in the segment and when they are out of the segment. For this example we are trying to keep things simple so lets set them so that if you are in the ‘Young Dudes’ segment you will always see the segment promo and if you are not then you never will: set IN to 100% and OUT to 0% (or you can just leave it blank).

v. Drag our regular content into the ‘If No Segments Apply’ section of the recommendation asset.

4. Code our templates to handle personalisation

All this set-up is great but it means nothing if our templates aren’t coded to record visitor data or to display personalised content. We need to make changes to our templates to achieve our desired result.

4.1 Recording visitor data

Without visitor data, we have nothing to base our personalisation on; every user looks the same to WCS. To record visitor data we use the <vdm:setscalar/> tag. I will leave up to you how to collect your visitor data, be it a form or a more implicit way but the main thing is you need to record the data to the WCS database using this tag.

<vdm:setscalar attribute="age" value='<%=ics.GetVar("age")%>'/>
<vdm:setscalar attribute="gender" value='<%=ics.GetVar("gender")%>'/>

For this example, let’s use a form that the user must fill out before accessing the site:

<input class="modal-state" id="modal-1" type="checkbox" />
<div class="modal">
    <label class="modal__bg" for="modal-1"></label>
    <div class="modal__inner">
        <label class="modal__close" for="modal-1"></label>
        <h2>Tell us about yourself!</h2>
        <p>
            We love to find out more about our customers, if you could take a couple of secs to tell us about yourself we'd really appreciate it
            and we might even chuck a few special deals for you!
        </p>
        <div class="form-horizontal">
        <satellite:form method="GET" id="personalisationForm">
            <fieldset>
                <!-- Form Name -->
                <!-- Text input-->
                <div class="form-group">
                  <label class="control-label col-sm-2" for="customerName">Name</label>
                  <div class="col-sm-6">
                    <input id="customerName" name="customerName" type="text" placeholder="enter your name" class="form-control" required="true">
                  </div>
                </div>
                <!-- Multiple Radios (inline) -->
                <div class="form-group">
                  <label class="control-label col-sm-2" for="gender">Gender</label>
                  <div class="col-sm-6">
                    <label class="radio-inline" for="gender-0">
                    <input type="radio" name="gender" id="gender-0" value="male" checked="checked"> male
                    </label>
                    <label class="radio-inline" for="gender-1">
                        <input type="radio" name="gender" id="gender-1" value="female"> female
                    </label>
                  </div>
                </div>
                <!-- Text input-->
                <div class="form-group">
                  <label class="control-label col-sm-2" for="age">Age</label>
                  <div class="col-sm-4">
                    <input id="age" class="form-control" name="age" type="text" class="input-medium" required="">
                  </div>
                  <div class="col-sm-4">
                    <input class="btn btn-default" type="submit" value="Submit">
                  </div>
                </div>
            </fieldset>
            <input id="pagename" type="hidden" name="pagename" value="ManifestoDemo/Personalisation/ProcessUserDetailsForm" />
            <input id="site" type="hidden" name="site" value='<%=ics.GetVar("site") %>'/>
        </satellite:form>
        </div>
    </div>
</div><!-- modal -->

In WebCenter Sites all form inputs, when submitted, get converted to ics vars that are accessible using ics.GetVar("blah") or, using the jsp tag <ics:getvar name="blah"/> so we can set our user data with the following code (this would need to be in an Element that the form submits to):

<%
    double custId = ((Math.random() * 100000) + 1); //Generate a random customerId
    String custIdStr = String.valueOf(custId);
%>
<vdm:setalias key="customerId" value='<%=custIdStr%>'/>

<ics:if condition='<%=ics.GetVar("customerName") != null && !ics.GetVar("customerName").isEmpty() %>'>
    <ics:then>
        <ics:logmsg msg='<%="Customer name is " + ics.GetVar("customerName") %>'/>
        <vdm:setscalar attribute="name" value='<%=ics.GetVar("customerName")%>'/>
    </ics:then>
</ics:if>
<ics:if condition='<%=ics.GetVar("age") != null && !ics.GetVar("age").isEmpty() %>'>
    <ics:then>
        <ics:logmsg msg='<%="Customer age is " + ics.GetVar("age") %>'/>
        <vdm:setscalar attribute="age" value='<%=ics.GetVar("age")%>'/>
    </ics:then>
</ics:if>
<ics:if condition='<%=ics.GetVar("gender") != null && !ics.GetVar("gender").isEmpty() %>'>
    <ics:then>
        <ics:logmsg msg='<%="Customer gender is " + ics.GetVar("gender") %>'/>
        <vdm:setscalar attribute="gender" value='<%=ics.GetVar("gender")%>'/>
    </ics:then>
</ics:if>
{
    "custId" : "<%=custIdStr%>" //Return the customerId in the response to be saved in the cookie.
}

In order to stop the user having to repeatedly fill out this form we can store the result in a cookie and then access the cookie each time to get the visitor data for a returning user.

4.2 Read the visitor data

Once we have set the data required for our segment we need to make sure we read the visitor data on every request so we can perform our personalisation checks. To do this we use the commercecontext tags to read the visitor attribute data, calculate which segment the current user is in, and which promotions they qualify for.

<commercecontext:calculatesegments/>
<commercecontext:calculatepromotions/>

As this needs to be done on every page request, and should in no way be cached, we should put this code in a wrapper element.

With our segments and promotions calculated we can now use the recommendations we created to successfully alter the content for different users. The tag we need to use for this is

<commercecontext:getrecommendations collectionid='<%=ics.GetVar("collectionId") %>' listvarname='<%=ics.GetVar("listVarName") %>' />

We pass it a collection id, which is the id of the recommendation asset which holds our content (both personalised and regular); and a listvarname, which is the name of the list variable that will be returned which will have the recommended content to display. The first item on the list is the most highly recommended, and the last the least recommended.

So it’s then just a case of looping through (or just taking the first item if you only want to display one piece of content) and rendering out the returned asset using the appropriate template.

<commercecontext:getrecommendations collectionid='<%=ics.GetVar("collectionId") %>' listvarname="filteredPromoList" />
<ics:if condition='<%=ics.GetList("filteredPromoList") != null && ics.GetList("filteredPromoList").hasData() %>'>
    <ics:then>
        <ics:listloop listname="filteredPromoList">
            <ics:listget listname="filteredPromoList" fieldname="assetid" output="promoId"/>
            <ics:logmsg msg='<%="Filtered promo Id is " + ics.GetVar("promoId") %>'/>
        </ics:listloop>
        <ics:listget listname="filteredPromoList" fieldname="assetid" output="promoId"/>
        <ics:listget listname="filteredPromoList" fieldname="assettype" output="promoType"/>
        <insite:calltemplate
        site="ManifestoDemo"
        c='<%=ics.GetVar("promoType") %>'
        cid='<%=ics.GetVar("promoId") %>'
        tid='<%=ics.GetVar("tid")%>'
        ttype="Template"
        tname="PromoPagelet"
        slotname="PromoSlotHomePage" title="Promos" field="Promo" emptytext="Drop a reccomendation here...">
      </insite:calltemplate>
    </ics:then>
</ics:if>

4.3 Test it out

You should now be able to hit your promo page, set different user data using the form we created, and it should alter the content you see on the site.

Conclusion

This was just a small insight into one aspect of the engage personalisation engine. We covered:

• Creating segments and visitor attributes to store information on our users and section them into marketable groups
• Collecting and storing visitor data using the <vdm:* tag family
• Using the engage engine to workout the segment a site visitor belongs in and what promotions they qualify for, with: `<commercecontext:calculatesegments/>` and `<commercecontext:calculatepromotions/>`
• Creating personalised content with recommendations and displaying this to targeted users using `<commercecontext:getrecommendations/>`

You can also do all sorts of stuff with history attributes and we can do more complex content selection using recommendations and the confidence attribute. Those are more advanced topics but hopefully this post was enough to give you a good start with the often misunderstood engage personalisation framework.