Die Piwik API

von Roland Rickborn

Problemstellung

In einem Kundenprojekt verwenden wir für Webanalytik (hauptsächlich Downloads und Zugriffszahlen) das Tool Piwik[1]. Es gab folgende zwei Kritikpunkte:

  1. Der Funktionsumfang von Piwik ist beachtlich und für kommerzielle Webseiten optimal geeignet. In unserem Projekt führte die enorme Vielfalt an Funktionen allerdings zur Resignation des Kunden. Ein individuelles Dashboard reichte nicht aus, um die Anforderungen des Kunden hinsichtlich Reporting zu erfüllen.
  2. Auf unsere Applikation kann sowohl direkt per Browser, als auch indirekt per Schnittstelle zugegriffen werden. Zugriffe per Browser werden dabei mittels JavaScript passiv getrackt. Aufrufe per Schnittstelle werden bisher nicht verfolgt, da kein JavaScript ausgeführt wird.

Lösungsvorschlag

Unser Lösungsvorschlag sieht zwei Ansätze vor: 

  1. Automatische Generierung eines standardisierten Berichts in der Applikation
    Die Applikation richtet gezielte Abfragen bezüglich Downloads und Zugriffszahlen an Piwik und erstellt daraus einen standardisierten Bericht in Form einer MS Excel-Datei.
  2. Aktives Tracking von Zugriffen über die Schnittstelle
    Zugriffe auf die Applikation, die über die Schnittstelle erfolgen, die also nicht passiv verfolgt werden können, lösen ein aktives Tracking seitens der Applikation aus. Damit fällt beim Client kein zusätzlicher Programmieraufwand an und trotzdem werden alle Aufrufe analysiert.

Die Idee - Piwik APIs

Zur Umsetzung der Lösungsvorschläge soll die Piwik Analytics API [2] verwendet werden. Sie stellt folgende Programmierschnittstellen zur Verfügung:

API sichern

Eine Beispielabfrage an die Piwik API wäre:

http://demo.piwik.org/?module=API&method=VisitsSummary.getVisits&idSite=1&period=day&date=last10&format=xml

Da kein Token angegeben wird, verwendet Piwik implizit den Benutzer anonymous. Gegenüber der Piwik API authentifiziert man sich deshalb besser per Token. Ein Token wird automatisch beim Anlegen eines Benutzerkontos angelegt. Ein Benutzer erfährt sein Token in dem er sich einloggt und auf seinen Benutzernamen klickt. Im persönlichen Bereich gibt es den Eintrag API mit Links zur Dokumentation und dem Abschnitt Benutzerauthentifizierung.

Dort wird der Token-String angezeigt. Ich rate ausdrücklich davon ab, Piwik Abfragen ohne Token zu verwenden. Am besten den Login per anonymous deaktivieren, auch wegen [6].
Die selbe Abfrage für meinen Benutzer, also mit Token, lautet:

http://demo.piwik.org/?module=API&method=VisitsSummary.getVisits&idSite=1&period=day&date=last10&format=xml&token_auth=000000111111222222333333444444555555

Welche API

Für die Abfragen zur automatischen Erstellung eines Berichts dient die Reporting HTTP API. Sie ist in einzelne Module untergliedert, z. B. API oder Action. Ein Aufruf dieser API sieht wie folgt aus:

http://<URL>/?module=<Modul>&method=<Methode>.<Funktion>&idSite=<ID>&period=<period>&Zeitraum=<Startdatum>[,<Enddatum>]&format=<Format>[&token_auth=<Token>]

Mit den Parametern: 

  • URL = URL der Piwik-Instanz
  • Modul = Name des Moduls, das verwendet werden soll
  • Methode = Name der Methode, die verwendet werden soll
  • Funktion = Name der Funktion, die verwendet werden soll
  • ID = ID der Seite, die analysiert werden soll; falls alle vorhandenen Webseiten untersucht werden sollen, gibt es das Schlüsselwort all
  • Zeitraum = Gibt die Art des Untersuchungszeitraums an; mögliche Werte sind dayweekmonthyear oder range
  • Startdatum = Enthält das Startdatum der Untersuchung, standardmäßig im Vormat YYYY-MM-DD; besondere Schlüsselwörter sind today or yesterday, wobei die Zeitzone des Servers beachtet wird
  • Enddatum = Gibt das optionale Enddatum der Untersuchung an; Schlüsselbegriffe sind lastX und previousX, also die letzten X Zeiteinheiten inklusive der aktuellen Zeiteinheit oder ohne aktuelle Zeiteinheit
  • Format = Gibt an, in welchem Format die Antwort von Piwik erscheinen soll; mögliche Werte sind xmlcsvjsontsvhtmlphprss oder original
  • Token = Gibt das Token des Benutzers an.

