Business Analytics

Site Statistics View

The Site Statistics view offers an overview of tracked activity within the selected date range. You see actual data for the

• number of views
• number of visitors
• ratio of visitors per view
• number of new and returning visitors
• ratio of new to return visitors

  See Also: Tracking New and Returning Site Visitors.

Below this are pie charts of the ratio of views to visitors and new vs. return visitors.

Content View

The Content View shows the most frequently-accessed content on your Web site.

Click any content item to view:

• Content Statistics—statistics for that content item only (See Also: Analyzing Site Statistics)
• Content Activity—relative activity for that content item only (See Also: Content View)
• Audit Content—all users who viewed the selected content; to the right of each user are the date and time when content was viewed

NOTE: Only users who viewed content after logging in appear on the list. Site visitors who do not log in affect statistics but are not tracked on this report.

Templates

The Templates View shows all viewed templates on your Web site, with the most frequently-accessed ones on top.

By default, the templates at the top have the highest number of unique visitors. You can change the sort by clicking any column header. For example, to sort templates by the number of views, click Views.

You can click any template to view

• Template Statistics—statistics for that template only
• Template Activity—relative activity for that template only
• Content in Template—if a content item was specified for the template in the Content Analytic server control, this view show statistics for the template. You can click the template to view Template Level activity.

Referrers View

The Referrers View shows domains from which your site was most frequently accessed.

The following are Ektron-specific server control properties. You can find information about native .NET properties such as font, height, width and border style in Visual Studio^® help.

• Authenticated (Boolean)

  Indicates if you are logged into the CMS Explorer and can use it to browse to content, collections, and so on. See Also: Browsing Your Ektron Site Using CMS Explorer.

• ContentIdsList (String)

  Enter a comma-separated list of content IDs to be tracked. The DefaultContentId and the dynamicParameter are also tracked. See Also: Business Analytics

• DefaultContentID (Long)

  The ID of a content block being tracked by this server control. It typically would be the content directly above the analytics tracker if no other content block is identified, or is not available. If you don’t know the ID number of the content block, use the CMS Explorer to browse to it. See Also: Browsing Your Ektron Site Using CMS Explorer

• DoInitFill (Boolean)

  By default, Fill occurs during the Page_Init event. Set to false if you want to postpone the fill-action until later. In this case, Fill is automatically called during the Page Render event. You might do this if you need to set or change a property on the control in code-behind and have it render with your changes shown.

• DynamicParameter (String)

  To make this control dynamic, select id. When you do, this server control is attached to the content block passed as a URL parameter.

• EnableAnalytics (String)

  Set one of these values to determine if this server control tracks Business Analytics statistics.

  • true—this control tracks analytics
  • false— this control does not track analytics
  • ConfigSpecified—use the setting in the site root/web.configfile'senableAnalytics key. For example, if that key =true, this control tracks analytics.

  Note that the first 2 options (true and false) let you enable/disable this particular control. Use the last option, ConfigSpecified, if you want to use a single web.config setting to enable/disable all analytics controls.

• Hide (Boolean)

  Hides or displays the output of the control in design time and run time.

  • True—Hide the control output.
  • False—Display the control output.
• Language (Integer)

  Set a language for viewing content; shows results in design-time (in Visual Studio) and at run-time (in a browser).

• WrapTag (String)

  Lets a developer specify a server control’s tag.

  • Span (default)—designate an inline portion of an HTML document as a span element.
  • Div—apply attributes to a block of code.
  • Custom—Lets you use a custom tag.

Saving Event Data

Show how event data is saved to the database.

To save events, use the static class EventLogger, which exposes the following methods.

• IAnalyticsEventData CreateAnalyticsEventData()
• void Log(IAnalyticsEventData eventObject)
• void Log(string eventName)
• void Log(string eventName, string xml)
• void Log(string eventName, string xml, int count)

Show the illustrated EventLogger classes.

As long as an event (myEvent) has been registered in the system, you can store an event like this:

