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. For more information, see "Plan usage analytics, usage events and recommendations" in Plan search for cross-site publishing sites in SharePoint Server 2013.

Because SharePoint 2013 runs as websites in Internet Information Services (IIS), administrators and users depend on the accessibility features that browsers provide. SharePoint 2013 supports the accessibility features of supported browsers. For more information, see the following resources:

There are three default usage event types in SharePoint 2013. You can create up to twelve custom usage event types by using Windows PowerShell.

To create a custom usage event type

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

<SiteName> is the name of the site for which you want to create a custom usage event.

<EventTypeName> is the name of the new custom usage event type that you want to create — for example, BuyEventType.

This procedure creates a random GUID for the usage event type. Use this GUID when you add code to record the custom usage event, as described in Record a custom usage event.

Important:

It can take up to three hours for a custom usage event type to become available in the system. However, to speed up the process, you can alternatively restart the SharePoint Timer Service.

Note:

We recommend that you use Windows PowerShell when performing command-line administrative tasks. The Stsadm command-line tool has been deprecated, but is included to support compatibility with previous product versions.

After you have created a custom usage event type, as described in Create a custom usage event type, you have to add code to the place where the event occurs — for example, when a page loads, or when a user clicks a link or a button. This data is then sent to the analytics processing component, where it is recorded and processed.

If you are using cross-site publishing, where you show catalog content on a publishing site, you must record the usage event on the URL of the indexed item, and override some site settings. For example, if you have a catalog in an authoring site that you have published on a publishing site, when a user interacts with a catalog item on the publishing site, this usage event must be recorded on the item in the authoring site. Furthermore, the code that you add to record the usage event must override the SiteId and the WebId of the publishing site, and be replaced with the SiteId and the WebId of the authoring site.

To add code to record a custom usage event

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

# The example below shows how a custom usage event type is referred to when a button is clicked:
<button onclick="Log<CustomUsageEventType>ToEventStore('<URL>')"></button>

Where:

<CustomUsageEventType> is the name of the custom event type.

<URL> is the full URL of the item to which the usage event should be logged — for example, http://contoso.com/faq.

To add code to record a custom usage event and override site settings

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

In an HTML editor, open the file where the custom usage event should be logged — for example, a display template for a Content Search Web Part. The following example shows how to override the current SiteId, WebId and UserId.

# The example below shows how a custom usage event type is referred to when the "Buy!" button is clicked:
<button onclick="Log<CustomUsageEventType>ToEventStore('<URL>', new SP.Guid('{<SiteId GUID>}'), new SP.Guid('{<WebId GUID>}'), '<UserName>')">Buy!</button>

Where:

<CustomUsageEventType> is the name of the custom event type — for example, BuyEventType.

If you want to add code that refers to a default usage event type — for example, views, you have to add code to the place where the event occurs.

If you are using cross-site publishing, which shows catalog content on a publishing site, you must record the usage event on the URL of the indexed item, and override some site settings. For example, if you have a catalog in an authoring site that you have published on a publishing site, when a user interacts with a catalog item on the publishing site, this usage event must be recorded on the item in the authoring site. Furthermore, the code that you add to record the usage event must override the SiteId and WebId of the publishing site, and be replaced with the SiteId and WebId of the authoring site.

To add code to record a default usage event

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

# The example below shows how a default usage event type is referred to on a page load:
<body onload="Log<DefaultUsageEventType>ToEventStore('<URL>')">

Where:

<DefaultUsageEventType> is the name of the default usage event type — for example, Views.

<URL> is the full URL of the item to which the usage event should be logged, — for example, http://contoso.com/careers

Save the file.

To add code to record a default usage event and override site settings

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

In an HTML editor, open the file where the custom usage event should be logged — for example, a display template for a Content Search Web Part. The example below shows how to override the current SiteId, the WebId and the UserId.

# The example below shows how a default usage event type is referred to on a page load:
<body onload="Log<DefaultUsageEventType>ToEventStore('<URL>', new SP.Guid('{<SiteId GUID>}'), new SP.Guid('{<WebId GUID>}'), '<UserName>')">

Where:

<DefaultUsageEventType> is the name of the default event type — for example, Views.

