Phoca Download in MW SiteStats erfassen: meine Lösung für Download-Klicks

Ich wollte in MW SiteStats mit einem Blick sehen, welche Dateien aus meinem Phoca-Downloadbereich angeklickt werden. Obwohl das Ereignis-Tracking eingeschaltet war, erschienen zunächst keine Download-Ereignisse. Bei einem Test stieg stattdessen die Zahl der Formularaktionen.

Mit einer Anpassung an der Darstellung der Download-Buttons in Phoca Download und an der JavaScript-Datei von MW SiteStats werden die Download-Klicks jetzt mit dem jeweiligen Dateititel angezeigt.

Warum die Einstellung allein nicht ausreichte

Die von mir geprüfte SiteStats-Datei erkennt normale Download-Links anhand ihrer Dateiendung. Ein Link auf eine Datei mit der Endung .zip oder .png kann so als Download erfasst werden, wenn diese Endung in den Einstellungen hinterlegt ist.

Bei Phoca Download steht die eigentliche Dateiendung jedoch nicht unbedingt im Download-Link. Ein abgesendetes Formular kann zusätzlich als Formularaktion erscheinen. Nur weitere Dateiendungen einzutragen reichte für meinen Ablauf deshalb nicht aus.

So funktioniert die Anpassung

Die Phoca-Vorlage umschließt ausschließlich den Download-Button mit einer Kennzeichnung namens data-mt-phoca-download. Darin steht der Dateititel. Die angepasste tracker.js erkennt einen Klick auf diesen markierten Button und sendet ein Ereignis vom Typ download.

Die Lösung nutzt den vorhandenen Ereignisversand von MW SiteStats. Ein zusätzlicher Aufruf wie mw_stats.trackEvent() wird nicht verwendet: Diese Funktion existiert in meiner geprüften Tracker-Datei nicht.

1. Die richtige Phoca-Vorlage finden

Entscheidend ist die Vorlage, die die Download-Buttons tatsächlich ausgibt. Bei mir enthält sie unter anderem die Variablen $pdButtonDownload und $v->title sowie den Bereich pd-card-actions.

Template-Overrides liegen bei Joomla typischerweise unter templates/DEIN-TEMPLATE/html/com_phocadownload/. Der genaue Unterordner und Dateiname hängen von der verwendeten Ansicht ab. Nicht irgendeine Datei namens default.php ersetzen.

In meiner Kartenvorlage stand diese Ausgabezeile:

echo '<div class="pd-card-actions">' . $pdButtonPreview . $pdButtonDetails . $pdButtonDownload . $pdButtonPlay . '</div>';

Nur diese Ausgabezeile wird durch den folgenden Abschnitt ersetzt. Die davorstehenden Ausgaben für Video, Bewertung und Schlagwörter bleiben bestehen. Ebenso bleiben die nachfolgenden Bereiche erhalten.

