|
|
| (15 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| | {{Version|7.8.0}} |
| | |
| == Metrics == | | == Metrics == |
|
| |
|
| === Introduction ===
| | The content on this page has moved to https://documentation.open-xchange.com/latest/ui/features/metrics.html. |
| | |
| 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.
| |
| | |
| === Parts and 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 [[#backend|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 =====
| |
| | |
| <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
| |
| </code>
| |
| | |
| ==== 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 =====
| |
| | |
| <code>
| |
| // global switch [true/false]
| |
| // current default: true
| |
| io.ox/core//tracking/enabled
| |
| </code>
| |
| | |
| <code>
| |
| // consider doNotTrack-flag in front end [true/false]
| |
| // current default: false
| |
| io.ox/core//tracking/donottrack
| |
| </code>
| |
| | |
| ===== Adapterspecific =====
| |
| | |
| <code>
| |
| // 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
| |
| | |
| </code>
| |
| | |
| === Step-by-step Setup guide ===
| |
| | |
| 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.
| |
| | |
| === Details ===
| |
| | |
| ==== Overview ====
| |
| | |
| {{metrics-01.jpg| image}}
| |
| | |
| ==== Listener ====
| |
| | |
| With metrics in mind listeners are waiting for special events to occur - usually a user action that manifests as a mouse click.
| |
| | |
| Common practice is to register listeners by using jQuerie’s delagate (TODO: link) function. For example this snippet would listen for any mousedown event on an action icon within the mail app toolbar.
| |
| | |
| <code javascript>
| |
| $('.classic-toolbar-container').delegate('.io-ox-action-link', 'mousedown', yourHandler);
| |
| </code>
| |
| hint: please do not register these listeners when metrics is disabled to avoid unnecessary work for the client.
| |
| | |
| ==== Handlers ====
| |
| | |
| Handler call the public functions of the metrics module. To gain access to the metrics object simply require ‘io.ox/metrics/main’.
| |
| | |
| <code javascript>
| |
| require(['io.ox/metrics/main'], function(metrics) {
| |
| metrics.trackEvent({
| |
| app: 'mail',
| |
| target: 'detail/toolbar',
| |
| type: 'click',
| |
| action: $(e.currentTarget).attr('data-action')
| |
| });
| |
| });
| |
| | |
| </code>
| |
| ==== Metrics module ====
| |
| | |
| The metrics module provide some simple api that enables you to track events.
| |
| | |
| ===== trackEvent() =====
| |
| | |
| //app//
| |
| | |
| * application name
| |
| * //example: ‘mail’//
| |
| | |
| //target//
| |
| | |
| * container/area
| |
| * //example: ‘detail/toolbar’//
| |
| | |
| //type//
| |
| | |
| * type of event
| |
| * //example: ‘click’//
| |
| | |
| //action//
| |
| | |
| * name/id of the action
| |
| * //example: ‘delete’//
| |
| | |
| ===== trackPage() =====
| |
| | |
| //name//
| |
| | |
| * name of the page. for OX Appsuite this is the name of the application
| |
| * //example: ‘mail’//
| |
| | |
| //id//
| |
| | |
| * id of the page.
| |
| * //example: ‘io.ox/mail’//
| |
| | |
| //name//
| |
| | |
| * name of the page
| |
| * //example: ‘Mail’//
| |
| | |
| ===== trackVariable() =====
| |
| | |
| * currently unused
| |
| | |
| ===== watch(options, data) =====
| |
| | |
| Shortcut to register a trackEvent listener by using _.delegate on a container node
| |
| | |
| <code javascript>
| |
| watch({
| |
| node: $('#my-actions'),
| |
| selector: '#my-button',
| |
| event: 'click'
| |
| }, dataToTrack)
| |
| | |
| </code>
| |
| ===== getUserHash() ====
| |
| | |
| return unique user (based on cookie value)
| |
| | |
| ===== isEnabled() =====
| |
| | |
| returns boolean that indicates status of the metrics module
| |
| | |
| <code javascript>
| |
| require(['io.ox/metrics/main'], function (metrics) {
| |
| var name = app.get('parent').get('name') || 'unknown',
| |
| apptitle = _.last(name.split('/')),
| |
| facet = model.get('facet').get('id').split(':')[0];
| |
| // toolbar actions
| |
| metrics.trackEvent({
| |
| app: apptitle,
| |
| target: apptitle + '/search/facet/' + facet,
| |
| action: 'search',
| |
| value: facet
| |
| });
| |
| });
| |
| </code>
| |
| | |
| ===== Adapters =====
| |
| | |
| ====== PIWIK ======
| |
| | |
| **source**
| |
| | |
| //io.ox/metrics/adapters/default.js//
| |
| | |
| **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 ocurred in the the browser.
| |
| | |
| **consider settings**
| |
| | |
| please add at first a line into the code that checks for the user setting to prevent registering the adapter (more precisecly to extend the extension point)
| |
| | |
| <code javascript>
| |
| if (!settings.get('tracking/[add-your-id-here]/enabled', false)) return;
| |
| </code>
| |
| | |
| **extend**
| |
| | |
| Now you will have to extend ‘io.ox/metrics/adapter’ to register your adapter. The metrics module will run through all registered adapters and calls existing functions.
| |
| | |
| <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 further questions please take a look at the PIWIK adapter in the source code.
| |
| | |
| ====== Console ======
| |
| | |
| You can activate a special debugging adapter that writes events to console and tracks all events in browers 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>
| |
| | |
| === Events ===
| |
| | |
| ==== General ====
| |
| | |
| ===== Header/Logo =====
| |
| | |
| {| class="wikitable"
| |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | core/banner/title
| |
| | Click on header title
| |
| |-
| |
| | core/banner/logo
| |
| | Click on header logo
| |
| |}
| |
| | |
| ==== File Viewer ====
| |
| | |
| {| class="wikitable"
| |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | core/viewer/toolbar/[action]
| |
| | User clicks on action while using the file viewer
| |
| |}
| |
| | |
| ==== Settings ====
| |
| | |
| {| class="wikitable"
| |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | core/toolbar/[action]
| |
| | Upsell event triggered
| |
| |}
| |
| | |
| | |
| ==== Upsell ====
| |
| | |
| {| class="wikitable"
| |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | core/upsell/[upsell.type]/[upsell.id]
| |
| | Clicks (settings, my contact data, help, getting started, fullscreen, about, sign out) within the context menu of our settings icon at the top right.
| |
| |}
| |
| | |
| ===== Apps =====
| |
| | |
| ==== Portal ====
| |
| | |
| {| class="wikitable"
| |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | portal/toolbar/add/[type]
| |
| | Click on “Add widget” button in upper right area of portal.
| |
| |-
| |
| | portal/toolbar/add/[type]
| |
| | Click on a specific widget to “install” it on the portal page.
| |
| |-
| |
| | portal/widgets/show-detail/[type]
| |
| | Click on the area of the widget, which gets displayed.
| |
| |-
| |
| | portal/widget/disable/[type]
| |
| | Click on the remove widget icon (“X”)
| |
| |-
| |
| | portal/widget/change-order/[type]
| |
| | Reordering a widget into another location on the screen.
| |
| |}
| |
| | |
| ==== Mail ====
| |
| | |
| {| class="wikitable"
| |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | mail/list/[layout]/select/one, mail/list/[layout]/select/mulitple
| |
| | Select mail by click on the list/grid (layout: vert, horiz, compact, list)
| |
| |-
| |
| | mail/toolbar/[action], mail/detail/toolbar/[action] , mail/compose/toolbar/[action]
| |
| | Clicks on a email action
| |
| |-
| |
| | mail/folders/folder/select/[type]
| |
| | Clicks on a folder in the mail folder tree (type: primary, external)
| |
| |-
| |
| | mail/folder/account/add
| |
| | Clicks on “Add new mail account”
| |
| |-
| |
| | mail/settings/account/add
| |
| | Clicks within “Social + Mail Accounts” on “Add account”
| |
| |}
| |
| | |
| ==== Contacts ====
| |
| | |
| {| class="wikitable"
| |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | contacts/list/select/one, contacts/list/select/multiple
| |
| | Select contact by click on the list/grid
| |
| |-
| |
| | contacts/folder/select/[type]
| |
| | Clicks on a folder in the contact folder tree (folder-type: private, public, shared)
| |
| |-
| |
| | contacts/toolbar/[action]
| |
| | Clicks on a a contact action
| |
| |}
| |
| | |
| ==== Calendar ====
| |
|
| |
|
| {| class="wikitable"
| | 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. |
| ! style="font-weight: bold;" | EventId
| |
| ! style="font-weight: bold;" | Trigger
| |
| |-
| |
| | calendar/toolbar/[action]
| |
| | Clicks on calendar toolbar action
| |
| |-
| |
| | calendar/folder/select/[type]
| |
| | Clicks on a folder in the contact folder tree (folder-type: private, public, shared)
| |
| |-
| |
| | calendar/folder/permissions
| |
| | Clicks on the “cloud” icon and the “User” icon next to the folder name
| |
| |-
| |
| | calendar/folder/context-menu/[action]
| |
| | Clicks within the context menu, which pops up, when you click on a folder name and its menu icon
| |
| |-
| |
| | calendar/detail/toolbar/[action]
| |
| | Clicks on calendar detail view toolbar action
| |
| |}
| |
|
| |
|
| ==== Tasks ==== | | === Further reading === |
|
| |
|
| ^EventId ^Trigger ^
| | * [https://documentation.open-xchange.com/latest/ui/features/metrics/01-details.html Details]: the metrics framework components in detail |
| |tasks/folder/select/[type] |Clicks on a folder in the contact folder tree (folder-type: private, public, shared) |
| | * [https://documentation.open-xchange.com/latest/ui/features/metrics/02-adapters.html Adapters]: connections between OX App Suite metrics and the Analytics solutions |
| |tasks/folder/context-menu/[action]|Clicks within the context menu, which pops up, when you click on a folder name and its menu icon|
| | * [https://documentation.open-xchange.com/latest/ui/features/metrics/03-analytics-solutions.html Analytics Solutions]: details and how to setup |
| |tasks/toolbar/[action] |Clicks on tasks toolbar action |
| | * [https://documentation.open-xchange.com/latest/ui/features/metrics/09-events.html Events]: list of tracked events so far |
| |tasks/detail/[action] |Clicks on calendar detail view toolbar action |
| |
|
| |
|
| ==== Drive ====
| |
|
| |
|
| ^EventId ^Trigger ^
| | [[Category:AppSuite]] |
| |drive/folder/select/[type] |Clicks on a folder in drive folder tree (folder-type: standard_folder_type + '.' + folder_type) |
| | [[Category:UI]] |
| |drive/folder/context-menu/[action]|Clicks within the context menu, which pops up, when you click on a folder name and its menu icon|
| | [[Category:Metrics]] |
| |drive/toolbar/[action] |Clicks on tasks toolbar action |
| |