What is Click Tracking in EPiServer Find?

When a customer performs a search and subsequently clicks a search result, your website should be informing Find of this event.

Why is Click Tracking important?

There are two fundamental reasons:

• Quality of search results returned from Find
• Using statistics for continuous search optimisation

Find Relevancy Scores

The EPiServer Find algorithm will assign a relevancy score to each search result it deems to match the words in the search query. Search results are then by default ordered by the relevancy score.

Some of the factors taken into account in the EPi Find algorithm are as follows:

• Boost Weighting: the weighting you assign to fields in your search query. For example your query may stipulate that matches in the “Title” field are should be twice as relevant as the same matches in the “Description” field
• Term Frequency: number of occurrences of search term words within a result
• Inverse Frequency: measurement of how frequently words in a search term occur across the entire set of results. Words in the search query which occur in many potential results have a lower impact to the relevancy score than rare words across the result set.
• Number of keyword matches:search results which match all of the keywords in a search term will rank higher than those that match a subset

However a major part of how the EPi Finds algorithm assigns relevancy is the intelligence the platform gathers on click throughs. Search results that customers are frequently clicking for a search term will be assigned higher relevancy scores.

Find needs to know what results people are clicking.

Statistics

You’re marketing team should be using the Find Search Statistics interface to continually optimise results using Best Bets, Related queries, Synonyms and Autocomplete.

The cornerstone of this process is solid reporting.

If Click Tracking is not working, all search results will have a Click-through rate of 0% denying your marketing team of very valuable information.

Does Click Tracking not work out of the box?

If you’re using EPiServer Find Unified Search – Yes. Just enable Tracking on the search query. As long as you are injecting the EPi Client Resources in your root template (which you probably are!), then the JS injected handles all the rest.

If you’re not using Unified Search – No, you should read on…

How do i implement custom click tracking?

This excellent post from Henrik Fransas explains adding custom click tracking excellently:

https://world.episerver.com/blogs/Henrik-Fransas/Dates/2015/2/how-to-do-custom-query-and-click-tracking-with-episerver-find/

The only thing i will add is that sometimes we need to use the Find GetResult method to query the index. The GetResult methods supports returning extended data on the content type which we can set up in an initialisation module as follows with the MyCustomExtendedProperty() method being an simple static extension of the BaseProduct class.

