Customizing how statistics tracking scripts are loaded on pages when using EPiServer Find

Find injects 2 scripts on site pages in order to track search statistics. By default these scripts are requested from EPiServer CDN. In certain scenarios developer may need to tweak how tracking scripts are added on pages.

Prerequisites

EPiServer Find 8.10.x.x or later version packages should be installed on website.

Loading Find tracking scripts on Intranet websites

Customers may use EPiServer Find on Internal websites where site visitors don’t have access to the Internet, so tracking scripts cannot be loaded from CDN.

Possible solution can be hosting these tracking scripts in customer’s Intranet instead of loading scripts from CDN.

Hosting statistics tracking scripts in Intranet

Download the following scripts from EPiServer CDN. Version 8.10.0 is an example, grab scripts that correspond to EPiServer Find version installed on the website:

https://dl.episerver.net/8.10.0/epi-util/native.history.js
https://dl.episerver.net/8.10.0/epi-util/find.js

Remember to upgrade these scripts when upgrading EPiServer Find on website.

Overriding tracking script locations

Tell Find that scripts should be loaded form Intranet. Script locations can be overridden by defining client resources with corresponding names:

history.js script must be defined as “browserstate.history“
find.js script must be defined as “epi.find.trackingScript“

Specifying script URLs in module.config

The easiest way to define client resource is adding them in site module.config:

<?xml version="1.0" encoding="utf-8"?>
<module>
    ...
    <clientResources>
        ...
        <add name="browserstate.history" path="http://intranet/Scripts/native.history.js" resourceType="Script"/>
        <add name="epi.find.trackingScript" path="http://intranet/Scripts/find.js" resourceType="Script">
            <dependencies>
                <add name="browserstate.history" />
            </dependencies>
        </add>        
    </clientResources>
    ...
</module>

Script path value can be the path on the site or full URL.

Note that browserstate.history is defined as dependency for epi.find.trackingScript to ensure correct order of loading.

Implementing client resource provider in order to define script locations

Another way to define client resources is implementing client resource provider. This options can be useful if script URLs should be somehow resolved in code:

[ClientResourceProvider]
public class ClientResourceProvider : IClientResourceProvider
{
    public IEnumerable<ClientResource> GetClientResources()
    {
        return new[] 
        {
            new ClientResource
            {
                Name = "browserstate.history",
                Path = GetIntranetUrl() + "native.history.js",
                ResourceType = ClientResourceType.Script
            },
            new ClientResource
            {
                Name = "epi.find.trackingScript",
                Path = GetIntranetUrl() + "find.js",
                ResourceType = ClientResourceType.Script,
                Dependencies = new List<string> { "browserstate.history" }
            }
        };
    }
}

Loading Find tracking scripts when history.js is added in page templates

Another scenario could be running EPiServer Find on a website where history.js variation like jquery.history.js script is used in page templates. In this case injecting native.history.js script from EPiServer CDN gives error like “History.js Adapter has already been loaded”.

In order to solve this issue, history.js script that is used on website can be defined as a client resource and Find will inject this script instead of requesting native.history.js on CDN.

Defining history.js client resource

history.js script must be defined as “browserstate.history” client resource.

Specifying history.js URLs in module.config

Client resource can be defined in site module.config:

<?xml version="1.0" encoding="utf-8"?>
<module>
    ...
    <clientResources>
        ...
        <add name="browserstate.history" path="PathToMyScripts/jquery.history.js" resourceType="Script"/>
    </clientResources>
    ...
</module>

Where value is the path or full URL of history.js that is used on the site.

Defining history.js path in client resource provider

Another option is defining browserstate.history script in a client resource provider. Make sure that script name is defined as “browserstate.history“.

[ClientResourceProvider]
public class ClientResourceProvider : IClientResourceProvider
{
    public IEnumerable<ClientResource> GetClientResources()
    {
        return new[] 
        {
            new ClientResource
            {
                Name = "browserstate.history",
                Path = "ClientResources/Scripts/jquery.history.js",
                ResourceType = ClientResourceType.Script
            }
        };
    }
}

Again, this options can be useful if URL of history.js should be resolved in code.

What if you don’t want to load history.js using client resources framework

Probably there are some cases when loading history.js using client resources framework is not desirable. For example, history.js is bundled with other site scripts and you don’t want to load history.js separately. There is a workaround.

Define fake “browserstate.history” client resource with empty inline content:

[ClientResourceProvider]
public class ClientResourceProvider : IClientResourceProvider
{
    public IEnumerable<ClientResource> GetClientResources()
    {
        return new[] 
        {
            new ClientResource
            {
                Name = "browserstate.history",
                InlineContent = "",
                ResourceType = ClientResourceType.Script
            }
        };
    }
}

Now add your own history.js on pages as you want, but make sure that it is loaded before find.js script (by default required scripts are rendered at the bottom of the page, using something like @Html.RequiredClientResources(“Footer”)).

Dmytro Duk