DataFirefly Live Counters — Vollständige Anleitung

DataFirefly Live Counters zeigt in Ihrem PrestaShop-Shop ein Widget mit animierten Zählern an, das teils automatisch aus Ihrer Datenbank gespeist wird (aktive Kunden, versendete Bestellungen, Produkte, belieferte Länder) und teils aus Werten, die Sie eingeben (Bewertungen, Zufriedenheit, Social-Media-Follower…). Das Widget hakt sich nativ in mehrere Display-Hooks (Home, Footer, Warenkorb, Spalten) ein oder lässt sich überall in Ihrem Theme über den Smarty-Tag widget name="dflivecounters" platzieren. Diese Dokumentation behandelt die Installation, die Konfiguration der 17 verfügbaren Zähler, die 5 visuellen Themes, die Cache-Strategie, die Anbindung der Facebook- und Instagram-APIs, den AJAX-Live-Refresh und die Fehlerbehebung.

Installation

1. Laden Sie die Datei dflivecounters.zip aus Ihrem DataFirefly-Konto herunter.
2. PrestaShop-Backoffice → Module → Modul hochladen → senden Sie die ZIP-Datei.
3. Bei der Installation registriert das Modul 7 Display-Hooks und initialisiert etwa ein Dutzend Konfigurationsvariablen. Es wird keine SQL-Tabelle erstellt: alle Einstellungen liegen in ps_configuration.
4. Das Modul lädt seinen Standalone-PSR-4-Autoloader — kein composer install auf dem Server erforderlich.

Widget-Erscheinungsbild

Öffnen Sie Module → DataFirefly Live Counters → Konfigurieren. Der erste Abschnitt bündelt die globalen Erscheinungs-Einstellungen.

Visuelles Theme

Fünf sofort einsetzbare Themes:

• Minimal: maximale Sachlichkeit, weißer Hintergrund, ideal für saubere Themes.
• Glassmorphism: Frostglas mit backdrop-blur, Hintergrund leicht in der Primärfarbe getönt. Sehr trendy.
• Gradient: Vollbreiten-Verlauf von der Primärfarbe zu einem dunkleren Ton. Starke visuelle Wirkung, weißer Text.
• Card: erhabene weiße Karten mit weichem Schatten und Hover. Premium-Klassiker.
• Flat: Hintergrund leicht in der Primärfarbe getönt, Werte in Primärfarbe eingefärbt.

Titel und Untertitel

Über dem Zähler-Grid angezeigt. Leer lassen, um den Header auszublenden (nützlich im Footer, wo der Kontext bereits durch die Umgebung gegeben ist).

Farben

Drei Hauptfarben steuern das gesamte Widget über CSS-Variablen (--dflc-primary, --dflc-text, --dflc-bg):

• Primärfarbe: Standardsymbole, Akzent des Flat-Themes, Verlauf des Gradient-Themes.
• Textfarbe: Titel, Untertitel, Werte und Beschriftungen.
• Hintergrundfarbe: Sektionshintergrund (auf Glassmorphism- und Gradient-Themes ignoriert, die ihren eigenen Hintergrund anwenden).

Spalten

Zwei unabhängige Einstellungen:

• Desktop-Spalten: 1 bis 6 (Standard 4).
• Mobile-Spalten: 1 bis 3 (Standard 2). Breakpoint ist 768 px.

Dauer der CountUp-Animation

Dauer in Millisekunden, während der die Ziffern von 0 auf ihren Zielwert hochzählen (Standard 2.000 ms). Eine Ease-Out-Cubic-Kurve wird für eine sanfte Verzögerung angewendet. Setzen Sie 0, um die Animation zu deaktivieren und den Endwert sofort anzuzeigen.

AJAX-Live-Refresh (optional)

Wenn aktiviert, fragt das Widget periodisch einen JSON-Endpoint ab, um die Werte ohne Seitenneulade zu aktualisieren. Zwei Parameter:

• Live-Refresh: ON/OFF.
• Intervall: in Sekunden, Minimum 30 (Standard 60). Auf 30 erzwungen, wenn Sie weniger eingeben.

Der Endpoint antwortet mit einem Cache-Control: public, max-age=30-Header, sodass Ihr CDN den Traffic absorbieren kann. Die Übergangsanimation von einem Wert zum nächsten startet vom aktuell angezeigten Wert, nicht von null — visuell natürlicher.

„Date from“

