DEV Community: Dmitry Bastron

Activity logging with Xperience by Kentico

Dmitry Bastron — Tue, 26 Sep 2023 11:58:26 +0000

Introduction

In our previous post, we explored activity tracking data modeling principles and common pitfalls. If you missed it, catch up here. In this article, we'll dive into practical implementation in your Xperience by Kentico project. We'll guide you through setting up a custom activity type and show you how to log visitor activities effectively.

Setting Up the Example: Selling Property Search

Let's implement one of the custom activity types that was mentioned in the previous post - Selling property search. We aim to log this activity whenever a website visitor searches for a property for sale. If the visitor interacted with any filters, then some additional context information should be captured as well:

property location: postcode area, city or district
property type: house, flat, etc.
price range
number of bedrooms
status: available or sold

Creating a custom activity type

First of all, we need to create our custom Activity type via Xperience by Kentico interface. This can be done in Digital Marketing > Contact Management > Activity Types section of Xperience by Kentico admin:

Remember the code name of the custom activity type - SellingPropertySearch - this will be used later in the code.

Logging activity

There are two main methods to log visitor activity in Xperience by Kentico - server-side and client-side.

The main difference is that server-side activity tracking happens as part of the request execution pipeline before the result is returned to the visitor, and client-side happens after the page is returned to the visitor.

Client-side logging

For most activity logging scenarios, we recommend employing client-side logging. This ensures that activities are logged only after the visitor has seen the rendered page, preventing false-positive tracking triggered by crawlers or bots. Additionally, certain user interface interactions, like button clicks, can only be logged on the client side.

Consider this code snippet to log our custom activity when a visitor lands on a search results page for properties on sale:

@using Kentico.Activities.Web.Mvc

@* Registers the script that allows custom activity logging *@
@Html.Kentico().ActivityLoggingAPI()

...

<script>
    function trackSalesSearch() {
        kxt('customactivity', {
            type: 'SellingPropertySearch',
            value: '', // Keep it blank for now, we will add some context later
            title: 'Property search for sale'
        });
    }

    // Add an event listener to track the activity after the page load
    window.addEventListener('load', trackSalesSearch);
</script>

Server-side logging

In some cases, like dynamic Ajax requests, server-side tracking is more suitable. Imagine a visitor landing on a search results page, then applying various filters, and triggering a request to the backend, resulting in new properties matching the filter criteria appearing. Xperience by Kentico provides three options to accomplish this:

Manually insert ActivityInfo object

You can manually create and save an ActivityInfo object into the database, as shown below:

var activity = new ActivityInfo
{
    ActivityCreated = DateTime.Now,
    ActivityType = "SellingPropertySearch",
    ActivitySiteID = siteId,
    ActivityContactID = ContactManagementContext.CurrentContactID
};
activity.Insert();

However, this method has its drawbacks, such as always logging the activity irrespective of global settings and cookie consent, and not populating extra fields automatically.

Using standard ICustomActivityLogger

Another option is to utilize Kentico's implementation of the ICustomActivityLogger interface:

using CMS.Activities;

private readonly ICustomActivityLogger customActivityLogger;

...

var salesPropertySearchActivityData = new CustomActivityData() {
    ActivityTitle = "Property search for sale",
    ActivityValue = ""
};

customActivityLogger.Log("SellingPropertySearch", salesPropertySearchActivityData);

This method respects cookie consent and populates extra activity fields but can become unwieldy if you have numerous custom activity types with unique logic.

Implementing CustomActivityInitializerBase

For more streamlined activity logging, especially when dealing with multiple custom activity types, it's recommended to inherit activity type implementations from the CustomActivityInitializerBase base class:

public class SellingPropertySearchActivityInitializer : CustomActivityInitializerBase
{
    private readonly string activityValue;
    private readonly int activityItemId;

    public SellingPropertySearchActivityInitializer(string activityValue = "", int activityItemId = 0)
    {
        this.activityValue = activityValue;
        this.activityItemId = activityItemId;
    }

