Tutorial: How to implement Piwik Data in Template Files

[Luis]

Hello Processwire folks,

today I want to show how to implement piwik into Processwire to show some specific site details to visitors or, if you create a special frontend login, for yourself. 

First Step (preparation):

What do we need?

Well, to grab piwik data we need the piwik open source analytics suite. 

Grab your copy here: http://piwik.org/

Now copy piwik right into your Processwire folder, you get a folder structure like: piwik, site,wire

next install piwik!

After installation log into your piwik dashboard and setup your site, we need some information from piwik later in the tutorial, so just let the piwik dashboard open in the background.

Now we have to think about data presentation.

I´m currently working on a Webapp to let customers create their own Landing Pages and measure their performance, to show the data I´ve choosen morris.js a goodlooking javascript based on raphael.js and jQuery.

So, we need jQuery. morris.js and raphael.js.

jQuery : http://jquery.com/

morris.js : http://www.oesmith.co.uk/morris.js/

raphael.js : http://raphaeljs.com/

Install all three scripts in your Processwire templates folder and dont forget to copy the provided .css file, too. 

Second Step (Connect to the piwik API):

To grab data from piwik we have to include the piwik API in our Processwire installation and we need some special settings to do.

We need 2 informations about our piwik installation:

1st our own Auth Token

2nd the SiteID of our tracked page

You could find your Auth Token in the piwik Dashboard. Just click on API in the head menu and there it is, in this little green box. 

Now we need to know the site id of our page we want to show in our template files. 

If you only setup one page in piwik the SiteId is 1, if you setup multiple sites click on "all websites" in the head menu now click on add new site. 

Now you could see all your pages and their own site Id. 

Remember where to find this informations, we need them in our next steps.

Third Step (templating and API connection):

Go to your PW Admin and create a new Template. 

We don´t need any fields so far, so title and body would be enough, now create a new page with your new template. 

Thats it on clicki bunti side, we now have to open our favorite ninja code editor. 

Create a new file in your templates folder named like the template you created.

Create a new file in a subfolder of your templates folder, maybe if exists in scripts or includes, wherever your include files are.

Name this file analyticSettings.php

This is our piwik API connector.

Copy and paste the following code:

<?php
// if you don't include 'index.php', you must also define PIWIK_DOCUMENT_ROOT
// and include "libs/upgradephp/upgrade.php" and "core/Loader.php"
define('PIWIK_INCLUDE_PATH', realpath($config->paths->root.'/piwik'));
define('PIWIK_USER_PATH', realpath($config->paths->root.'/piwik'));
define('PIWIK_ENABLE_DISPATCH', false);
define('PIWIK_ENABLE_ERROR_HANDLER', false);
define('PIWIK_ENABLE_SESSION_START', false);

require_once PIWIK_INCLUDE_PATH . "/index.php";
require_once PIWIK_INCLUDE_PATH . "/core/API/Request.php";

Piwik_FrontController::getInstance()->init();

