Difference between revisions of "AppSuite:Metrics-Adapters"

 
Line 3: Line 3:
 
== Adapters ==
 
== Adapters ==
  
Adapters can be registered or extended by using the well established technology of [[AppSuite:Extension_points|extension points]].
+
The content on this page has moved to https://documentation.open-xchange.com/latest/ui/features/metrics/02-adapters.html.
  
Here is an basic example how the PIWIK adapter is registered. The metrics module will call/invoke the defined functions for all registered adapters.
+
Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.
 
 
=== Your Adapter ===
 
 
 
==== Check preconditions ====
 
 
 
Please add at first a line into the code that checks for the user settings. In case the current adapter is disabled we should prevent registering the adapter;
 
 
 
<code javascript>
 
  if (!settings.get('tracking/[add-your-id-here]/enabled', false)) return;
 
</code>
 
 
 
 
 
==== Register Adapter ====
 
<code javascript>
 
  ext.point('io.ox/metrics/adapter').extend({
 
        id: 'piwik',
 
        setup: function () {
 
          // called once
 
        },
 
        trackVisit: function () {
 
          // called for each tracked visit (usually called once)
 
        },
 
        trackEvent: function (baton) {
 
          // called for each tracked event
 
        },
 
        trackPage: function (baton) {
 
          // called for each opened application/module
 
        },
 
        trackVariable: function (baton) {
 
          // usually called once
 
        }
 
    });
 
</code>
 
 
 
For more details the source code of the PIWIK adapter is A very good starting point.
 
 
 
==== Overwrite predefined adapter ====
 
 
 
Please take a look at the [[AppSuite:Extending_the_UI#replace_extension | extension point documentation]].
 
=== PIWIK ===
 
 
 
Predefined adapter for the open-source analytics platform.
 
 
 
==== source ====
 
 
 
<code>
 
  io.ox/metrics/adapters/default.js
 
</code>
 
 
 
==== hint ====
 
 
 
Be aware to not use a name for your javascript files that matching common patterns of adblockers. For example in case we would name default.js PIWIK.js the adblocker would block the request and an error occurred in the the browser.
 
 
 
==== data mapping: app starting ====
 
 
 
This represents the impact of a user interaction not the interaction itself.
 
 
 
===== Page titles =====
 
 
 
Every time a module/app is used for the first time for each visit the corresponding event will be triggered.
 
 
 
You can interpret page titles as '[appname] was started [x] times'. Please be aware that after a full refresh of the browser tab used by OX Appsuite the app usage is tracked again.
 
 
 
 
 
==== data mapping: tracked user interaction ====
 
 
 
This represents a user interaction like a click on a functional ui element.
 
 
 
 
 
===== Event action =====
 
 
 
This part contains all main information about the whole event data condensed in a single string.
 
 
 
[appname]/[location in the ui]/[action]
 
 
 
''example: 'mail/toolbar/delete' ''
 
 
 
 
 
===== Event category =====
 
This part of the event data contains the application were the event occurred. You can Interpret it as 'a user action within [appname] occurred'. Please be aware that the category is based on the technical app that might differ from the abstract application that is communicted by the user interface.
 
 
 
''example: 'io.ox/mail' ''
 
 
 
 
 
===== Event name =====
 
 
 
The event id.
 
 
 
''example: 'delete' ''
 
 
 
 
 
===== Event value=====
 
 
 
An optional value that might contain further details about the event.
 
 
 
=== Console ===
 
 
 
A special predefined debugging adapter that simply writes events to console.
 
 
 
==== source ====
 
 
 
<code>
 
  io.ox/metrics/adapters/console.js
 
</code>
 
 
 
==== hint ====
 
 
 
You can activate this special adapter that writes events to console and tracks all events in browsers localstorage. To activate/deactivate simply paste this code into your console when you are logged in at appsuite:
 
 
 
<code javascript>
 
  // enable
 
  require('settings!io.ox/core').set('tracking/console/enabled', true).save();
 
 
 
  // disable
 
  require('settings!io.ox/core').set('tracking/console/enabled', false).save();
 
</code>
 
You can see all tracked events by using the browers console again:
 
 
 
<code javascript>
 
  //directly accessing to the data
 
  metrics.hash
 
 
 
  // please use the following only in chrome cause it is using console.table
 
  metrics.show()
 
</code>
 
  
 
[[Category:AppSuite]]
 
[[Category:AppSuite]]
 
[[Category:UI]]
 
[[Category:UI]]
 
[[Category:Metrics]]
 
[[Category:Metrics]]

Latest revision as of 10:21, 12 July 2016

This information is valid from 7.8.0

Adapters

The content on this page has moved to https://documentation.open-xchange.com/latest/ui/features/metrics/02-adapters.html.

Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.