inchorus Matomo Plugin Dokumentation

Das Matomo-Plugin (ehemals Piwik) bietet Ihnen die wesentlichsten Funktionen zum Abfragen eines Matomo Servers zur Webanalyse.

Folgende Funktionalitäten stehen zur Verfügung:

Die jeweiligen Server Antworten werden im XML Format zurückgegeben.

Weitere Informationen zu Matomo und zur verwendeten HTTP API finden Sie auf Matomo.org und in der Matomo API Reference.

Plugin einbinden

Öffnen Sie die Datei pom.xml Ihres inchorus Gadget Projektes und ergänzen Sie folgende Zeilen im Abschnitt "dependencies":

<dependency>
	<groupId>de.guh.plugin</groupId>
	<artifactId>inchorus-matomo-plugin</artifactId>
	<version>2.0.0</version>
</dependency>

Initialisieren des Matomo Plugins

String url = "https://demo.matomo.cloud/";
String authenticationtoken = "anonymous";

MatomoSystem system = new MatomoSystem(url, authenticationtoken);

Zum Initialisieren und Verwenden des Matomo Plugins, werden lediglich die URL zum Matomo Server und der Authentication-Token benötigt, die dem Konstruktor übergeben werden. Die Verbindung zum Server wird aufgebaut, sobald eine Anfrage gesendet wird.

Definieren von Analysezeiträumen

Wenn Anfragen an den Server gestellt werden sollen, muss der Zeitraum bestimmt werden, für den die Analysedaten abgefragt werden sollen. Beispielsweise können die Daten für die letzten fünf Wochen benötigt werden, wobei diese jeweils pro Woche angegeben werden sollen. Diese Zeiträume werden durch eine Kombination aus zwei Datenklassen dargestellt: MatomoDate und MatomoPeriod.

Die Date Klasse gibt entweder ein bestimmtes Datum, oder eine Spanne von Daten an, die abhängig von der gewählten Periode ist. Date kann entweder die Werte TODAY bzw. YESTERDAY annehmen, der Zeitraum entspricht dann der Periode, in der der aktuelle bzw. vorherige Tag liegt. Oder es können die letzten X Perioden abgefragt werden, indem Date auf die Werte LAST bzw. PREVIOUS mit der Anzahl X der letzten Perioden gesetzt wird. Diese vier Werte sind als Konstanten in der Klasse MatomoDate definiert, bei Verwendung von LAST wird im Gegensatz zu PREVIOUS der aktuelle Tag mit eingeschlossen.

Die Period Klasse kann einen der Werte DAY, WEEK, MONTH, YEAR oder RANGE annehmen, die in der Klasse MatomoPeriod als Konstanten definiert sind. Wird zum Beispiel für Date der Wert TODAY und für für Period der Wert YEAR gewählt, wird die Zusammenfassung der Daten für das aktuelle Jahr abgefragt. Wird für Date der Wert LAST, mit der Anzahl 5 und für für Period der Wert WEEK gewählt, werden die Daten für das anfangs erwähnte Beispiel abgefragt: Die Daten der letzten fünf Wochen, jeweils zusammengefasst für jede Woche.

Abfragen von festen Daten oder Zeiträumen im Datumsformat sind in der Version 1.0.1 nur über die Methode für benutzerdefinierte Anfragen möglich und nicht über die verfügbaren Date und Period Klassen.

Folgender Code zeigt die Umsetzung des obigen Beispiels mit den verfügbaren Klassen:

MatomoDate date = new MatomoDate(MatomoDate.LAST, 5);
MatomoPeriod period = new MatomoPeriod(MatomoPeriod.WEEK);

Zu beachten ist, dass bei der Klasse Day für die Werte TODAY oder YESTERDAY ein anderer Konstruktor verwendet werden muss, als für LAST und PREVIOUS, die zusätzlich eine Anzahl übergeben bekommen müssen.

Anfragen an den Matomo Server stellen

Um eine Anfrage an den Server zu stellen, kann einer der in MatomoSystem definierten Methoden verwendet werden. Alle verfügbaren Methoden und ihre Verwendung sind in der API Dokumentation bzw. den Beispielen zu finden.

Beispielsweise können mit VisitsSummary_get() Informationen zu den Seitenaufrufen abgefragt werden:

XML visits = system.VisitsSummary_get("1", period, date, 100);