Außerdem gibt es weitere optionale Parameter, z. B. languageflat oder filter_pattern, mit deren Hilfe sich das Ergebnis der Abfrage beeinflussen lässt hinsichtlich der Darstellung oder des Inhalts.
Es gibt zwei Besonderheiten: 

  1. Manche Parameter können einzeln oder als Feld übergeben werden
    Parameter, die in der Dokumentation in der Mehrzahl angegeben wurden, beispielsweise urls, können als Feld angegeben werden. Ein Aufruf wäre dann ...&urls[0]=ersteUrl&urls[1]=zweiteUrl...
  2. Abfragen bündeln mittels Bulk API Request
    Anstatt viele einzelne API Anfragen an Piwik zu stellen, lassen sich die Abfragen zu einer einzigen Abfrage bündeln. Achtung, die gebündelten Abfragen müssen in diesem Fall URL encoded sein!

Beispiel für API.getBulkRequest

Diese beiden Abfragen sollen zu einer Bulk-Abfrage kombiniert werden:

http://demo.piwik.org/?module=API&method=VisitsSummary.getVisits&idSite=1&period=day&date=last10&format=xml&token_auth=000000111111222222333333444444555555
http://demo.piwik.org/?module=API&method=CustomVariables.getCustomVariables&idSite=1&period=day&date=last10&format=xml&token_auth=000000111111222222333333444444555555

Hier ist die URL-kodierte Bulk-Abfrage:

http://demo.piwik.org/?module=API&method=API.getBulkRequest&format=json&urls[0]=method%3dVisitsSummary.getVisits%26idSite%3d1%26period%3dday%26date%3dlast10&urls[1]=method%3dCustomVariables.getCustomVariables%26idSite%3d1%26period%3dday%26date%3dlast10&token_auth=000000111111222222333333444444555555

Die Parameter format und token_auth müssen nur für die Bulk-Abfrage angegeben werden, aber nicht für die gebündelten Abfragen. Bei Bulk-Abfrage sind nur die Rückgabeformate xml und json zulässig.

Die Tracking HTTP API wird für die Erweiterung der Schnittstelle verwendet. Jeder Aufruf über die Schnittstelle wird damit aktiv an Piwik berichtet.
Ein Aufruf dieser API sieht wie folgt aus:

http://<URL>/piwik.php?_cvar={"<Index>":["<Name>","<Wert>","<Bereich>"]}&action_name=<AktionName>&url=<Webseite>&idsite=<ID>&rand=<Zufall>&rec=1&send_image=0

Mit den Parametern: 

  • URL = URL der Piwik-Instanz
  • Index = Index der benutzerdefinierten Variablen
  • Name = Name der benutzerdefinierten Variablen
  • Wert = Wert der benutzerdefinierten Variablen
  • Bereich = Bereich der benutzerdefinierten Variablen; mögliche Angaben sind visit und page
  • AktionName = Name der Aktion
  • Webseite = Vollständige URL für die Aktion
  • ID = ID der Webseite in Piwik
  • Zufall = Ein zuvälliger Wert, der das Caching der Abfrage im Broser oder in einem Proxy verhindern soll

Daneben gibt es noch eine umfangreiche Liste von weiteren Parametern, die teilweise zwingend erforderlich sind, z. B. &rec=1, oder die optional angegeben werden können, z. B. &send_image=0. Anfragen an die Tracking HTTP API benötigen in der Regel kein Token, außer es sollen grundlegende Angaben überschrieben werden, z. B. Absender IP oder Abfragezeitpunkt.

Tipp zum Testen

Für schnelle Tests im Browser bietet sich der RESTClient [7] an. Mit dem gleichnamigen AddOn für Firefox, Chrome oder Safari lässt sich eine Abfrage an die Piwik API einfach im Browser absetzen.

Fazit

Die Piwik API bietet eine einfache Möglichkeit, auf den kompletten Funktionsumfang von Piwik zuzugreifen, ohne den Anwender mit der schieren Vielfalt des Tools zu erschlagen. Mit der Reporting API lassen sich umfangreiche und detaillierte Berichte automatisiert erstellen. Und mit der Tracking API können auch Zugriffe analysiert werden, die nicht ausschließlich auf reinen Browserzugriffen auf Webseiten beruhen.

Kategorien: Apache TomcatJavaScript

Zurück