using Ektron.Cms.Framework.Analytics.BusinessAnalytics;
…
EventLogger.Log(“myEvent”);

This code saves the event data with default values. As shown, the Log method has several overloaded versions. Each provides a different amount of control over the information saved to the database. The following list shows the Log method's parameters.

• eventName (String)—A name that uniquely identifies the event. This name must be registered and enabled in the database for it to be recorded.
• XML (String)—This parameter is purely for customization. By default, its value is null. The API stack passes the string to the database, where the appropriate stored procedure can use it. For example, it can store additional values that are not part of the current event-object
• count (Integer)—Allows increments other than the default value of one. For example, you may want a specific event to increment the event counter by 5.

In addition to the parameters listed above, you can set other values by referencing the event object that carries the information to the database. A call to CreateAnalyticsEventData returns this object, and can be used as follows:

IAnalyticsEventData eventObject = CreateAnalyticsEventData();

Through the interface IAnalyticsEventData, the object provides the following additional parameters, which allow more control over what information is saved with the event.

• ObjectId (Long)—For a content related event, ObjectId should be set to a Content ID.
• LanguageId (Integer)—The content object's Language ID. If that is not available, the current request's Language ID.
• SiteId (Long)—The current request's Site ID

  NOTE:  A value of -1 means this value has not been set, and will be updated appropriately at a lower level.

• UserId (Long)—The current request's User ID (if logged in)
• VisitorId (String)—The current request's Visitor ID (if not logged in)
• EventDate (DateTime)—Defaults to current date and time

Retrieving Event Data

Show how data is retrieved into reports

Use the static class EventReporter to retrieve events stored in the database. This class exposes the following methods.

• IList<string> GetReportNameList()
• IAnalyticsQueryRequest CreateQueryRequest()
• IContentQueryRequest CreateContentQueryRequest()
• IList<IAnalyticsEventItem> GetList(IAnalyticsQueryRequest queryRequest)
• IList<IContentEventItem> GetList(IContentQueryRequest queryRequest)
• void UpdateReportData(String eventName, DateTime eventDate)

Show the illustrated EventReporter classes.

GetReportNameList method

GetReportNameList Method

Use the GetReportNameList method to obtain a list of recognized (e.g., registered) report names. You can extend this list by adding custom event types and their corresponding stored procedure handlers.

For example, to obtain a list of the allowed report names, use the following code.

using Ektron.Cms.Framework.Analytics.BusinessAnalytics;
...
IList<String> names = EventReporter.GetReportNameList();

CreateQueryRequest method

CreateQueryRequest Method

Use the CreateQueryRequest method to specify an event data report of the base-level type. The method returns an object that implements the interface IAnalyticsQueryRequest, which has the following parameters.

• ReportName (String)—Uniquely specifies the report, which is registered and corresponds to one or more stored procedures which, when run, generate the requested data.
• SiteId (Long)—The Site ID of the data being returned.
• UserId (Long)—The User ID of the data being returned.
• EventStartDate (DateTime)—If desired, use to determine the earliest date for which report data is returned. By default, data from the earliest date is returned.
• EventEndDate (DateTime)—If desired, use to determine the latest date for which report data is returned. By default, data through the most recent date is returned.
• PagingInfo (Ektron.Cms.PageingInfo)—Page size and number let you display a small portion of the report at a time. By setting page size and number, the report data is reduced, and performance will improve. Conversely, performance degrades as page size (RecordsPerPage) increases, especially if the amount of stored data is large. This type has the following fields:
  • CurrentPage
  • EndRow
  • RecordsPerPage
  • StartRow
  • TotalPages
  • TotalRecords
• OrderByDirection (EkEnumeration.OrderByDirection)—Descending or Ascending
• XML (String)—This parameter is purely for customization. By default, its value is null. While saving event data, the API stack passes the string to the database, where the appropriate stored procedure can use it. For example, it can store additional values that are not part of the current event-object. Within the CreateQueryRequest method, this parameter can returns that string.

