Content personalization in Kentico cloud

Content personalization in Kentico cloud

If you are following my blog, you probably noticed that the last few posts were targeted at Kentico Cloud and its marketing features. My post today is about personalization, but it is more aimed at developers. I'll show you how to setup a simple personalization for your site.

If you are new to Kentico Cloud development, I recommend checking this article by Bryan Soltis before you start:

More on Kentico blog:

In order to perform content personalization with Kentico Cloud platform, we need to set it up in our MVC application. To do so, navigate to the API Keys section in Kentico cloud administration. You will find the section containing the Personalization API key.

Copy the key using the button and store it as an accessible key in your MVC application (e.g. under appSettings section in the web.config file)

    <add key="webpages:Version" value="" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    <add key="ProjectId" value="YOUR_PROJECT_KEY_HERE" />
    <add key="PersonalizationApiKey" value="YOUR_API_KEY_HERE" />

Next, we need to add the tracking code to the site. You'll see the script tag for tracking code right next to the Personalization API key in API keys section in Kentico Cloud administration. The section covered in red is your Project ID. You can add this script tag to the shared layout inside the head element.

NuGet Packages

In order to work with the tracking information in your controllers, you need to install the KenticoCloud.Personalization package. If you're working with an MVC project, install the KenticoCloud.Personalization.MVC package. However, if you're working with ASP.NET Core, install the KenticoCloud.Personalization.AspNetCore package. These packages add extension methods which allow you to query the Kentico Cloud Personalization API.

For example, if we want to find out when a contact visited the site for the first time, we need the contact's Personalization UID. By having the KenticoCloud.Personalization.MVC package installed, it's as simple as retrieving it from the request.


private string PersonalizationUID
        return this.Request.GetCurrentPersonalizationUid();

Once we have the Personalization UID, we can poll the Personalization API to see when the current contact visited the site for the first time.

In order to work with the Personalization API, we need to instantiate the PersonalizationClient. We can do so by creating a variable which instantiates it using the PersonalizationApiKey we've set up earlier. For example:

private static readonly PersonalizationClient PersonalizationClient = new PersonalizationClient(ConfigurationManager.AppSettings["PersonalizationApiKey"]);

The PersonalizationClient constructor takes the API key provided by the Kentico Cloud administration interface, and we're getting the API key from the settings. Alternatively, the key could have been directly provided in the constructor.

Validating a viewer's first visit

In this example, we'll show how to check when a contact visited the site for the first time. We've used Kentico's Dancing Goat site. If two hours or more have passed since the contact's first visit, we'll show them a banner offering them 50% off their first purchase. This banner will be displayed only on the home page.

To do this, we need to modify the HomeController. In the Index method, right below retrieving of the page content, we'll first add an “if” to check if we have the personalization user ID. This ID will be null in case it's a first-time visit.

if (!string.IsNullOrWhiteSpace(PersonalizationUID))
    var firstVisit = await PersonalizationClient.GetFirstVisitAsync(PersonalizationUID);

If you recall, the PersonalizationUID property is set to return the personalization user ID from the user's request.

Once we've retrieved the first visit, we can compare it to the current time to check if the promo banner for the 50% discount should be displayed.

ViewBag.ShowPromoBanner = GetFirstVisitDifference(firstVisit.VisitDateTime);

GetFirstVisitDifference does a simple subtraction of two dates to get the difference between the first visit date and time and the current date and time.

private bool GetFirstVisitDifference(DateTimeOffset firstVisit)
    var now = DateTimeOffset.UtcNow;
    var span = now.Subtract(firstVisit);
    return span.Hours >= 2;

The reason why we're working with DateTimeOffset.UtcNow instead of DateTimeOffset.Now is simply because the first visit date is always returned in UTC (+00:00). In order to have the correct calculation, the current date needs to be in UTC as well.

As noticed earlier, the result from this function is stored in ViewBag.ShowPromoBanner. This allows us to perform a simple if check on the Razor view in order to determine whether to show the promo banner or not.

    <section class="banner-section" style="background-color:#B24143;text-align:center;padding-top:15px; min-height:0">
        <h2 class="banner-heading" style="font-size:36px">Get 50% off first purchase</h2>
        <div class="banner-text" style="margin: 0 auto">
            <p>You have 50% off first purchase. Go to our <a href="/product-catalog/coffees?promo=50off">store</a> to find out more.</p>

If two hours or more have passed since the contact's first visit, this will be displayed:

On the other hand, if the contact is visiting the site for the first time or if the 2 hours mark hasn’t passed yet, the user sees this page:

In addition to the first visit, the Personalization API allows you to retrieve the following data:

  • Current contact session, where it started from (referrer URL), start time and the actions performed during the session
  • Location of the contact, in form of country, city and state
  • Usual contact's location, in form of country city and state
  • Average number of actions performed in a session, total number of contact's visit on the site
  • All the contact's recorded actions, filterable by type of action
  • Last date of contact's visit

P.S. I would like to thank my co-workers Marko and Tea for helping me with this blog post. Because of my tight schedule, they did most of the job.