Make Better Decisions with Usage Analytics Part 2

Earlier this month I demonstrated how to plug Azure Application Insights logic into an Office 365 or SharePoint Master Page to track common usage events. This gets you very basic, but still critical, information about usage on your site such as the number of views per page, session length, entry and exit pages, and info about the client. This is useful, but only a slight improvement over native SharePoint and Office 365 reporting.  Further, most of the time I am looking for something more specific, for example, which refiners or refinement panels are used on my Search Result page.
There is a limited amount of real estate on the results page and while it is common to add refiners for everything that seems relevant, or even to target refinement panels to audiences, I still want to know whether or not users actually use the refiner that I just added. Usage analytics can steer efforts when you have no other insights, or augment first-hand data like user surveys or interviews with concrete numbers.
For example, your Test users may report that they spend as much time working with Presentations as they do with Spreadsheets, but if you want to improve the rendering for both content types and you know that users browsing data filter by “Excel” twice as often as they filter by “PowerPoint” you might prioritize the work on the Excel experience over PowerPoint for the short-term.  Besides, it never hurts to have a good quantitative reason for prioritization in the absence of other reasons.

Even Dilbert is aware of this problem- but you don’t have to take the pill, just have a good answer.

In the last post we got started with four quick steps:

1. Create an Azure Application Insights (AI) instance
2. Acquire the Javascript for sending events to your AI instance
3. Insert Javascript into Master Page for your site
4. Use the new “AI Master Page”

…and I mentioned that you could add one simple statement to create a custom event:

appInsights.trackEvent(“Your Event Here”);

Today, we will add this one simple statement to a refinement template in Office 365 to gather feedback on refiner usage by repeating steps 3 and 4 with Display Templates for refinement.

Note: this post assumes that you are working in a site collections where you have already updated the Master Page like we covered in the last post.

If you have never edited a Display Template before, then you might want to review here first.

To get started like we did with the Master Page, download the Default Filter template from your Filter gallery.

Filters folder in the Master Page Gallery
Filters folder in the Master Page Gallery

I also highlighted the Search folder as a reminder that your filter templates are not in the same folder as item Display Templates. The file we edit here is Filter_Default.html.

Open it for editing and change the title and filename to something meaningful. On line 266 you should see a div tag for refinement items. Note that it already features an onclick event which fires some JavaScript. We can add our statement in the same tag but we need to encode the quotes in our statement so as to not confuse the browser.

Replace the onclick statement in the tag with this one:

onclick="_#= aOnClick =#_ appInsights.trackEvent("Refine by _#=ctx.RefinementControl.propertyName=#_ ");"

In the “your event here” part of the statement we have added a context property(ctx), propertyName, which will provide the name of the Managed Property which was refined on.

Save the template, upload, and publish it as we did with the Master Page in part 1.  Again, as with the Master Page we need to utilize our new template on a page which displays refiners, like the standard results page for your Search Center. You can either change the template for the desired property refiner to use your new one, or add a new refiner using the new template.  You can choose the template that is used for each property when you edit the Refinement webpart on your page.

Select a Refiner Template from the list
Select a Template

Save your changes to the webpart, then the page,then publish, and watch your new metrics start rolling in.

Not so tough, but this only tells me what properties were filtered on, not which items were clicked as I promised earlier.
The event logic is already in the right place to capture which item was clicked. To get the actual item we only need to change the variable that gets stuffed into the event. Replace the ctx.RefinementControl.propertyName variable with refinementName, like this:
("Refine by _#=refinementName=#_ ")
…and you will log exactly the item that was clicked such as Excel, PowerPoint, etc, and your reports will start to look like this one:

Chart of Custom Events
Custom Events