CreateContentQueryRequest method

CreateContentQueryRequest Method

Use the CreateContentQueryRequest method to specify a report of event data that is related to content. It returns an object that implements the interface IContentQueryRequest which, in addition to those provided by interface IAnalyticsQueryRequest (see CreateQueryRequest Method) has the following parameters.

NOTE: You can use either the FolderID or the TaxonomyID parameter but not both. Also, you can only use the IncludeChild parameter related to the selected parent parameter.

• LanguageId (ID)—The Language ID of the content that the report returns.
• FolderId (Long)—The folder of the content being returned. All content in the folder is returned. It defaults to that of the current HTTP request.
• IncludeChildFolders (Boolean)—Determines whether the report includes children of the folder specified in the FolderID parameter.
• TaxonomyId (Long)—The taxonomy category of the content being returned. All content to which the category is applied the folder is returned. It defaults to that of the current HTTP request.
• IncludeChildTaxonomy (Boolean)—Determines whether the report includes children of the folder specified in the FolderID parameter.

GetList method

GetList Method

There are 2 versions of the GetList method.

One version takes an IAnalyticsQueryRequest object, and returns a list of objects that implement IAnalyticsEventItem. That version has the following parameters.

• ID (Long)—The object Id s supplied when the related events were saved.
• XML (String)—This parameter is purely for customization. By default, its value is null.

  While saving event data, the API stack passes the string to the database, where the appropriate stored procedure can use it. It can store additional values that are not part of the current event-object.

The other version of the GetList method takes an IContentQueryRequest object and returns a list of objects that implement the interface IContentEventItem. That provides the following parameters in addition to those of IAnalyticsEventItem (shown above).

• LanguageId (Integer)—The Language ID of the content that the report returns.
• Quicklink (String)—The object's URL.
• Title (String)—Determines whether the report includes children of the folder specified in the FolderID parameter.
• Teaser (String)—The content summary. See Also: Writing a Summary for Content
• Status (String)—The content's status. See Also: Content Statuses
• FolderID (Long)—The FolderID of the content being reported.
• Count (Integer)—The count of the object being reported. For example, if you are retrieving the most frequently emailed content item, the count is the number of times it was emailed. The count and average values may be used individually or together, depending on the report. For example, the rating report returns both the average (rating) and the count (the number of ratings), while the commented report uses only the count.
• Average (Decimal)—The a numerical value divided by the count. For example, when Ektron calculates average content rating, it divides the total number of rating points (on a scale of 1 thru 10) by the number of votes.

UpdateReportData method

UpdateReportData Method

This method tells the database that an event's details should update that event's aggregated data. This method is only required if the database does not automatically do this, such as when the corresponding bit is disabled for that an type in the database. Disabling the corresponding bit generally improves performance, especially if the event logging rate is high. But, if you disable the corresponding bit, you must call this update method if you want the report to show current data.

The UpdateReportData method takes the following parameters.

• eventName (String)—The event whose data will be updated.
• eventDate (DateTime)—The date of the event's occurrence. For example, if you pass 1/1/2009, one row in the aggregate table is updated. If the row doesn't exist, it gets created. If you do not pass an event date, this method updates the aggregate table with summary info for that event for all dates. For example, if today is February 1, the system has been in use since the beginning of the year, and you pass NULL for the date, 32 table rows are updated (31 days in January plus 2/1).

Disabling the Saving or Reading of Events

You can disable the saving or reading of all events or of individual events.

It is useful to disable events when you want to minimize database traffic. To disable all events:

1. Open siteroot/web.config.
2. Set the following parameters to false.

   <!-- Enable saving business-analytics events to the database (at API level) -->
   <add key="ek_enableBusinessAnalyticsEventStorage" value="false"/>
   <!-- Enable querying the database for business-analytics events (at API level) -->
   <add key="ek_enableBusinessAnalyticsEventReports" value="false"/>

   NOTE: These settings are set to enabled (true) by default.