Referenzdatum, das von zwei Zählern verwendet wird:

• Versendete Bestellungen: zählt nur Bestellungen, die nach diesem Datum erstellt wurden (Filter WHERE date_add >= ?).
• Jahre an Expertise: berechnet automatisch die Anzahl der Jahre, die von diesem Datum bis heute vergangen sind.

Zählerkatalog

17 Zähler stehen zur Verfügung, aufgeteilt in drei Gruppen je nach Berechnungsmodus.

Automatische Zähler (5)

Diese Zähler lesen Ihre PrestaShop-Daten in Echtzeit. Keine Eingabe erforderlich.

• Kunden: aktive Kunden (active = 1 AND deleted = 0), auf den Shop-Kontext beschränkt. TTL 15 min.
• Versendete Bestellungen: Bestellungen, deren Statushistorie mindestens einen der ausgewählten Status enthält (Feld „Order states counted as shipped“). Wenn kein Status ausgewählt ist, verwendet das Modul automatisch das shipped = 1-Flag aus ps_order_state. TTL 15 min.
• Bearbeitete Bestellungen: alle Bestellungen, deren aktueller Status das logable = 1-Flag hat (PrestaShops kanonisches Flag für Bestellungen, die in den Statistiken zählen). Schließt also Stornierungen und Rückerstattungen aus. TTL 15 min.
• Produkte: aktive, sichtbare Produkte im Katalog, auf den Shop-Kontext beschränkt. TTL 30 min.
• Belieferte Länder: Anzahl der unterschiedlichen Länder, die mindestens eine Bestellung erhalten haben (COUNT(DISTINCT id_country) auf ps_address, verbunden mit ps_orders). TTL 1 h.

Hybrid-Zähler (4)

Diese Zähler versuchen zuerst eine automatische Berechnung, dann greifen sie auf den manuellen Backup-Wert zurück, den Sie eingegeben haben.

• Jahre an Expertise: aus „Date from“ berechnet; manueller Wert, wenn Sie es vorziehen, eine gerundete Zahl festzulegen (z.B. „12″ statt „11″). TTL 24 h.
• Veröffentlichte Artikel: Auto-Erkennung der Haupttabellen der PrestaShop-Blog-Module (smart_blog_post, prestablog_news, psblog_post, ph_simpleblog_post) via INFORMATION_SCHEMA. Bei keinem Treffer wird der manuelle Wert verwendet. TTL 24 h.
• Facebook-Follower: Aufruf der Facebook Graph API mit einem langlebigen Page Access Token. Manueller Fallback, wenn nicht konfiguriert oder die API ausfällt. TTL 1 h.
• Instagram-Follower: Aufruf der Instagram Graph API (Business- oder Creator-Konto erforderlich). Manueller Fallback. TTL 1 h.

Manuelle Zähler (8)

Diese Zähler zeigen einfach den von Ihnen eingegebenen Wert an. Ideal für Metriken, die PrestaShop nicht berechnen kann oder über die Sie die volle Kontrolle haben möchten.

• Kundenbewertungen: Anzahl der Bewertungen (von Trustpilot, Avis Vérifiés, Google usw.).
• Zufriedenheit: Zufriedenheitsrate. Tipp: verwenden Sie ein „%“-Suffix und einen Wert von 0–100.
• Gespartes CO₂: kg an vermiedenen Emissionen. Tipp: „kg“-Suffix.
• Auszeichnungen: Preise, Zertifizierungen, Auszeichnungen.
• Support-Stunden: „h“-Suffix.
• TikTok-Follower: Die TikTok Display API erfordert OAuth pro Benutzer, das für ein öffentliches Widget unpraktikabel ist. Manuelle Eingabe.
• X (Twitter) -Follower: Die X API v2 ist kostenpflichtig. Manuelle Eingabe.
• LinkedIn-Follower: LinkedIn Organization Followers erfordert eine Marketing-Developer-Platform-Partner-Genehmigung. Manuelle Eingabe.

Konfiguration pro Zähler

Jede Zählerzeile im Admin schlägt die gleichen Einstellungen vor:

• Aktiviert (ON/OFF): nur aktivierte Zähler erscheinen im Widget. Die Anzeigereihenfolge folgt der Admin-Reihenfolge.
• Benutzerdefinierte Beschriftung: überschreibt die Standardbeschriftung. Leer lassen, um die native Beschriftung zu verwenden, übersetzt in die Sprache des Besuchers.
• Wert (manuell): für manuelle Zähler und den Fallback der Hybrid-Zähler.
• Offset: ganze Zahl, die zum berechneten Wert addiert wird. Praktisch, um mit einer schmeichelhafteren Zahl zu starten, ohne Ihre Datenbank anzufassen. Für „Kunden“ und „Versendete Bestellungen“ beispielsweise können Sie jeweils +500 und +2.000 hinzufügen, wenn Ihr Shop gerade migriert wurde. Die Beschriftung „Current live“ neben dem Offset-Feld zeigt Ihnen den rohen, von PrestaShop berechneten Wert ohne Offset.
• Präfix / Suffix: 4 bzw. 6 Zeichen. Präfix und Suffix bleiben auch während der Animation fest.
• Dezimalstellen: 0 bis 3. Die Formatierung verwendet Intl.NumberFormat mit dem Locale des Besuchers (lokalisierte Tausendertrennzeichen und Dezimalpunkt).
• Symbolfarbe: überschreibt die Primärfarbe nur für dieses Symbol.

„Versendete“ Bestellstatus

Der Zähler „Versendete Bestellungen“ stützt sich standardmäßig auf die Statushistorie. Die Einstellung Order states counted as shipped lässt Sie genau auswählen, welche Status zählen. In einer Standard-PrestaShop-Installation sind die Status mit den IDs 4 (Versendet) und 5 (Geliefert) vorausgewählt.

Wenn kein Status ausgewählt ist, greift das Modul auf einen Fallback zurück, der das shipped = 1-Flag in ps_order_state abfragt. Dieser Ansatz ist permissiver und erfasst die meisten gängigen Setups.

Facebook konfigurieren

1. Gehen Sie zu developers.facebook.com und erstellen Sie eine App vom Typ „Business“.
2. Wählen Sie im Graph API Explorer Ihre App und dann Ihre Facebook-Seite aus.
3. Generieren Sie ein Page Access Token mit den Scopes pages_read_engagement und pages_show_list.
4. Tauschen Sie dieses kurzlebige Token (1 h) gegen ein langlebiges Token (60 Tage) über den Endpoint /oauth/access_token?grant_type=fb_exchange_token aus.
5. Holen Sie sich Ihre Page ID aus den Einstellungen Ihrer Seite (Sektion „Seitentransparenz“ oder direkt im Graph API Explorer).
6. Füllen Sie die beiden Felder in der Live-Counters-Konfiguration aus und speichern Sie. Der Facebook-Zähler aktualisiert sich beim Speichern.

Instagram konfigurieren

1. Ihr Instagram-Konto muss sich im Business– oder Creator-Modus befinden. Persönliche Konten werden von der Graph API nicht unterstützt.
2. Verknüpfen Sie Ihr Instagram-Konto mit einer Facebook-Seite (Seiteneinstellungen → Instagram).
3. Fragen Sie im Graph API Explorer /me/accounts mit Ihrem Page Access Token ab, um die zugehörige Instagram User ID abzurufen (Feld instagram_business_account).
4. Verwenden Sie das gleiche langlebige Facebook-Token für die Instagram-API.
5. Füllen Sie die IG User ID und das Token in der Live-Counters-Konfiguration aus.

Cache-Strategie

Der Cache arbeitet auf zwei Ebenen, um eine konstante TTFB auch unter Last zu gewährleisten.

Cache pro Zähler

Jeder Zähler hat seine eigene TTL:

• 15 Minuten: Kunden, Versendete Bestellungen, Bearbeitete Bestellungen.
• 30 Minuten: Produkte.
• 1 Stunde: Belieferte Länder, Facebook, Instagram.
• 24 Stunden: Jahre an Expertise, Veröffentlichte Artikel und alle manuellen Zähler.

Der Cache verwendet zuerst die native PrestaShop-Cache-Schicht (memcached, APCu oder Redis, falls auf Ihrem Server konfiguriert), dann einen Filesystem-Fallback in var/cache/dflivecounters/. Dies garantiert, dass die TTLs auch dann respektiert werden, wenn die native Schicht im „No-Cache“-Modus ist.

Cache des gerenderten Widgets

Das komplette Widget-HTML wird selbst für 60 Sekunden pro Sprache und pro Hook gecacht (dflc_widget_LANG_HASH). Diese zweite Schicht absorbiert den Großteil des Traffics, auch wenn die inneren Zähler bereits aktuell sind.