Die verwendeten Objekte system, date und period beziehen sich auf die in den obigen Codebeispielen instantiierten Objekte. Das erste Argument "1" gibt an welche Website ID verwendet werden soll und das letzte Argument 100 gibt die maximale Anzahl an Ergebniszeilen in der Antwort an. Setzt man diesen Wert auf null, dann werden alle Zeilen zurückgegeben. Die Antwort wird im XML Format zurückgeliefert, wobei jede Ergebniszeile ein Kindknoten für jede Periode mit dem betreffenden Datum als Attribut ist. Zum Beispiel für die Woche des 06.08.2021:

<results>
  <result date="2021-08-02,2021-08-08">
    <nb_uniq_visitors>20943</nb_uniq_visitors>
    <nb_users>7</nb_users>
    <nb_visits>23319</nb_visits>
    <nb_actions>42235</nb_actions>
    <nb_visits_converted>1474</nb_visits_converted>
    <bounce_count>15345</bounce_count>
    <sum_visit_length>3803594</sum_visit_length>
    <max_actions>27</max_actions>
    <bounce_rate>66%</bounce_rate>
    <nb_actions_per_visit>1.8</nb_actions_per_visit>
    <avg_time_on_site>163</avg_time_on_site>
  </result>
</results>

Zusätzlich zu den in Matomo standardmäßig verfügbaren Modulen, bietet das Matomo Plugin die Möglichkeit die N meistbesuchten Seiten in sortierter Reihenfolge in einem leicht abweichenden XML Format ausgeben zu lassen. Die Methode Custom_getTop10PageTitles(siteids, period, date, size) liefert das Ergebnis für den angegebenen Zeitraum, wobei size die Anzahl der gewünschten meistbesuchten Seiten darstellt. Das Ergebnis wird im folgenden XML Format zurückgegeben:

<tops>
  <top>
	<label>Seitentitel #1</label>
	<visits>Anzahl Aufrufe</visits>
  </top>
  <top>
	<label>Seitentitel #2</label>
	<visits>Anzahl Aufrufe</visits>
  </top>
  ...
   <top>
	<label>Seitentitel #N</label>
	<visits>Anzahl Aufrufe</visits>
  </top>
</tops>

Die Knoten sind hier entsprechend benannt und nach Anzahl der Aufrufe sortiert.

Nähere Informationen zu den Klassen und Methoden finden sie in der API Dokumentation.

Beispiele finden Sie im Ordner Beispiele.

Bei Fragen und Anregungen nutzen Sie unser inchorus Forum.

Dieses Dokument erhalten sie hier auch als PDF.

G+H Systems GmbH

Professionell, effizient und zuverlässig.

Ludwigstraße 8

63067 Offenbach am Main

Deutschland

Telefon: +49 (0) 69 85 00 02 - 0

Fax: +49 (0) 69 85 00 02 - 51

Email: info@guh-systems.de

Web: www.guh-systems.de

Die G+H Systems leistet keinerlei Gewähr bezüglich des Inhaltes oder Gebrauchs dieser Dokumentation. Insbesondere werden keine ausdrücklichen oder stillschweigenden Gewährleistungen hinsichtlich der handelsüblichen Qualität oder Eignung für einen bestimmten Zweck übernommen. Die G+H Systems behält sich weiterhin das Recht vor, diese Dokumentation zu revidieren und ihren Inhalt jederzeit und ohne vorherige Ankündigung zu ändern.

Des Weiteren übernimmt die G+H Systems für Software keinerlei Haftung und schließt insbesondere jegliche ausdrücklichen oder impliziten Gewährleistungsansprüche bezüglich der Marktfähigkeit oder der Eignung für einen bestimmten Zweck aus. Außerdem behält sich die G+H Systems das Recht vor, G+H Software ganz oder teilweise jederzeit inhaltlich zu ändern, ohne dass für die G+H Systems die Verpflichtung entsteht, Personen oder Organisationen von diesen Überarbeitungen oder Änderungen in Kenntnis zu setzen.

Copyright © inchorus ist ein Produkt der G+H Systems GmbH

Ohne ausdrückliche, schriftliche Genehmigung des Herausgebers darf kein Teil dieser Veröffentlichung reproduziert, fotokopiert, übertragen oder in einem Speichersystem verarbeitet werden.