// Mark only the download control, without changing existing handlers.
$pdTrackedDownload = '';
if ($pdButtonDownload !== '') {
    $pdTrackedDownload = '<span data-mt-phoca-download="'
        . htmlspecialchars((string) $v->title, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')
        . '">' . $pdButtonDownload . '</span>';
}
echo '<div class="pd-card-actions">' . $pdButtonPreview . $pdButtonDetails . $pdTrackedDownload . $pdButtonPlay . '</div>';

Die Verwendung von htmlspecialchars() sorgt dafür, dass beispielsweise Anführungszeichen oder ein kaufmännisches Und im Dateititel das HTML-Attribut nicht beschädigen. Vorhandene Klick-Funktionen des Download-Buttons werden dabei nicht ersetzt.

2. Die tracker.js ergänzen

Bei meiner Installation liegt die Datei auf dem Server hier:

media/plg_system_sitestats/js/tracker.js

Innerhalb des Abschnitts für das Ereignis-Tracking befindet sich dieser Beginn des Klick-Handlers:

document.addEventListener('click', function (e) {

Direkt hinter dieser Zeile wird die Prüfung der Phoca-Kennzeichnung eingefügt. Die bereits vorhandenen Zeilen zur Suche nach dem angeklickten Link bleiben danach stehen. Der Anfang des Handlers sieht anschließend so aus:

document.addEventListener('click', function (e) {
    // Explicit Phoca card download marker; retain existing button behaviour.
    var target = e.target && e.target.closest ? e.target : null;
    var control = target ? target.closest('a[href], button, input[type="submit"], input[type="button"]') : null;
    var marker = control ? control.closest('[data-mt-phoca-download]') : null;
    if (marker) {
        if (opts.clicks && !control.disabled && control.getAttribute('aria-disabled') !== 'true') {
            fire('download', marker.getAttribute('data-mt-phoca-download'), control.getAttribute('href') || '');
        }
        return;
    }

    var a = e.target && e.target.closest ? e.target.closest('a[href], ' + (opts.selector || 'a[data-ssp]')) : null;
    if (!a) { return; }

Danach folgt unverändert der vorhandene Abschnitt // Eigener Selektor (Buttons o. Ä.). und der restliche Klick-Handler. Den Handler nicht ein zweites Mal anlegen und nicht die komplette Datei durch den oben gezeigten Ausschnitt ersetzen.

Die neue Prüfung steht bewusst vor der allgemeinen Link-Erkennung. Sie berücksichtigt den bestehenden Klick-Schalter und überspringt deaktivierte Schaltflächen. Der vorhandene Opt-out-Ablauf bleibt erhalten. Die Shop-Funktionen im übrigen Skript werden nicht verändert.

3. Einstellungen und Funktion prüfen

1. In MW SiteStats Ereignis-Tracking und Klicks (Tel/E-Mail/Download) einschalten.
2. Beide geänderten Dateien an ihren jeweiligen Platz hochladen.
3. Den betreffenden Joomla-, Browser- und gegebenenfalls Optimierungs-Cache leeren. Die Downloadseite anschließend neu laden.
4. Einen Testdownload als angemeldetes Mitglied starten und die Statistik aktualisieren.
5. Den Ablauf zusätzlich als Gast prüfen. Ein privates Browserfenster hilft, alte zwischengespeicherte Dateien auszuschließen.

Wenn nichts erscheint, auch die bisherigen Ausschlüsse, Opt-out und Do-Not-Track-Einstellungen berücksichtigen. Je nach Konfiguration werden eigene Testaufrufe nicht erfasst.

Was erscheint anschließend in der Statistik?

Unter „Ereignisse (Aktionen)“ erscheint der Typ „Download“. Unter „Top-Ereignisse (Details)“ werden die Dateititel und die Anzahl der erfassten Klicks angezeigt, zum Beispiel:

• Download: Vikings Rise Avatar2 – 1
• Download: Vikings Rise Avatar19 – 1

Es entsteht kein eigener Menüpunkt und kein zusätzlicher Statistikbereich. Die vorhandene Ereignisanzeige wird genutzt. Frühere Einträge werden nicht rückwirkend geändert. Dateien mit identischem Titel können in der Ereignisanzeige zusammengefasst werden.

Nach Updates erneut prüfen

Ein Update von MW SiteStats kann die angepasste tracker.js überschreiben. Deshalb die Änderung dokumentieren und nach Updates prüfen, ob die Erfassung noch funktioniert.

Eine alte angepasste tracker.js nicht ungeprüft über eine neue Version kopieren. Stattdessen die Ergänzung mit der neuen Datei vergleichen und bei Bedarf erneut einarbeiten. Auch ein Phoca-Template-Override sollte nach Änderungen an der Erweiterung auf Kompatibilität geprüft werden.

Mein Ergebnis

Auf meiner Website sehe ich jetzt direkt in MW SiteStats, welche Avatar-Downloads angeklickt wurden. Für die Downloadverwaltung und die dort verfügbaren Downloadprotokolle nutze ich weiterhin Phoca Download. Beide Übersichten ergänzen sich für meinen Zweck.