November Happy Hour will be moved to Thursday December 5th.

AI OnAI Off

Configuring the Statistics Handler

Product version:

EPiServer CMO 2.0

Document last saved:

 

CMS pages related to any active campaigns contain injection which makes user browsers send requests to the statistics handler.

The installation files needed to configure the statistics handler can be downloaded from EPiServer World. The statistics handler processes statistics data coming from users and saves raw visit logs to the statistics storage.

Note! Statistics collecting requires the Friendly URL Rewriter module as the injection is done by the handler of this event.

Statistics Data Handling

Each request contains parameters that cannot be detected on server side. The statistics handler tries to find and parse the following information in the request query string:

  • CMS page ID (GUID)
  • Original URL referrer
  • User ID – simple generated indentificator to track requests from the same user
  • Event type – indicates user action – open page, leave page, download file or post form. The handler also detects the user agent and user IP address. If data is related to pages from active campaigns, the handler saves raw log entry for each page's campaigns.

Statistics Handler Deployment and Configuration

  1. Create a new website to host the statistics handler. If you need, handler can be added to the existing website.
  2. Copy EPiServer.Cmo.Core.dll, EFExtensions.dll and log4net.all files to the /bin directory of website.
  3. If the website does not already have a web.config file, create one under the root of the site.
  4. Configure database connection for data model using ADO.NET Entity Framework format. Add the following elements and update it with your specific connection parameters.
     
    <configuration>
      <connectionStrings>
        <add name="CmoEntities" connectionString="metadata=res://*/Entities.CmoModel.csdl|res://*/Entities.CmoModel.ssdl|res://*/Entities.CmoModel.msl;provider=System.Data.SqlClient;provider connection string=&quot;Data Source=.\sqlexpress;Initial Catalog=Cmo;Integrated Security=True;MultipleActiveResultSets=True&quot;" providerName="System.Data.EntityClient" />
      </connectionStrings>
    </configuration>     
  5. Register Statistics handler for IIS. See below.
  6. You can also need to configure IIS to forward the request for *.stat file name extension to ASP.NET. For more information about how to configure a handler for a custom file name extension, see How to: Configure an HTTP Handler Extension in IIS (http://msdn.microsoft.com/en-us/library/bb515343.aspx). Make sure that IIS will not check if handler file physically exists on disk.
  7. Verify configuration parameters defined on the CMO Settings page in the General Settings tab in EPiServer CMS Admin mode. The statistics handler uses cache timeout parameters.
  8. Several more steps are needed to properly detect modern browsers. In the site's root folder create the App_Browsers subfolder and put the browser definition files listed below.

    For Safari version 3.0 and higher:
    File name: safari.browser  >> Download the safari.browser file
    File content:
     
    <browsers>
     <browser id="Safari3Plus" parentID="Safari1Plus" >
      <identification>
       <userAgent match="Version/(?'version'(?'major'\d+)\.(?'minor'\d+[\.\d+]*)\w*)\s+Safari" />
      </identification>
      <capture>
      </capture>
      <capabilities>
       <capability name="majorversion" value="${major}" />
       <capability name="minorversion" value="${minor}" />
       <capability name="version" value="${version}" />
      </capabilities>
     </browser>
     <browser refID="Safari1Plus" >
      <capabilities>
       <capability name="browser" value="Safari" />
      </capabilities>
     </browser>
    </browsers>
    For Google Chrome:
    File name: chrome.browser >> Download the crome.browser file
    File content:
     
    <browsers>
     <browser id="GoogleChrome" parentID="Safari1Plus">
      <identification>
       <userAgent match="Chrome/(?'version'(?'major'\d+)\.(?'minor'\d+\.\d+).\d+)" />
      </identification>
      <capture>
      </capture>
      <capabilities>
       <capability name="browser"        value="Chrome" />
       <capability name="majorversion"   value="${major}" />
       <capability name="minorversion"   value="${minor}" />
       <capability name="version"        value="${version}" />
      </capabilities>
     </browser>
    </browsers>
    Also, because of internal ASP.NET User-Agent caching you need to add parameter in web.config:
     
    <system.web>
        <browserCaps userAgentCacheKeyLength="128" />      
  9. If you need to have debug logs, you can define logging configuration. See details about log4net configuration here http://logging.apache.org/log4net/. Sample configuration with DebugOutput and file logging:
     
    <configuration>
      <configSections>
            <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net, Version=1.2.10.0, Culture=neutral, PublicKeyToken=1b44e1d426115821" />
      </configSections>
     
      <log4net>
        <appender name="OutputDebugStringAppender" type="log4net.Appender.OutputDebugStringAppender">
            <layout type="log4net.Layout.PatternLayout">
                <conversionPattern value="%date [%thread] %-5level - %message%newline" />
            </layout>
        </appender>
        <appender name="RollingLogFileAppender" type="log4net.Appender.RollingFileAppender">
            <file value="Statistics.log.txt" />
            <appendToFile value="true" />
            <rollingStyle value="Date" />
            <datePattern value="yyyyMMdd " />
            <layout type="log4net.Layout.PatternLayout">
                <conversionPattern value="%date [%thread] %-5level - %message%newline" />
            </layout>
        </appender>
        <root>
            <level value="DEBUG" />
            <appender-ref ref="OutputDebugStringAppender" />
            <appender-ref ref="RollingLogFileAppender" />
        </root>
      </log4net>
    </configuration>

Handler Registration for IIS

See details about handlers registration here: http://msdn.microsoft.com/en-us/library/46c5ddfy.aspx

Register Handler for IIS 6

  1. In the application's web.config file, create an httpHandlers section.
     
    <configuration>
      <system.web>
        <httpHandlers>
          <add verb="GET" path="{file_mask}" type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core"/>
        </httpHandlers>
      </system.web>
    </configuration>      
  2. Make sure to change the {file_mask}  parameter to the correct mask of the web service you configured during the installation of EPiServer CMO. For example, if your web service URL is “http://localhost/mywebservice.stat”, you could specify  “mywebservice.stat” or “*.stat” instead of this parameter.
  3. Configure IIS to forward the request for ”*.stat” requests to ASP.NET.

Register Handler for IIS 7 Running in Classic Mode

  1. In the application's web.config file, create an httpHandlers section.
  2. Create a handlers element in the system.webServer section.
  3. Add the following elements to register the handler:
     
    <configuration>
      <system.web>
        <httpHandlers>
          <add verb="GET" path="{file_mask}" type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core" />
        </httpHandlers>
      <system.web>
      <system.webServer>
        <handlers>
          <add name="StatisticsHandler" verb="GET" path="{file_mask}" Modules="IsapiModule" scriptProcessor="FrameworkPath\aspnet_isapi.dll" resourceType="File" type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core" />
        </handlers>
      </system.webServer>
    </configuration>     
  4. Replace FrameworkPath with the correct path to the Aspnet_isapi.dll file.
  5. Make sure to change the {file_mask} parameter to the correct mask of the web service that you configured during the installation of EPiServer CMO. For example, if your web service URL is “http://localhost/mywebservice.stat” you could specify  “mywebservice.stat” or “*.stat” instead of this parameter.
  6. Add the following elements to register the handler:

Register Handler for IIS 7 Running in Integrated Mode

  1. In the application's Web.config file, create a handlers element in the system.webServer section.
    Add the following elements to register the handler:
     
    <configuration>
      <system.webServer>
        <handlers>
          <add name="StatisticsHandler" verb="GET" path="{file_mask}" type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core" />
        </handlers>
      </system.webServer>
    </configuration>     
  2. Make sure to change {file_mask} parameter to the correct mask of web service that you configured during installation of CMO module. For example, if your web service URL is “http://localhost/mywebservice.stat” you could specify  “mywebservice.stat” or “*.stat” instead of this parameter. 

FURTHER INFORMATION