You can also enable or disable individual events in the database itself, but this does require a call to travel through the full stack.

Using a Custom Provider

Below the service level are providers that read and write event data. The default providers simply pass calls through to the standard Ektron database-access-level code, which reads and writes from the database. But you can modify this behavior to almost any conceivable alternative. For example, you can

• save the data to an alternate database on an alternate machine
• call a Web service to handle the reads and writes
• filter the data and/or requests
• process information on its way to or from the database

The SDK contains sample providers, as well as full source code for the Ektron-supplied providers. You can use this material as a basis for writing custom providers, which is the preferred technique for customizing the behavior of the Business Analytics API stack and subsystem.

The Default Providers

The default providers for saving and reading event data (respectively) are EktronEventProvider.cs and EktronQueryProvider.cs. Example custom-provider source code has the following names for saving and reading event data (respectively): “DemoEventProvider.cs” and “DemoQueryProvider.cs” For the default providers, the siteroot/web.config file must contain the following, inside <configuration><configSections>.

<section name="businessAnalyticsQueryProvider"
  type="Ektron.Cms.Analytics.Providers.BusinessAnalyticsQueryProviderConfiguration,
  Ektron.Cms.BusinessObjects"
  allowDefinition="MachineToApplication"
  restartOnExternalChanges="true"/>
<section name="businessAnalyticsEventProvider"
  type="Ektron.Cms.Analytics.Providers.BusinessAnalyticsEventProviderConfiguration,
  Ektron.Cms.BusinessObjects"
  allowDefinition="MachineToApplication"
  restartOnExternalChanges="true"/>

Additionally, the following must exist inside the <configuration> tags.

<businessAnalyticsQueryProvider
  defaultProvider="EktronBusinessAnalyticsQueryProvider">
<providers>
<add name="EktronBusinessAnalyticsQueryProvider"
  type="Ektron.Cms.Analytics.Providers.EktronQueryProvider,
  Ektron.Cms.BusinessObjects"/>
</providers>
</businessAnalyticsQueryProvider>
<businessAnalyticsEventProvider
  defaultProvider="EktronBusinessAnalyticsEventProvider">
<providers>
<add name="EktronBusinessAnalyticsEventProvider"
  type="Ektron.Cms.Analytics.Providers.EktronEventProvider,
  Ektron.Cms.BusinessObjects"/>
</providers>
</businessAnalyticsEventProvider

Creating Custom Providers

To override the default Ektron provider with the a custom provider:

1. Create a new solution with a project named CustomProviders.
2. Add the following references to your project.
   • Ektron.Cms.BusinessObjects.dll
   • Ektron.Cms.Common.dll
   • Ektron.Cms.ObjectFactory.dll
3. Add files DemoEventProvider.cs and DemoQueryProvider.cs (from the Ektron SDK).
4. Build.
5. Copy the CustomProviders.dll file to your Ektron site's bin file.
6. Update web.config by modifying the <configuration> section. Specifically, add demo providers to the Business Analytics providers as shown below.

<businessAnalyticsQueryProvider
  defaultProvider="DemoQueryProvider">
<providers>
<add name="EktronBusinessAnalyticsQueryProvider"
  type="Ektron.Cms.Analytics.Providers.EktronQueryProvider,
  Ektron.Cms.BusinessObjects"/>
<add name="DemoQueryProvider"
  type="Ektron.Cms.Analytics.Providers.DemoQueryProvider,
  CustomProviders"/>
</providers>
</businessAnalyticsQueryProvider>
<businessAnalyticsEventProvider
  defaultProvider="DemoEventProvider">
<providers>
<add name="EktronBusinessAnalyticsEventProvider"
  type="Ektron.Cms.Analytics.Providers.EktronEventProvider,
  Ektron.Cms.BusinessObjects"/>
<add name="DemoEventProvider"
  type="Ektron.Cms.Analytics.Providers.DemoEventProvider,
  CustomProviders"/>
</providers>
</businessAnalyticsEventProvider>