Custom Reports: Extended

This is the follow-up to our Custom Reports guide.

Implementing the API method

Our new report will use realtime visit data. To get it, our API method will use the Live.getLastVisitsDetails method:

public function getLastVisitsByBrowser($idSite, $period, $date, $segment = false)
{
    $data = \Piwik\API\Request::processRequest('Live.getLastVisitsDetails', array(
        'idSite' => $idSite,
        'period' => $period,
        'date' => $date,
        'segment' => $segment,
        'numLastVisitorsToFetch' => 100,
        'minTimestamp' => false,
        'flat' => false,
        'doNotFetchActions' => true
    ));
    $data->applyQueuedFilters();

    // TODO

    return false;
}

$data will be a DataTable instance that stores information about visits; each visit being a DataTable row.

Now that we've got a list of visits, let's think about what our report will look like. Our report will count the number of visits for each browser. So each row will have the browser name and the number of visits. It might look something like this:

label   | nb_visits
-------------------
Chrome  | 24
Firefox | 32
Safari  | 28

To create the report, we'll go through every visit and increment the counter for the browser. The counter will be the nb_visits column.

Change the method to the following:

public function getLastVisitsByBrowser($idSite, $period, $date, $segment = false)
{
    $data = \Piwik\API\Request::processRequest('Live.getLastVisitsDetails', array(
        'idSite' => $idSite,
        'period' => $period,
        'date' => $date,
        'segment' => $segment,
        'numLastVisitorsToFetch' => 100,
        'minTimestamp' => false,
        'flat' => false,
        'doNotFetchActions' => true
    ));
    $data->applyQueuedFilters();

    // we could create a new instance by using new DataTable(),
    // but we would lose DataTable metadata, which can be useful.
    $result = $data->getEmptyClone($keepFilters = false);

    foreach ($data->getRows() as $visitRow) {
        $browserName = $visitRow->getColumn('browserName');

        // try and get the row in the result DataTable for the browser
        $browserRow = $result->getRowFromLabel($browserName);

        // if there is no row for this browser, create it
        if ($browserRow === false) {
            $result->addRowFromSimpleArray(array(
                'label'     => $browserName,
                'nb_visits' => 1
            ));
        } else { // if there is a row, increment the counter
            $counter = $browserRow->getColumn('nb_visits');
            $browserRow->setColumn('nb_visits', $counter + 1);
        }
    }

    return $result;
}

If you visit http://localhost/index.php?module=API&method=MyPlugin.getLastVisitsByBrowser&idSite=1&date=today&period=week you should see the new report!

Displaying the report

Now that we've defined a new report, we need to define how the report should be displayed. We'll do this by going back to the GetLastVisitsByBrowser class and modifying the configureView() method:

public function configureView(ViewDataTable $view)
{
    // The ViewDataTable must be configured so the display is perfect for the report.
    // We do this by modifying properties on the ViewDataTable::$config object.

    // Disable the 'Show All Columns' footer icon
    $view->config->show_table_all_columns = false;
    // The 'label' column will have 'Browser' as a title
    $view->config->addTranslation('label', 'Browser');

    $view->config->columns_to_display = array_merge(array('label'), $this->metrics);
}

As we will only display the number of visitors, and not the number of unique visitors or actions which Matomo assumes by default, we need to modify the supported metrics in the init() method of the report as follows:

$this->metrics = array('nb_visits');

The report should now look like this:

Updating the report in realtime

So now there's a page with a report that shows the browsers used by the latest visitors. It uses realtime data - but it's not truly realtime since after a couple of minutes, the report will be out-of-date. To make the report more realtime we'll update the report every 10 seconds automatically.

Adding JavaScript files to Matomo

To make the report reload itself, we'll have to write some JavaScript code. This means we'll need a JavaScript file.

Create an empty javascripts/plugin.js file in your plugin directory. Then register to the AssetManager.getJavaScriptFiles event (read more about Events) to have this javascript file included by Matomo:

class MyPlugin extends \Piwik\Plugin
{
    public function registerEvents()
    {
        return array(
            'AssetManager.getJavaScriptFiles' => 'getJavaScriptFiles',
        );
    }

    public function getJavaScriptFiles(&$files)
    {
        $files[] = 'plugins/MyPlugin/javascripts/plugin.js';
    }
}

Remember that Matomo will include this file directly only when disable_merged_assets is enabled in your ini config:

[Development]
disable_merged_assets = 1

If this option is disabled, Matomo will merge all JavaScript files into one to optimize the page loading time, but that means that any change to plugin.js will be ignored.

Reloading the report

In your plugin.js file, add the following code:

$(document).ready(function () {

    setInterval(function () {

        // get the root element for our report
        var $dataTableRoot = $('.dataTable[data-report="MyPlugin.getLastVisitsByBrowser"]');

        // in the UI, the root element of a report has a JavaScript object associated to it.
        // we can use this object to reload the report.
        var dataTableInstance = $dataTableRoot.data('uiControlObject');

        // we want the table to be completely reset, so we'll reset some
        // query parameters then reload the report
        dataTableInstance.resetAllFilters();
        dataTableInstance.reloadAjaxDataTable();

    }, 10 * 1000);

});

As you can see, all our javascript code is inside the $(document).ready callback. This is because we want the JavaScript code to be executed when the page is fully loaded.

Now if you open the report in your browser, you'll see the report being reloaded every 10 seconds.