AppSuite:Metrics: Difference between revisions

From Open-Xchange
No edit summary
No edit summary
Line 7: Line 7:
A common set of events is tracked by default. Out of the box PIWIK is supported as reference analytics framework. Every other analytics framework can be added easily by registering a new adapter within the metrics module where data and events are mapped to the special needs of the target analytics framework.
A common set of events is tracked by default. Out of the box PIWIK is supported as reference analytics framework. Every other analytics framework can be added easily by registering a new adapter within the metrics module where data and events are mapped to the special needs of the target analytics framework.


=== Parts and tasks ===  
=== Components and their tasks ===  


   * listener/handler: waiting for events and call metrics module
   * listener/handler: waiting for events and call metrics module
Line 65: Line 65:
===== Adapterspecific =====
===== Adapterspecific =====


For more details visit the [[AppSuite:Metrics-Adapters | adapter article]].
<code>
<code>
   // ADAPTER BLOCK PIWIK: START  
   // ADAPTER BLOCK PIWIK: START  
Line 84: Line 85:
</code>
</code>


=== Step-by-step Setup guide ===
=== Further reading ===
 
With this easy step-by-step guide it should be quite simple to setup PIWIK and adjust the relevant properties to start tracking.
 
==== 1. Preconditions ====
 
**important**
 
Please ensure PIWIK runs also on SSL in case OX Appsuite does.
 
**adblockers**
 
hint: in case you consider to bypass adblockier mechanisms please avoid suspicious strings for any part of the url (for example ‘piwik’). One possible solution would be to use [[http://httpd.apache.org/docs/current/mod/mod_rewrite.html|apaches mod_rewrite]] or something similar to aliases for affected urls.
 
==== 2. Install PIWIK ====
 
Simply follow the steps provided by the PIWIK documentation http://piwik.org/docs/installation/
 
Please pause when you reach step 8 of the wizard (JavaScript Tag) and move on with part 2 of this guide.
 
==== 3. Take a deeper look at the generated script ====
 
The script provided by PIWIK will look like this:
 
<code javascript>
<!-- Piwik -->
<script type="text/javascript">
  var _paq = _paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    // in this line you can see the base url that we need to add as property
    var u="//metrics.example.com/piwik/";
    _paq.push(['setTrackerUrl', u+'piwik.php']);
    // in this line you can see the site id that we need to add as property
    _paq.push(['setSiteId', 1]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<noscript><p><img src="//metrics.open-xchange.com/piwik/piwik.php?idsite=1" style="border:0;" alt="" /></p></noscript>
<!-- End Piwik Code -->
</code>
==== 4. Appsuite properties ====
 
Now we have to extract some of the information used in this script. The script itself do not has to be added to OX Appsuite. Use the following file to adjust/add the properties:
 
<code>
  /opt/open-xchange/etc/settings/metrics.properties
</code>
 
**base url**
 
You need to specify the base url that allows OX Appsuite calling the PIWIK tracking API. You can simply check if got the right url by trying to open the url followed by ‘piwik.php’ in the browser (example: ‘https:%%//%%metrics.example.com/piwik/piwik.php’). You should see some message similiar to ‘Piwik is a free/libre web analytics that lets you keep control of your data.’
 
<code>
//generated PIWIK script//
 
[...]
var u="//metrics.example.com/piwik/";
[...]
 
//appsuite property//
io.ox/core//tracking/piwik/url=https://metrics.example.com/piwik/
</code>
**siteId**
 
With PIWIK you can separate tracking by using different contextes called ‘websites’. These contextes are identified by an unique id that usually starts with 1 and increments by 1 for every newly created page. To guarantee tracked date is added to the right context you have to specify this id in the settings. In case no setting is provided the id ‘1’ is used as default
 
//generated PIWIK script//
 
<code>
[...]
_paq.push(['setSiteId', 1]);
[...]
</code>
//appsuite property//
 
<code>
io.ox/core//tracking/piwik/id=1
</code>
**enabling/disabling**
 
Finally you need to enable tracking in general and PIWIK in particular.
 
<code>
  io.ox/core//tracking/enabled=true
  io.ox/core//tracking/piwik/enabled=true
</code>
 
==== 5. Continue ====
 
Please continue with the PIWIK Installation wizard.
 


* [[AppSuite:Metrics-Analytics-Solutions | Analytics Solutions]]  like PIWIK
* [[AppSuite:Metrics-Events | Events ]]
* [[AppSuite:Metrics-Adapters | Adapters ]]
*  [[AppSuite:Metrics-Details |  Details ]]


[[Category:AppSuite]]
[[Category:AppSuite]]
[[Category:UI]]
[[Category:UI]]
[[Category:Metrics]]
[[Category:Metrics]]

Revision as of 09:48, 22 September 2015

Metrics

Introduction

The Metrics module provides a very flexible and extendible way to track user behaviour and conditions within OX Appsuite.

A common set of events is tracked by default. Out of the box PIWIK is supported as reference analytics framework. Every other analytics framework can be added easily by registering a new adapter within the metrics module where data and events are mapped to the special needs of the target analytics framework.

Components and their tasks

 * listener/handler: waiting for events and call metrics module
 * metrics module: provides a central API for tracking and propagate events to enabled adapters
 * Adapter: maps generic event data for a concrete analytics framework and calls their API


Basics

The metrics module is located in Appsuite’s front end and can be configured by backend properties.

Frontend

The parts a separated by their role/task with high flexibility and extendability in mind.

Parts
 - metrics listener: waiting for a event (example: click on an ‘mail reply’)
 - metrics handler: submits data to the metrics module
 - metrics module: central facade with a generic API as connecting piece between event handlers and adapters
 - metrics adapter: communicates with a concrete analytics framework API
Source code

 // core module
 io.ox/metrics/main.js

 // adapter for each target analytics framework
 io.ox/metrics/adapters

 // adapter for PIWIK
 io.ox/metrics/adapters/default.js

 // global listeners/handlers
 io.ox/metrics/extensions.js

Backend

Use the following setting properties to enhance/adjust usage. Please be aware of the double slashes that are used as separator for the namespaces.

Global

 // global switch [true/false]
 // current default: true
 io.ox/core//tracking/enabled


 // consider doNotTrack-flag in front end [true/false]
 // current default: false
 io.ox/core//tracking/donottrack

Adapterspecific

For more details visit the adapter article. 

 // ADAPTER BLOCK PIWIK: START 

 // adapter switch (PIWIK) [true/false]
 // current default: true
 io.ox/core//tracking/piwik/enabled

 // platform base url [url]
 // current default: https://[insert-your-host-here]/piwik/
 io.ox/core//tracking/piwik/url

 // platform page id [url]
 // current default: 1
 io.ox/core//tracking/piwik/id

 // ADAPTER BLOCK PIWIK: END

Further reading

Retrieved from "https://wiki.open-xchange.com/wiki/index.php?title=AppSuite:Metrics&oldid=20514"