function piwikRequest($piwikSiteId,$piwikMethod,$piwikPeriod,$piwikDate,$piwikSegment,$piwikColumns, $piwikColumnsHide)
{
  $piwikGetData = new Piwik_API_Request
  ('
    method='. $piwikMethod .'
    &idSite='. $piwikSiteId .'
    &period='. $piwikPeriod .'
    &date='. $piwikDate .'
    &format=php
    &serialize=0
    &token_auth=AUTH TOKEN
    &segment='.$piwikSegment.'
    &showColumns='. $piwikColumns .'
    &hideColumns='. $piwikColumnsHide .'
  ');
  $piwikGetData = $piwikGetData->process();
  return $piwikGetData;
}

?>

line 1 - 14 sets the paths to the piwik API and setup some error handling for piwik. 

Enter your own Auth Token in line 26. 

Thats it, connection to piwik allready done. 

Now lets see how we grab our data.

There is a function beginning in line 15. I named this little friend piwikRequest. 

You could pass 7 values to our function to define which, how many, which date,period and method we want to request from piwik.

$piwikSiteId = from which tracked page we need data. 

$piwikMethod = which data method do we need? You could find a full list here: http://piwik.org/docs/analytics-api/reference/#toc-standard-api-parameters

$piwikPeriod = day, year, moth, week

$piwikDay= today, yesterday

$piwikSegment = Segment of data, e.g. pageTitle==home

$piwikColumnsShow = Only grab Data from this columns in the piwik database

$piwikColumnsHide = Do not grab data from this columns 

So, if we want to grab the visitor count from yesterday we could call our function like this:

<?php echo piwikRequest('3','VisitsSummary.getVisits','day','yesterday' ?>

3 = id of tracked site from piwik (I use piwik to track frontend, backend and the user created landing pages in its own site)

VisitsSummary.getVisits = our API Method to tell piwik which data we need

day = our period

yesterday = well yes, data from yesterday

This request returns just a neat integer so there is no need to do additional logic, if we use methods providing more data the function returns an array which could be displayed by an print_r() or json_encode()

Well our piwik connection is ready, now we want to show some data on our template file. 

The Templating:

Open your template file, make sure you included all needed files from jquery, morris and raphael. 

Include on top of the page your piwik api connector file.

Make sure that jquery, morris.js and raphael.js are included in this order and above the html code.

Order:

jQuery

Rapaehl.js

Morris.Js

We now want to show 2 Donuts with 2 data values each. 

Visits today and Yesterday.

Total pageviews from this year, unique and all. 

Copy and paste the following code to your template file:

<h2>Visitors</h2>
<div id="donut" style="height:200px;"></div>

<h2>Page Views</h2>
<div id="donut2" style="height:200px;"></div>
<script>
Morris.Donut({
  element: 'donut',
  data: [
    {label: "Yesterday", value: <?= piwikRequest('3','VisitsSummary.getVisits','day','yesterday') ?>},
    {label: "Today", value: <?= piwikRequest('3','VisitsSummary.getVisits','day','today' ) ?>},
  ]
});
Morris.Donut({
  element: 'donut2',
  data: [
    {label: "unique", value: <?= piwikRequest('3','Actions.get','year','yesterday',' ','nb_uniq_pageviews') ?>},
    {label: "all", value: <?= piwikRequest('3','Actions.get','year','yesterday',' ','nb_pageviews') ?>}
  ]
});
</script>

We add 2 empty divs with some inline css. You could change this via a stylesheet. 

In this 2 divs the morris script will draw a donut with the grabbed data from piwik.

Right under the divs we are calling our morris.js and provide data from our piwikRequest function. 

Thats all

You could find all piwik methods, dates, periods and so on in the piwik api reference here: 

http://piwik.org/docs/analytics-api/reference/#toc-standard-api-parameters

[pwired]

WoW Luis, thats a real interesting tuto you put there, kudos for that. I stumbled upon piwik a couple of months ago but never found the time to dig it. Your tuto is going to change that. Can you say something more about the difference between google analytics and piwik ?

[Luis]

hm difference, well with piwik you own your data, with google not. 

I didn´t worked with gAnalytics much nor with piwik, so I´m not really the best spokesman to outline the pros and cons of both. 

I worked a lot with OpenWebAnalytics, but it looks like the developer stopped to work on it, therefor I give piwik a try in this project. 

[pwired]

I read somewhere that with google analytics, If you use Adwords they will know what works and start charging you more for CTR. I guess this would be different with piwik. Something similar happened to me when buying on-line flight tickets. If you visit a flight agency, look for prices, leave the website and then come back again to the same page, suddenly the price for the same ticket goes up ! Using a different computer with a different ip shows the old price. I have seen it happen.

[Manfred62]

here is an nice article: http://www.statstory.com/some-reasons-to-choose-piwik-analytics-over-google-analytics/

The main difference is, like Luis said, the data is on your server (and not on a third-party server). Also there are some terms about data collecting you have to keep an eye on, especially in Germany the rules are more or less restrictive.

[Luis]

I attached a screenshot to show what I did with processwire - piwik