Automatische Purge

• Das Speichern der Konfiguration purged automatisch alle Modul-Caches.
• Eine Cache purgen-Schaltfläche ist im Admin-Panel für manuelle Invalidierung verfügbar.
• Die Deinstallation des Moduls purged den Cache automatisch.

Das Widget in Ihrem Theme platzieren

Das Modul registriert 7 Hooks bei der Installation:

• displayHome — Startseite
• displayFooter — Footer
• displayFooterBefore — direkt vor dem Footer (PS 8+)
• displayLeftColumn / displayRightColumn — Seitenspalten
• displayShoppingCartFooter — Warenkorb-Seite, unter der Zusammenfassung
• actionFrontControllerSetMedia — registriert die CSS/JS-Assets

Sie können Hooks von Design → Positionen im Backoffice hinzufügen oder entfernen.

Freie Platzierung via Smarty

Um das Widget an einer bestimmten Stelle in Ihrem Theme zu platzieren (z.B. auf der Produktseite, unter einem Kategorietitel), verwenden Sie den Smarty-Widget-Tag:

{widget name="dflivecounters"}

Das Widget implementiert PrestaShops native WidgetInterface, was es aus jedem .tpl-Template Ihres Themes aufrufbar macht.

Das Widget-Template anpassen

Das Haupt-Smarty-Template ist views/templates/hook/widget.tpl. Um es zu überschreiben, ohne das Modul zu ändern (um Updates zu erhalten), kopieren Sie es in Ihr Theme, in den Ordner themes/ihr-theme/modules/dflivecounters/views/templates/hook/widget.tpl.

Verfügbare Smarty-Variablen:

• {$dflc.counters} — Array jedes Zählers mit den Schlüsseln key, label, value, icon, prefix, suffix, decimals, icon_color
• {$dflc.theme} — Theme-Slug (minimal, glassmorphism, gradient, card, flat)
• {$dflc.title}, {$dflc.subtitle}
• {$dflc.primary_color}, {$dflc.text_color}, {$dflc.bg_color}
• {$dflc.cols_desktop}, {$dflc.cols_mobile}
• {$dflc.hook} — Name des Ursprungs-Hooks (nützlich, um das Rendering an die Platzierung anzupassen)

AJAX-Endpoint

Der Front-Controller refresh stellt eine JSON-URL zur Verfügung, die vom Live-Refresh oder von jeder Drittanbieter-Integration verwendet werden kann:

index.php?fc=module&module=dflivecounters&controller=refresh

Die JSON-Antwort enthält ein boolesches success, einen Unix-timestamp und ein counters-Objekt, bei dem jeder Schlüssel die Zähler-ID ist (customers, shipped_orders, facebook, instagram usw.) und jeder Wert die aktuelle Zahl. Der Inhalt spiegelt die zum Zeitpunkt des Aufrufs aktivierten Zähler wider, mit angewendeten Offsets. Die Antwort wird mit Cache-Control: public, max-age=30 ausgeliefert.

Barrierefreiheit

Das Widget ist darauf ausgelegt, die WCAG 2.2 AA-Empfehlungen zu erfüllen:

• Semantische Struktur: section, header, ul role="list", li.
• Alle SVG-Symbole haben aria-hidden="true" (dekorativ).
• Strikte Beachtung von prefers-reduced-motion: reduce: Animation deaktiviert, Endwert sofort angezeigt.
• Kontrast: Standardfarben erfüllen ein Verhältnis von über 4,5:1 auf den Minimal- und Card-Themes. Überprüfen Sie Ihre benutzerdefinierten Farben mit einem Tool wie axe DevTools.
• Zahlenformatierung: font-variant-numeric: tabular-nums für eine konstante Ziffernbreite (vermeidet den visuellen „Sprung“ während der Animation).

DSGVO

Das Widget ist so gestaltet, dass kein Consent-Banner erforderlich ist:

• Kein Cookie auf der Besucherseite gesetzt.
• Kein Drittanbieter-Skript geladen (kein Facebook-Pixel, kein Google Tag Manager).
• Facebook- und Instagram-API-Aufrufe erfolgen serverseitig in PHP, nie aus dem Browser. Keine Besucherdaten werden an Meta gesendet.
• Keine personenbezogenen Daten werden vom Modul gesammelt oder gespeichert.

Kompatibilität und technische Hinweise