<UserName> can be a cookie ID that is used to identify users on a site that has anonymous users, for example.

Note:

We recommend that you use Windows PowerShell when performing command-line administrative tasks. The Stsadm command-line tool has been deprecated, but is included to support compatibility with previous product versions.

The usage event type property, RecommendationWeight, is a numeric value that shows the level of importance of a usage event type compared to other usage event types that are used in the recommendations calculation. The default Views usage event type has a preconfigured RecommendationWeight value of 1. The other default usage event types, Recommendations displayed, and Recommendations clicked, and all custom usage event types, have a RecommendationWeight value of 0. To increase the importance of a usage event type in the recommendations calculation, change the value of the RecommendationWeight parameter. The highest level of importance available is 10.

To change the level of importance of a usage event type

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

<EventTypeId> is the numeric ID of the usage event type for which you want to change the weight — for example, 256.

<RecommendationWeightNumber> is the level of importance that you want to apply to the user event type — for example, 4.

Note:

We recommend that you use Windows PowerShell when performing command-line administrative tasks. The Stsadm command-line tool has been deprecated, but is included to support compatibility with previous product versions.

The usage event type property RecentPopularityTimeframe is a numeric value that defines the Recent time period in the Most Popular Items report. The Most Popular Items report shows the most popular items per usage event type for all items in a library or list — for example, the most viewed items in a library or list. The report can be sorted by the time periods Recent or Ever. By default, the Recent time period is set to the last 14 days for each usage event. You can change this to a time period between one and 14 days.

To change the Recent time period for a usage event type

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

<EventTypeId> is the numeric ID of the usage event type for which you want to change the Recent time frame — for example, 256.

<TimeFrame> is the new Recent time frame that you want to apply to the user event type — for example, 7.

Note:

The system updates any changes to the Recent time period only after the Usage Analytics Timer Job has run.

Note:

We recommend that you use Windows PowerShell when performing command-line administrative tasks. The Stsadm command-line tool has been deprecated, but is included to support compatibility with previous product versions.

Users that are browsing the contents of a site without being connected to an account are known as anonymous users. Only the Views event type is enabled for the logging of anonymous users. By default, the logging of custom usage events is disabled for anonymous users.

To enable the logging of usage events of anonymous users

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

<EventTypeId> is the numeric ID of the usage event type that you want to enable for the logging of anonymous users — for example, 256.

To disable the logging of usage events of anonymous users

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

<EventTypeId> is the numeric ID of the usage event type that you want to disable for the logging of anonymous users — for example, 256.

Note:

For the default usage event type Views, you cannot disable the logging of anonymous users.

Note:

We recommend that you use Windows PowerShell when performing command-line administrative tasks. The Stsadm command-line tool has been deprecated, but is included to support compatibility with previous product versions.

You can use the following PowerShell commands to get the SiteId GUID and the WebId GUID for a site.

To get SiteId GUID and WebId GUID for a site

Verify that you have the following memberships:

securityadmin fixed server role on the SQL Server instance.

db_owner fixed database role on all databases that are to be updated.

Administrators group on the server on which you are running the Windows PowerShell cmdlets.

Add memberships that are required beyond the minimums above.

An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 cmdlets.

Note:

If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.

# To get the SiteId GUID and the WebId GUID for a root site collection:
$site = Get-SPSite "<RootSiteURL>"
$web = $site.RootWeb
$site.id
$web.id
# To get the WebId GUID for a site below the root site collection:
$site = Get-SPSite "<RootSiteURL>"
$web = $site.OpenWeb("<SubSiteLocation>")
$web.id

Where:

<RootSiteURL> is the URL of the root site that you want to get the SiteId GUID and the WebId GUID of — for example, http://contoso.com/sites/catalog.

<SubSiteLocation> is the remainder of the URL path to the subsite after the root site URL. For example, if your root site URL is http://contoso.com/sites/catalog, and your subsite URL is http://contoso.com/sites/catalog/products, type products for this placeholder.

Note:

We recommend that you use Windows PowerShell when performing command-line administrative tasks. The Stsadm command-line tool has been deprecated, but is included to support compatibility with previous product versions.