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

Make better decisions with Usage Analytics in O365 and SharePoint

If you have worked with me for more than a day then you have probably heard me talk about feedback loops and the necessity of analytics to assist in prioritizing UX work.  I am passionate about using data to support investment and there are really simple ways to get started, even with “inside the firewall” SharePoint sites.
Why is this important?  It is important because you probably have a limited budget for making improvements and you would like to invest those limited resources in the places where the opportunity to improve productivity is the greatest.

Most SharePoint site templates provide some basic reports around page views, and certain ones, like catalogs, also provide popularity reports for catalog items.  What is not there out of the box, is a way to review other activities such as, when a search refiner is clicked, when an object is hovered-over, if someone clicks on those shortcuts you added in a Content webpart, or whether or not the average visitor hops around on the site or stays on one page.

I cannot cover every option in a short post, but today I will get you started by demonstrating how to get Azure Application Insights into your SharePoint site to collect more comprehensive data than just page views.
The process is simple:
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”

That is all.  From the moment the new Masterpage is utilized you will start seeing core session and page view data in your Azure Portal.   I take for granted that if you are interested in analytics for your SharePoint sites that you are already familiar with Masterpages and their function, but I still explain the update process here in case you need a guide.  To complete this exercise you also need to have an Azure account to create an AAI instance, but the basic tier is free and most intranets will not generate enough events to get you out of the “free” tier.  Do not have an account?  Sign-up is free at:

1. Create an Azure Application Insights (AI) instance

Click to create a new Application Insights instance at and fill in the necessary info about resource group and application type- I used ASP.Net here.  The blades expand as clicked so I numbered the image below for clarity.

2. Acquire the Javascript for sending events to your AI instance

When the instance is created, you should see info like this in the AI instance landing page indicating that there is no data yet.

Select “Page views” as above when the service is new and AI will produce a block of code for you which both enables Application Insights on a page, and submits a View event to AI.  The snippet will look like this:

The instrumentation key is unique for every instance.  Note the final statement in the block which actually logs the View event:
When this script is loaded, you can add custom events with only one more statement:
appInsights.trackEvent(“Your Event Here”);
What custom events should you make and where should they go?  That is the high-value question.  More on this subject in my next post.

3. Insert Javascript into Masterpage for your site

Navigate to your masterpage gallery and download a copy of the masterpage which you would like to add the event logic to.  In this example I downloaded the standard “seattle.html” Master Page.  Add the Javascript snippet as the last item inside the Body tag, save with a new meaningful name, upload, and publish.

4. Use the new “AAI Masterpage”

Finally, from the Site Master Page Settings screen select your new Master Page.  If you did not publish the new page in the last step, your new Master Page will not appear in the dropdown.

Once the master page is set, all Page Views in the site will be logged in Application Insights and you will start seeing data like this in your portal:

O365 Site Views in Azure Application Insights

You get a lot more than just Page Views from Application Insights but I will let you explore until I have time to create another post outlining how to use Custom Events in standard templates- it is easier than the name might lead you to believe.  Keep in mind that while it great to have core usage data, the value is in how you use it.