[InitializableModule]
[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class SearchIndexInitialization : IInitializableModule
{
public void Initialize(InitializationEngine context)
{
SearchClient.Instance.Conventions.ForInstancesOf()
.IncludeField(x => x.MyCustomExtendedProperty());
}

public void Uninitialize(InitializationEngine context)
{
//Add uninitialization logic
}
}

Using GetResult the following method will add the HitId and HitType properties to your search results view model. I hope it comes in useful for someone!

public List AddStatisticsAndRelevancyToSearchResults(SearchResults searchResult) where T : ISearchResultViewModel
{
var searchResultsWithRelevancyScore = searchResult.Hits.Select(x =>
{
try
{
var result = _contentLoader.Get(x.Document.ContentLink);
x.Document.HitId = SearchClient.Instance.Conventions.IdConvention.GetId(result);
x.Document.HitType = SearchClient.Instance.Conventions.TypeNameConvention.GetTypeName(result.GetType());
}
catch (Exception e)
{
_logger.Error("Error thrown retrieving hit count from Find", e);
}
x.Document.RelevancyScore = x.Score;
return x.Document;
}).ToList();
return searchResultsWithRelevancyScore;
}

The goal is to create the most dynamic E-Commerce Category pages possible with Epi Commerce & Find.

First lets clarify the terminology. By category page i am referring to the EPi Commerce “NodeContent” type used to structure the product catalog.  Customers will be able to navigate the site using this category structure seeing the top relevant products at all points.

My project type is a Dynamics AX ERP to EPiServer Commerce integration using Avensia Storefront to manage the catalog synchronisation. More information on this type of integration is available here: Delivering Unified Commerce Solutions With Episerver Avensia Storefront And Dynamics For Finance & Operations

Using Avensia Storefront we can replicate the AX Product Catalog in the EpiServer Commerce Catalog. With this approach if our client publishes a new category and/or products in AX, within minutes that set up will be replicated in our EPiServer catalog.

The Category pages of an E-Commerce site are absolutely critical to get right as an optimal set up will provide the customer with an easy method of navigating the site while providing the functionality and information they need to find the product(s) they need. From an SEO perspective it’s also extremely important that crawlers can easily traverse the hierarchy and gain context.

Because categories are added dynamically, we have one category page implementation but the search faceting and product view should dynamically optimise based on the descendant products types of the current category and their attributes.

Take for example this simplistic catalog structure:

All Product Types inherit from a “BaseProduct” which contains common properties across the catalog.

Our Category Page inherits from Base Node

My requirement is:

• Category A – advanced facet filtering options for Product Type 1
• Category B – advanced facet filtering options for Product Type 2
• Category C – facets common to Base Product

Technical Set Up

The Category Controller inherits from ContentController<NodeContent> meaning that it gets hit on all page loads of Node Content. We are going to use a search service which is injected into the Category Controller and manages the communication with Find. The following sequence diagram will give you a feel for the flow.

Dynamically getting Child Content Types

My Search Service interface defines the following methods:

public interface ISearchService
{
  SearchResultsModel SearchFromCategory(NodeContent currentContent, string query, string sort = "", int page = 1, int? pageSize = null, List facetGroups = null);
  SearchResultsModel Search(NodeContent currentContent, string query, string sort, int page = 1, int? pageSize = null, List facetGroups = null, bool trackSearch = false) where T : BaseProduct;
}

In the SearchFromCategory method we need to find the descendant product types.

This query took a bit of figuring out and i have to thank the excellent community in Epi World for pointing me in the right direction:

https://world.episerver.com/forum/developer-forum/EPiServer-Search/Thread-Container/2019/1/using-termfacets-to-return-a-list-of-product-namespaces-under-a-node/#200943

The solution i arrived at is the following method which uses Find to get return all product types that are descendants of the current Node. To accomplish this “_Type” is included in the request where the indexed property will contain the entire type string.

public List GetProductTypesForCurrentCategory(NodeContent currentContent)
{

  // use Find to execute search with the content type id set as a facet
  var searchQuery = _findClient.Search()
    .Filter(x =>
     x.Ancestors().Match(currentContent.ContentLink.ToReferenceWithoutVersion().ToString()))
      .Take(0).TermsFacetFor(x => x.CommonType(), request => request.Field = "_Type")
      .StaticallyCacheFor(TimeSpan.FromMinutes(SearchConstants.ProductTypesCacheInMinutes))
      .GetContentResult();

  // extract the content type id's form the result
  var terms = searchQuery.TermsFacetFor(x => x.CommonType()).Terms;
  var productTypes = new List();

  // add returned types to list
  foreach (var typeNamespace in terms)
  {
    var type = Type.GetType(typeNamespace.Term);
    productTypes.Add(type);
  }  

  return productTypes;
}

The Search From Category can then be implemented where it customises search to a product type where possible or otherwise using the Base Product object

// Called from category page
public SearchResultsModel SearchFromCategory(BaseNode currentContent, string query, string sort = "", int page = 1, int? pageSize = null, List facetGroups = null)
{
  var productTypes = GetProductTypesForCurrentCategory(currentContent);

  if (productTypes?.Count == 1)
  {
    // get product type
    var productType = productTypes.First();
    // instantiate and invoke generic search
    var searchMethod = typeof(SearchService).GetMethod("Search", new [] {typeof(BaseNode), typeof(string), typeof(string), typeof(int), typeof(int?), typeof(List), typeof(bool) });

    if (searchMethod != null)
    {
      var genericSearch = searchMethod.MakeGenericMethod(productType);
      return genericSearch.Invoke(this, new object[] {currentContent, query, sort, page, pageSize, facetGroups, false}) as SearchResultsModel;
    }
  }
  // search for base type
  return Search(currentContent, query, sort, page, pageSize, facetGroups);
}

The generic Search Service in this solution is then built to customise facets and search results based on the type of product so this solution. Thats a large topic so happy to do another blog post on that!

Also note that this solution uses reflection and this might not always be the optimal implementation from a performance perspective. You could just as easily implement a factory method with a switch statement to map types to Search<T>() method invocations.

Although this post is quite trivial, EPiServer Content Approvals are a large step forward from the old functionality and as it’s relatively recent, there’s not a lot of posts out there on customising the engine. Most importantly i would have found this post useful had i found it last week!

My requirement is simple in that customers can upload images via an interface on the website product details page. On successful upload, these images are saved as a media asset in a Draft state. These assets contain properties associating it with both the product and customer who uploaded it.

The image will go through a content approval workflow before eventually being either published on the web site or rejected in which case we need to send an email to the customer to notify them of the rejection. Comments are mandatory in the Content Approval workflow on declining an Image so this comment will be included in the email.

There are Approval Engine Events that we can easily hook into and it is well documented in the EPiServer World:

https://world.episerver.com/documentation/developer-guides/CMS/Content/content-approvals/working-with-content-approvals/

Our image content type has properties linking it to the customer and product so we need to extract the media content reference from the event to do just about whatever we want. Getting that content reference should be the trivial bit…and it is…once you know what to do!

As detailed in the link above, each Approval Engine event provides us with an ApprovalEventArgs object providing us with the context.

Within this object we have the ApprovalId and ApprovalReference properties which we can use to query the approval repository to get us more details:

private void OnRejected(ApprovalEventArgs e)

{

var approvalRepo = ServiceLocator.Current.GetInstance();

IEnumerable approvalIds = new List() {e.ApprovalID};

var approvalItems = approvalRepo.GetItemsAsync(approvalIds);

The next bit is the bit that got me initially…

Approval Items Results contain an “Approval” object….However this Approval object does not contain the content reference of the item which the event is triggered for. To retrieve the ContentReference you need to cast the Approval to a “ContentApproval” which is derived from Approval.

var contentApproval = (approvalItems.Result.FirstOrDefault() as ContentApproval);

We can now use our contentApproval object to do just about whatever we want. See the code sample below:

using System.Collections.Generic;

using System.Linq;

using EPiServer;

using EPiServer.Approvals;

using EPiServer.Approvals.ContentApprovals;

using EPiServer.Framework;

using EPiServer.Framework.Initialization;

using EPiServer.ServiceLocation;

using EPiServer.WebApplication.Core.ContentTypes.Media;

namespace EPiServer.WebApplication.Infrastructure

{

[InitializableModule]

public class ApprovalEngineEvents : IInitializableModule

{

private IApprovalEngineEvents _approvalEngineEvents;

public void Initialize(InitializationEngine context)

{

_approvalEngineEvents = context.Locate.Advanced.GetInstance();

_approvalEngineEvents.Rejected += OnRejected;

}

private void OnRejected(ApprovalEventArgs e)

{

var contentLoader = ServiceLocator.Current.GetInstance();

var approvalRepo = ServiceLocator.Current.GetInstance();

IEnumerable approvalIds = new List() {e.ApprovalID};

var approvalItems = approvalRepo.GetItemsAsync(approvalIds);

var contentApproval = (approvalItems.Result.FirstOrDefault() as ContentApproval);

if (contentApproval != null)

{

var rejectedContent = contentLoader.Get(contentApproval.ContentLink);

if (rejectedContent != null)

{

string comment = e.Comment;

// get customer id from page data

// get product from page data

// send email to customer

}

}

}

public void Uninitialize(InitializationEngine context) => _approvalEngineEvents.Rejected -= OnRejected;

}

}