Expose usage stats at the object/node level

[mjordan]

https://github.com/Islandora-Labs/islandora_usage_stats_charts provides usage stats for a single Islandora 7 object. We should create a block that does the same for usage data for Islandora 8 objects collected by Matomo.

https://www.drupal.org/project/matomo_reporting_api will be useful for this.

Related issues:

• Meta-Issue: Usage Stats #792
• Use case: Counting and exposing usage stats for multisites #1073

[mjordan]

Been playing around with Motomo's API and have been able to get it to generate a graph showing node-level page views in a block, like this:

Here is the proof of concept block plugin that renders this graph:

<?php

/**
 * @file
 */

namespace Drupal\matomo_charts\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Provides a block showing the Solr representation of the object.
 *
 * @Block(
 * id = "matomo_charts",
 * admin_label = @Translation("Matomo usage chart for this object"),
 * category = @Translation("Islandora"),
 * )
 */
class MatomoChartsBlock extends BlockBase {
  /**
   * {@inheritdoc}
   */
  public function build() {
    $node = \Drupal::routeMatch()->getParameter('node');
    if ($node) {
      $token_auth = '7165b664aadfcf9d95532cb6e0879275';
      $matomo_url = "http://localhost:8000/matomo/index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=Actions&apiAction=get&token_auth=" . $token_auth . "&graphType=evolution&period=day&date=previous30&width=500&height=250&pageUrl=http://localhost:8000/node/" . $node->id();;
      $markup = '<img src="' . $matomo_url . '">';
      return [
        '#children' => $markup,
      ];
    }
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheMaxAge() {
    return 0;
  }

}

Note that 1) this block doesn't use the Matomo Reporting API module, and 2) this PNG is generated by Matomo. https://developer.matomo.org/api-reference/reporting-api-metadata provides examples of some other graphs generated by Matomo.

Tagging @manez @bryjbrown @DonRichards @Natkeeran

[mjordan]

Sorry, I posted that graph prematurely. It shows page visits for the entire site, not that node. https://developer.matomo.org/api-reference/reporting-api#Actions shows the actions that are available, but when I use apiAction=getPageUrl (singluar, for the current node) the image contains the error message "Invalid API module and/or API Action". Using apiAction=getPageUrls (plural) produces a valid graph, but not the one we want.

If we want this type of node-level graph, it's just a matter of someone figuring out Matomo's rather esoteric API. Or, if Matomo can't generate the graphs we want, get the raw data from Matomo and generate the chart with Chart.js or something similar.

[mjordan]

It is possible to get a summary of activity for a specific URL/node, so another way to do this would be to loop through monthly time ranges and query Matomo for hits/visits for a node during each period, then assemble those monthly counts into a report like this:

[mjordan]

Now that the awesome https://github.com/asulibraries/islandora_matomo is available, we can start thinking about how to generate node-level reports for emailing to authors, etc.

This drush code generates a very simple "usage report" for each node in my vagrant of type Repository Item:

<?php

namespace Drupal\islandora_matomo_node_group_reports\Commands;

use Drush\Commands\DrushCommands;

/**
 * Drush commandfile.
 */
class IslandoraMatomoNodeGroupReportsCommands extends DrushCommands {

  /**
   * Some proof of concept code.
   *
   * @command islandora_matomo_node_group_reports:generate_reports
   * @usage islandora_matomo_node_group_reports:generate_reports
   */
  public function generateReports() {
    $output = $this->output();

    // Get all nodes. IRL this would be get all nodes that have a specific field
    // populated, like "Author". Here, we get nodes whose titles are not blank
    // (i.e., all nodes).
    $query = \Drupal::entityQuery('node')
      ->condition('type', 'islandora_object')
      ->condition('title', '', '<>'); // <-This could be the author field, etc.
    $results = $query->execute();
    $nids = array_values($results);

    // IRL this list of node IDs would be of all the nodes by an author.
    $output->writeln('---------------------- Usage report for your items! -----------------');
    foreach ($nids as $nid) {
      $node = \Drupal::entityTypeManager()->getStorage('node')->load($nid);
      $node_views = \Drupal::service('islandora_matomo.default')->getViewsForNode(['nid' => $nid]);
      $output->writeln('"' . $node->getTitle() . '": ' . $node_views  . ' views');
    }
  }
}

Here is its output:

---------------------- Usage report for your items! -----------------
"Test image": 6 views
"Test image 2": 2 views
"Canterbury Stories": 8 views
"Mirador test": 34 views
"1491 finale": 15 views
"Media multifile test - pdf": 3 views
"1582 test": 9 views
"1582 test 2": 2 views
"Issue 740 test": 2 views
"Issue 740 test 2": 54 views
"Collection 1": 1 views
"Collection 2": 1 views

So what, who cares?

If our query was to get all the nodes that had something in their "author" field, and grouped the resulting nodes by unique author, we could get the usage for all those nodes during the last month, generate a nice looking email containing the summary of usage of those nodes, and email each author's report to them.

Getting the email address of the author is going to be the hardest part of making this totally work.

[elizoller]

if you can associate an "author" with a "user" in the drupal system then you've got an email, right? is that applicable to your use case here? if a person wants an email digest of their works, they have to log in to the system to begin with, right?

[mjordan]

Not sure at the moment. I'm meeting with the IR migration team tomorrow and will be asking about this.

[mjordan]

@elizoller Looks like we've settled on using the email address in the user object. Each IR item can have one or more "SFU Authors" linked to it (SFU Author is a content type, linked to the IR item via node reference); users with an SFU Author node will get stats for all linked IR items. To get an SFU Author node, you need a Drupal account, which our IR office creates on request.

[elizoller]

Looks like you've solved the "hardest part" then 👍

[rosiel]

Use case phrasing: "As a collection manager I wish to review a report that shows traffic and download of objects in my repository."