• PrestaShop 8.0 bis 9.x, PHP 8.1+.
• Natives Multi-Shop: alle SQL-Abfragen sind auf Shop::getContextListShopID() beschränkt.
• Mehrsprachig: Polylang Pro oder natives PrestaShop-Mehrsprachensystem.
• Keine SQL-Tabelle erstellt: Einstellungen in ps_configuration gespeichert.
• Standalone-PSR-4-Autoloader (kein composer install auf dem Server).
• Natives PrestaShop-WidgetInterface: nutzbar via {widget name="dflivecounters"}.
• Asset-Gewicht: 3 KB JS, 2 KB CSS. Keine externen Requests standardmäßig.
• Konform mit den PrestaShop-9-AJAX-Konventionen: $this->module->l() statt $this->l(), dedizierter Front-Controller für den Refresh, überschreibt nie ajaxRender.

FAQ und Fehlerbehebung

Das Widget erscheint nicht auf der Startseite. Prüfen Sie, ob das Modul am Hook displayHome in Design → Positionen eingehängt ist. Prüfen Sie auch, ob mindestens ein Zähler aktiviert ist: ohne aktivierten Zähler gibt das Widget nichts zurück (still).

Der Facebook-Zähler bleibt bei null. Mehrere mögliche Ursachen: falsche Page ID, abgelaufenes Token (60 Tage Lebensdauer), fehlender Scope (pages_read_engagement ist erforderlich). Purgen Sie den Modul-Cache und laden Sie die Konfiguration neu: der von der Graph API zurückgegebene Wert erscheint neben der Beschriftung „Current live“.

Der Zähler Versendete Bestellungen ist zu niedrig. Prüfen Sie die Auswahl „Order states counted as shipped“: nur ausgewählte Status werden gezählt. Wenn Sie benutzerdefinierte Status einbeziehen möchten (z.B. „Click & Collect abgeholt“), fügen Sie diese zur Auswahl hinzu.

Die Zahlen wirken eingefroren und spiegeln meinen echten Traffic nicht wider. Das ist der Cache, der seine Arbeit macht. Die Standard-TTLs reichen von 15 Minuten (Kunden, Bestellungen) bis 24 Stunden (statische Zähler). Verwenden Sie die Cache purgen-Schaltfläche zur manuellen Invalidierung. Für automatische Aktualisierung aktivieren Sie den Live-Refresh-Modus.

Die CountUp-Animation wird nicht ausgelöst. Das Widget verwendet IntersectionObserver und wird ausgelöst, sobald es in den Viewport eintritt. Wenn das Widget beim Seitenladen bereits sichtbar ist (z.B. ganz oben platziert), startet die Animation sofort. Wenn sie bei null bleibt: prüfen Sie die JavaScript-Konsole Ihres Browsers, ein anderes Modul könnte das JS-Bundle brechen.

Das Widget bricht meine Lighthouse / Core Web Vitals. Mit einer Platzierung am Seitenende (Footer) und dem 60-s-Cache auf dem gerenderten HTML ist der CLS / LCP-Einfluss vernachlässigbar. Wenn Sie ein Problem sehen, prüfen Sie, ob Sie den Live-Refresh mit einem zu kurzen Intervall aktiviert haben (das AJAX wird ausgelöst, während Lighthouse misst). Für eine saubere Auditierung deaktivieren Sie den Live-Refresh.

Sind die Zähler im Multi-Shop pro Shop beschränkt? Ja. Alle SQL-Abfragen verwenden Shop::getContextListShopID(). Im „Alle Shops“-Modus summieren sich die Zähler; im „Ein Shop“-Modus zählen sie nur diesen Shop. Benutzerdefinierte Beschriftungen und der manuelle Wert sind ebenfalls pro-Shop-pro-Sprache.

Wie füge ich einen benutzerdefinierten Zähler hinzu? Erstellen Sie eine Klasse, die Df/LiveCounters/Counter/AbstractCounter erweitert (oder ManualCounter für einen 100% manuellen Zähler), implementieren Sie getKey(), getDefaultLabel() und getValue(), fügen Sie dann die Instanz dem Instanzen-Array des CounterRegistry hinzu. Um Ihren Code beim nächsten Update nicht zu verlieren, erstellen Sie ein kleines Begleitmodul, das Ihren Zähler über einen benutzerdefinierten Hook in das Registry injiziert — kontaktieren Sie uns gerne für ein Beispiel.