    public override void Initialize(IActivityInfo activity)
    {
        activity.ActivityTitle = "Property search for sale";
        activity.ActivityValue = activityValue;
        activity.ActivityItemID = activityItemId;
    }

    public override string ActivityType => "SellingPropertySearch";

The actual logging part of the code will then look like this:

var service = Service.Resolve<IActivityLogService>(); // or retrieve it from DI container
var activityInitializer = new SellingPropertySearchActivityInitializer("value");
service.Log(activityInitializer);

Beware server-side caching

One critical consideration to keep in mind is server-side caching. If the activity logging code is part of a widget or component with output caching enabled, the activity will only be logged the first time the page is opened. Subsequent requests for the same page will return the cached widget, bypassing the tracking code.

Attaching context data

We've successfully logged a simple property search activity, but now it's time to enhance it with the context data mentioned at the beginning of this article. Specifically, we want to include location, price range, and other relevant details.

For each activity, we have four spare fields to attach context:

ActivityItemID - integer identifier of whatever "primary" object from DXP database you would like to relate to this activity: location or office is a good example
ActivityItemDetailID - yet another integer identifier to relate something "secondary", e.g. the property itself
ActivityValue - free text field where we can put any additional information
ActivityComment - same as previous, another free text field

Creating a custom class

Initially, you might consider creating a separate container to store this context information, such as a Module Custom Class. Then, you can save an integer reference to this object in the ActivityItemID or ActivityItemDetailID fields.

Start by creating a custom class from Development > Modules > Classes interface:

Add the following fields:

Generate a strongly-typed C# class for your module custom class following the documentation's instructions.

Now, we can modify the activity logging code as follows:

var propertySearchAttributes = new PropertySearchAttributesInfo()
{
    PropertyType = "Flat",
    Location = "London",
    PriceFrom = 350000,
    PriceTo = 500000,
    BedroomsFrom = 2,
    BedroomsTo = 3,
    Status = "Available"
};
propertySearchAttributes.Insert();

var service = Service.Resolve<IActivityLogService>();
var activityInitializer = new SellingPropertySearchActivityInitializer("", propertySearchAttributes.PropertySearchAttributesID);
service.Log(activityInitializer);

We can query the joined result of our logging via SQL:

SELECT *
FROM OM_Activity a
    INNER JOIN Custom_PropertySearchAttributes psa
        on a.ActivityItemID = psa.PropertySearchAttributesID
WHERE a.ActivityType = 'SellingPropertySearch'

From the technical perspective, it looks great because the data connected to the activity is decoupled from the activity itself. It can be processed, amended, or queried separately.

The reality though sounds much more pragmatic: this will never be the case. When marketers require this activity info, they always need the whole thing with all the context information available. For example, based on activities they may want to create a dynamic contact group with those who were searching for properties for sale in London to send out some communication for these people when there are new interesting properties available.

However, evaluating a connected object from the Custom_PropertySearchAttributes table to check the Location field would necessitate an additional SQL query, potentially impacting performance.

In the current version of Xperience by Kentico this method is also unavailable and we can only inspect data stored within ActivityValue field:

Structured XML

The alternative solution is to store serialized XML or JSON in ActivityValue field.

We only need a couple of things to make this work. First is a POCO-model:

[Serializable]
public class SalesSearch
{
    public string PropertyType { get; set; }
    public string Location { get; set; }
    public int PriceFrom { get; set; }
    public int PriceTo { get; set; }
    public int BedroomsFrom { get; set; }
    public int BedroomsTo { get; set; }
    public string Status { get; set; }
}

Then a generic method to serialize this object into XML string, like this:

public static string SerializeToXml<T>(T obj)
{
    var settings = new XmlWriterSettings
    {
        OmitXmlDeclaration = true,
        Indent = false
    };

    using (StringWriter stringWriter = new StringWriter())
    using (XmlWriter xmlWriter = XmlWriter.Create(stringWriter, settings))
    {
        var xs = new XmlSerializerNamespaces();
        xs.Add("", "");
        var serializer = new XmlSerializer(obj.GetType());
        serializer.Serialize(xmlWriter, obj, xs);
        return stringWriter.ToString();
    }
}

And finally our tracking code would be:

var propertySearchAttributes = new SalesSearch
{
    PropertyType = "Flat",
    Location = "London",
    PriceFrom = 350000,
    PriceTo = 500000,
    BedroomsFrom = 2,
    BedroomsTo = 3,
    Status = "Available"
};

var service = Service.Resolve<IActivityLogService>();
var activityInitializer = new SellingPropertySearchActivityInitializer(SerializeToXml(propertySearchAttributes));
service.Log(activityInitializer);

As a result, this would be the XML in ActivityValue column in OM_Activity table:

<SalesSearch>
    <PropertyType>Flat</PropertyType>
    <Location>London</Location>
    <PriceFrom>350000</PriceFrom>
    <PriceTo>500000</PriceTo>
    <BedroomsFrom>2</BedroomsFrom>
    <BedroomsTo>3</BedroomsTo>
    <Status>Available</Status>
</SalesSearch>

This approach will allow our marketers to accomplish their task of setting up a dynamic contact group with buying prospects from London:

Similar effect can be achieved with client-side tracking as well. We just need to withdraw this XML into the view with our tracking code:

@using Kentico.Activities.Web.Mvc

@* Registers the script that allows custom activity logging *@
@Html.Kentico().ActivityLoggingAPI()

@{
    var propertySearchAttributes = new SalesSearch
    {
        PropertyType = "Flat",
        Location = "London",
        PriceFrom = 350000,
        PriceTo = 500000,
        BedroomsFrom = 2,
        BedroomsTo = 3,
        Status = "Available"
    };
}
...

<script>
    function trackSalesSearch() {
        kxt('customactivity', {
            type: 'SellingPropertySearch',
            value: '@SerializeToXml(propertySearchAttributes)',
            title: 'Property search for sale'
        });
    }

    // Add an event listener to track the activity after the page load
    window.addEventListener('load', trackSalesSearch);
</script>

Conclusion

In this article, we've explored the practical implementation of activity tracking in Xperience by Kentico, focusing on the "Selling Property Search" custom activity type as an example.

For most cases, the recommended implementation is client-side tracking, ensuring accuracy after the page rendering. Finally, to enhance logged activities with context data, we suggested using structured XML or JSON in the ActivityValue field.

By following these techniques, you can effectively track and gather insights from visitor activities, enhancing your marketing strategies.

Mastering advanced tracking with Kentico Xperience

Dmitry Bastron — Tue, 15 Aug 2023 13:20:37 +0000

In the world of Digital Experience Platforms (DXPs), understanding and harnessing the power of data is key to unlocking success. In this blog post series, we will take you on a journey through a real-life scenario of implementing advanced tracking and analytics using Kentico Xperience 13 DXP. Whether you are working on a project with Xperience by Kentico or Kentico Xperience 13, the activity tracking principles remain consistent, making this information relevant for both.

Very often, the process of building websites goes through the challenges of budget restrictions and pressing deadlines. As a result of multiple tough prioritization calls, tasks like personalized user experience, marketing automation, visitor segmentation, and advanced tracking are usually not making the MVP launch of the project.

Gotcha 0: Tracking Trumps All Marketing Features

Data is the modern-day gold, and without detailed tracking from the very beginning, you risk missing out on valuable insights. Only building a solid foundation of data collection ensures all your marketing efforts, like segmentation, automation, and personalization, can reach their full potential in the future.

Gotcha 1: Going Beyond Out-of-the-Box Tracking

While Kentico Xperience 13 and other DXPs offer default activity tracking, it's not enough to fully comprehend the business context of your website. Injecting context into the tracked activities becomes your responsibility to gain deeper insights into visitor interactions.

With the enabled default activity tracking Kentico Xperience tracks multiple activity types automatically, such as:

Page visits. In the activity log, you will have the URL of the visited page and the referer URL (the page the user visited just before, what will be included there is defined by referer policy). However, there is no information regarding the context of content on the visited page.
Form submissions. This activity provides a bit more information, including a link to a form submission data and the type of the form. But if there was a generic form used on many pages, the context of the page is not included here.
E-commerce events. Products added to the basket, purchases, basket abandonment. This is probably the most advanced area of standard tracking because it includes a lot of data about products. But not the page context where it was performed on the website.

There is a common pattern here - the context of the visited page is missing.

To explain this in more detail, let's have a look at a real-life scenario we implemented recently with Kentico Xperience 13:

Website for one of the top real-estate agencies in the UK operating on a franchising model.
More than 100 offices advertising their properties for sale and to rent.
Different types of properties - homes, flats, commercial, etc.
Geolocation search feature to find a property in chosen city, postcode area, etc.

Gotcha 2: Unveiling User Interests with Page Visits

Page visits offer more than just a measure of visitor traffic. Understanding which specific pages users engage with can provide valuable insights into their interests, in our case, such as property type, location, price range, and status. Augmenting page visits with this additional information enriches your tracking data, leading to more informed decisions.

In our example, landing on property details page reveals:

Property is for sale or to rent
Location of property
Price
Property type (home, flat, commercial, etc)
Status (available now or in the future, already sold/let, etc)

From the search results page we could gather very similar insights:

Buy or rent filter
Region filter, where the property is located
Price range
Property type
Status

Ideally, all this valuable information should be tracked in addition to a page visit activity.

Gotcha 3: Making Analytics Actionable

Collecting data is only the first step, but making it actionable is where the real value lies. To achieve effective marketing automation, the activity data must be captured within your DXP. However, if your primary focus is reporting on the data and then applying actions manually, platforms like Google Analytics may suffice.

Below are the examples of reports that business could be interested in our example. These reports can be achieved in either of systems - Kentico Xperience or Google Analytics:

How many users are looking to buy or rent properties
How price range adjusts over time
What number of bedrooms is the most popular on the market
What offices perform the best in terms of leads

However later it can evolve into something more sophisticated, improving the visitor's experience based on the analytics. Supporting these cases would be easier if the analytical data is stored in the DXP:

If the user searched property for sale in a particular region, then suggest properties nearby
If they have seen N number of properties to rent, personalize their homepage to showcase more rental properties
If they have searched properties within a specific price range, then prioritize similarly priced properties on listing pages

Gotcha 4: Plan Personas First

Now we have a list of additional data to be tracked. Shall we go ahead and implement it? Not precisely. Although the data makes perfect sense now, there are multiple ways we can achieve these tracking requirements.

Before diving into implementing additional tracking information, it's essential to consider your website personas. By tailoring the tracking to individual personas, such as purchasers, landlords, renters, and vendors from our example, you can capture relevant data that aligns with their unique behavior. This targeted approach enhances user experience and optimizes marketing efforts.

From our example the main personas and their typical journeys were:

Sally, the purchaser. Is looking to buy a new property. Typically they would:
- Visits bying landing page
- Performs a few searches for properties for sale, providing their region, price range, type and size of the property
- Visits a number of property pages for sale
- Submits arrange a viewing form for the most interesting properties
- Adds those into favourites
Mike, the landlord. Is looking to let his property:
- Submits request a valuation (to rent) form
- Searches for already let properties in the past, to check how efficient estate agents are in the area they live
- Visits letting landing page
John, the renter. Is looking to rent a property:
- Performs a few searches for the properties to rent, providing their region, price range, type and size of the property
- Visits a number of property pages to rent
- Submits arrange a viewing form for the most interesting properties
- Visits rentals landing page
James, the vendor. Is looking to sell a property, and then potentially buy or rent another:
- Submits request a valuation (for sale) form
- Searches for already sold properties in the past, to check how efficient estate agents are in the area they live
- Visits selling landing pages
- Downloads terms and fees documents
Lisa, the franchisee prospect. Is looking to invest into opening a new branch:
- Visits franchising blog
- Subscribes to franchising newsletter
- Fills franchising contact form

Gotcha 5: Crafting the Ideal Data Structure

The list above is a starting point of custom activities we want to track and here is what can be customized when a new custom activity type is created in Kentico Xperience 13 (or Xperience by Kentico):

ActivityType - this is the main unique identifier of custom activity type
ActivityItemID - integer identifier of whatever "primary" object from DXP database you would like to relate to this activity: location or office is a good example
ActivityItemDetailID - yet another integer identifier to relate something "secondary", e.g. the property itself
ActivityValue - free text field where we can put any additional information
ActivityComment - same as previous, another free text field

In a nutshell we have one string unique identifier, two integer ID fields, and two free text fields where we can store any relevant info regarding tracked activities. Next is to define how many custom activity types we need, and what additional information is written in the rest of the fields.

There are two extremes in modeling data for custom activity types:

Extremely specific: Creating a new type for every specific activity you are tracking. Following this principle, there will be "search for properties to sale, from A to B price, in London," "visit of property details page, to rent, in Manchester" and so on. There will be many unique activity types in the system, and complimentary integer and string fields for each will not be utilized.
Extremely generic: Creating one generic custom type, like "estate agents custom activity," and storing as much additional information as we can in the 4 fields available. For example, in ActivityItemID, store the ID of the office if relevant; in ActivityItemDetailID, store the ID of the property; in ActivityValue and ActivityComment fields, store all the additional information serialized as XML or JSON. This can include whether this activity is "sales" or "lettings," price range, identifier of area search, sub-type of activity performed - search, page visit, download, etc.

Very often, if not always, these extreme approaches are not great, and we need to find some sweet spot in the middle.

Gotcha 6: Keeping Numbers Manageable

The rule of thumb here: keep the number of custom activity types manageable - between 10 and 25. Usually, you can park between these two numbers if you create a custom activity type for each combination of your main taxonomy comprising personas and a list of actions to be tracked.

In our estate agency example:

Main taxonomy - property interest:
- Selling
- Letting
Type of activity performed:
- Request valuation form submitted
- Request property viewing form submitted
- Property page visit
- Property search
- Property saved to favourites
- Property Search saved to favourites

As a result there will be 12 unique activity types, like: selling property page visit, letting property page visit, selling property search, letting property search, and so on.

One small but important detail worth noting here is that we could have avoided creating duplicates for both selling and letting in our example and stored selling or letting value in the details of the activity. However, this would have made the use of these activities inside other marketing features, like persona scoring rules or marketing automation, more complicated and less visual.

For example, when configuring persona scoring rules for a purchaser, we could either:

Select "visited selling property page" activity type
Or, select "visited property page", and configure further condition "where property page is selling"

The second option is less attractive because:

Further conditional checks could affect the performance on high traffic websites.
It's less visual in the DXP admin. In persona scoring rules list, activity log, and other places, these extra conditions are not displayed, hence you have to expand the specific rule to notice the difference.

Gotcha 7: Attaching More Context

Although custom activity gives you only 4 fields to fill, there are ways to inject more valuable context information.

Storing data in an attached object. Here we can create a structured object like module custom class, record all necessary context information inside it, then while logging activity object just store integer ID referencing this custom class.
Storing data in structured text format. Alternative option would be to prepare serialized context information as XML (or JSON) and storing it in one of the two text fields available in the activity object.

Conclusion

Mastering advanced tracking and analytics is essential for gaining valuable insights into user behavior and optimizing marketing efforts. By going beyond out-of-the-box tracking, understanding user interests with page visits, making analytics actionable, planning personas, crafting an ideal data structure, and attaching as much context as needed, you can create a comprehensive and effective tracking strategy for your website. Stay tuned for more insights in the next blog post in this series!