Create and use own usage event type in SharePoint 2013

The original technet article says the following about usage event types in SharePoint 2013

“Usage events enable you to track how users interact with items on your site. Items can be documents, sites, or catalog items. When a user interacts with an item on your site, SharePoint Server 2013 generates a usage event for this action. For example, if you want to monitor how often a catalog item is viewed from a mobile phone, you can track this activity. This article describes how to create custom usage event types, and how to add code to record custom usage events so that they can be processed by the analytics processing component. You can use the data that is generated by usage events to show recommendations or popular items on your site. This article also explains how to influence how recommendations are shown by changing the level of importance for a specific usage event type.”

So far, so good. Now let’s see how this can be done because of some code snippets in the original article won’t work very well.
In the following example we will create a custom event called “UseFulPage” and add a button to SharePoint to fire that event.

Step 1: create a custom usage event type

#Connect to SSA

$SSP = Get-SPEnterpriseSearchServiceApplicationProxy

#create Event:

#modify the $EventName varibale to your value

$EventGuid = [Guid]::NewGuid()

$EventName = "UseFulPage"

$tenantConfig = $SSP.GetAnalyticsTenantConfiguration([Guid]::Empty)

$newEventType = $tenantConfig.RegisterEventType($EventGuid, $EventName, "")

$tenantConfig.Update($SSP)

#manipulate the weight of you event by setting RecommendationWeight & RelevanceWeight

$customEvent = $tenantConfig.EventTypeDefinitions | where-object { $_.EventName -eq $EventName }

$customEvent.RecommendationWeight = 10

$customEvent.RelevanceWeight = 10

$tenantConfig.Update($SSP)

#check if the event is created
$tenantConfig.EventTypeDefinitions | select eventTypeId,EventName | ft

The result should be something like that:

The new custom event had several properties and also 2 managed properties (UsageEvent1LifeTime & UsageEvent1Recent) which can directly be used in Search or Search Driven WebParts after the next analytics processing run.

Step 2:  add code to record the custom usage event
In the following script we need the GUID of the event. To get the GUID use this script:

$SSP = Get-SPEnterpriseSearchServiceApplicationProxy
$tenantConfig = $SSP.GetAnalyticsTenantConfiguration([Guid]::Empty)
$tenantConfig.EventTypeDefinitions | select AppEventTypeId,eventTypeId,EventName | ft

To add the event to a SharePoint site I use a JavaScript snippet (thx Markus Alt).

1. Replace %EventGUID% with the GUID of your custom event.
2. Replace %URL% with the URL of the site where you place the event. For example: http://intranet.contoso.com
3. Use a ScriptEditor WebPart to host the script in your SharePoint site.

<script language="javascript">

function ToEventStore(url)
{
    alert("Useful Page Event recorded");
    ExecuteOrDelayUntilScriptLoaded(function()
    {
        var spClientContext = SP.ClientContext.get_current();
        var eventGuid = new SP.Guid("%EventGUID%");
        SP.Analytics.AnalyticsUsageEntry.logAnalyticsAppEvent(spClientContext, eventGuid, url);
        spClientContext.executeQueryAsync(null, Function.createDelegate(this, function(sender, e){ alert("Failed to log event for item: " + document.URL + " due to: " + e.get_message()) }));
    }, "SP.js");
}
</script>

<button onclick="ToEventStore('http://%URL%')">Useful Page</button>

Step 3: work with the event
Clicking the button brings up a message box which tells you that your click is recorded. That means that the event is send to analytics engine and is processed during the next run. So you have to wait until the next day to see the result. By the way: Analytics data is process only once a day. You can configure the schedule using the Set-AnalysisConfiguration cmdlet. Other important point is that only data from last day is processes, not from the actual day. Bella Engen descried in that post how to manually kick the Analytics so there is no waiting until next day to see the data: http://blogs.technet.com/b/tothesharepoint/archive/2014/01/21/modify-the-content-search-web-part-display-template-and-use-windows-powershell-to-start-usage-analytics-in-sharepoint-server-2013.aspx

Kicking the event of cause has an impact to the ranking of that site. Another option to bring the result out is to use the managed property “UsageEvent1Recent” in a Search WebPart as a sort option. Doin this you can build an overview based on search showing the most “Useful Pages” in you SharePoint: