Verkaufszähler Shopware 6: Installations- und Konfigurationsanleitung

Diese Anleitung behandelt Installation, Konfiguration und Anpassung des Plugins DfSalesCounter, das auf jeder Produktseite anzeigt, wie oft ein Produkt bereits verkauft wurde, basierend auf den echten Bestellungen Ihres Shopware 6 Shops.

Voraussetzungen

• Shopware 6.5.x, 6.6.x oder 6.7.x als selbst gehostete Installation. Shopware Cloud (SaaS) akzeptiert keine Server-Plugins.
• PHP 8.1 oder höher.
• Ein Storefront-Theme, das vom Shopware Storefront-Theme abgeleitet ist, oder ein individuelles Theme, das die Standard-Twig-Blöcke der Kaufbox beibehält.
• Kommandozeilenzugriff wird für die Theme-Kompilierung empfohlen, die Installation über die Administration funktioniert aber ebenfalls.

Installation

ZIP-Upload über die Administration

1. Öffnen Sie in der Shopware Administration Erweiterungen und dann Meine Erweiterungen.
2. Klicken Sie auf Erweiterung hochladen und wählen Sie die Datei DfSalesCounter-1.0.0.zip.
3. Sobald das Plugin gelistet ist, klicken Sie auf Installieren und aktivieren es über den Schalter.
4. Kompilieren Sie das Theme neu über Inhalte, Themes, indem Sie Ihr Theme auswählen und dann Theme neu kompilieren klicken. Dieser Schritt ist nur einmal nötig, da das Plugin ein Storefront-Stylesheet mitliefert.

Über die Kommandozeile

Legen Sie den Ordner DfSalesCounter in custom/plugins/ Ihrer Installation ab und führen Sie aus:

bin/console plugin:refresh
bin/console plugin:install --activate DfSalesCounter
bin/console theme:compile
bin/console cache:clear

In einer Umgebung mit Deployment-Pipeline gehört die Theme-Kompilierung in der Regel bereits zu den Standardschritten.

Konfiguration

Die Konfigurationsseite finden Sie unter Erweiterungen, Meine Erweiterungen, Schaltfläche … rechts neben DataFirefly Sales Counter, dann Konfigurieren. Über die Auswahl am Seitenkopf legen Sie fest, für welchen Verkaufskanal die Konfiguration gilt: jeder Kanal kann eine eigene Schwelle, einen eigenen Text und eine eigene Position haben.

Reiter Allgemein

• Verkaufszähler aktivieren: Hauptschalter. Deaktiviert wird keine Abfrage ausgeführt und kein Badge gerendert.
• Zählmodus: Verkaufte Menge addiert alle bestellten Mengen des Produkts. Anzahl Bestellungen zählt die unterschiedlichen Bestellungen, die das Produkt enthalten haben. Der erste Modus betont das Volumen, der zweite die Anzahl verschiedener überzeugter Kunden.
• Berücksichtigte Bestellungen: Alle Bestellungen liefert die Rohzahl. Stornierte Bestellungen ausschliessen entfernt jene im Status cancelled. Nur bezahlte Bestellungen behält ausschliesslich Bestellungen mit einer Transaktion im Status paid oder paid_partially.
• Mindestschwelle für die Anzeige: unterhalb dieses Werts erscheint kein Badge. Der Standardwert ist 5. Eine Schwelle von 0 wird wie 1 behandelt, bei einem Produkt ohne Verkäufe wird nie ein Badge gerendert.
• Zeitraum in Tagen: begrenzt die Zählung auf die letzten X Tage anhand des Bestelldatums. Der Wert 0 bedeutet einen Gesamtwert seit Beginn.
• Verkäufe aller Varianten zusammenfassen: addiert die Verkäufe des Hauptprodukts und aller Varianten. Empfohlen bei Mode- oder Grössenkatalogen, zu deaktivieren, wenn jede Variante einem eigenen Einsatzzweck entspricht.
• Nur Bestellungen des aktuellen Verkaufskanals zählen: verhindert, dass ein B2B-Shop oder ein Exportkanal die im Endkundenshop angezeigten Zahlen aufbläht.

Reiter Darstellung

• Position auf der Produktseite: Unter dem Produktnamen, Unter dem Preis oder Unter der Kaufbox, also am Ende der Box unterhalb des Warenkorb-Buttons.
• Darstellungsstil: Badge rendert eine umrandete Pille, Einfacher Text rendert eine Zeile ohne Rahmen, Banner rendert einen Block über die volle Breite mit farbiger Seitenleiste.
• Symbol: Flamme, Warenkorb, Haken oder keines. Die Symbole sind Inline-SVG, es wird keine Icon-Schriftart geladen.
• Akzentfarbe: leer gelassen wird die Primärfarbe des Themes verwendet. Ausgefüllt speist sie die CSS-Variable --df-sales-counter-accent am Badge-Element.
• Tausendertrennzeichen: schmales Leerzeichen, Komma, Punkt oder keines. Nützlich, sobald die Zähler vierstellig werden.
• Eigener Text: siehe folgender Abschnitt.
• Cache-Lebensdauer in Sekunden: standardmässig 900. Der Wert 0 deaktiviert den Cache und fragt die Datenbank bei jedem Seitenaufruf ab.

Den Text anpassen

Globaler Text aus der Konfiguration

Das Feld Eigener Text akzeptiert einen Satz mit dem Platzhalter %count% an der Stelle, an der die Zahl erscheinen soll. Beispiel: Dieses Modell ging in diesem Monat %count% mal raus. Dieser Text gilt für alle Sprachen des Verkaufskanals. Er wird vor der Ausgabe bereinigt, was einfache Auszeichnung wie <strong> erlaubt, aber jedes Skript blockiert.

Texte je Sprache über Textbausteine

Lassen Sie das Feld Eigener Text leer, um den Text sprachweise zu steuern. Öffnen Sie Einstellungen, Shop, Textbausteine und suchen Sie nach dfSalesCounter. Vier Schlüssel stehen zur Verfügung:

• dfSalesCounter.badge.quantitySingular und dfSalesCounter.badge.quantityPlural, verwendet im Modus verkaufte Menge.
• dfSalesCounter.badge.ordersSingular und dfSalesCounter.badge.ordersPlural, verwendet im Modus Anzahl Bestellungen.

Jeder Wert akzeptiert den Platzhalter %count%. Die deutschen, englischen, französischen, spanischen und italienischen Übersetzungen werden mit dem Plugin ausgeliefert. Ein im Textbaustein-Manager geänderter Wert hat Vorrang vor dem des Plugins, auch nach einem Update.

Wie die Zahl berechnet wird

Das Plugin liest Bestellpositionen vom Typ Produkt, verknüpft mit der Bestellung und ihrem Status. Die Berechnung erfolgt in einer einzigen aggregierten Abfrage, ohne Hintergrundprozess und ohne eigene Tabelle.

• Im Mengenmodus summiert die Abfrage die Mengenspalte der Bestellpositionen.
• Im Bestellmodus zählt sie unterschiedliche Bestell-Identifikatoren.
• Nur die Live-Version der Bestellungen wird berücksichtigt, Arbeitsversionen aus einer Gutschrift oder einer Bestellbearbeitung werden ignoriert.
• Bei aktivierter Variantenzusammenfassung löst das Plugin zunächst die Produktfamilie des angezeigten Produkts auf, Hauptprodukt und Varianten, und filtert dann über die gesamte Menge der Identifikatoren.

Liegt das Ergebnis unter der konfigurierten Schwelle, wird dem Produkt keine Erweiterung hinzugefügt und das Template gibt nichts aus. Das Badge existiert also gar nicht im HTML, wodurch jede Restanzeige über eine CSS-Regel des Themes ausgeschlossen ist.

Cache und Aktualität der Zahl

Das Ergebnis wird im Anwendungs-Cache-Pool von Symfony abgelegt, unter einem Schlüssel aus Produkt-Identifikator, Verkaufskanal und einer Signatur der Optionen, die die Berechnung beeinflussen. Eine Änderung von Zählmodus, Bestellumfang, Zeitraum oder Zusammenfassungsoptionen ändert diese Signatur und macht frühere Werte damit automatisch ungültig.

Bei jeder eingehenden Bestellung leert das Plugin den Cache der in dieser Bestellung enthaltenen Produkte sowie den ihres Hauptprodukts. Der Zähler bildet den Verkauf also ab, ohne das Ablaufen der konfigurierten Laufzeit abzuwarten.

Bei einem überschaubaren Katalog kann die Cache-Laufzeit ohne spürbare Folgen auf 0 gesetzt werden: die Abfrage greift auf indizierte Spalten zu. Bei einem grossen Katalog mit hohem Traffic behalten Sie eine Laufzeit von mehreren Minuten bei.

Erweiterte Anpassung der Ausgabe

Das Plugin überschreibt die Kaufbox der Produktseite und fügt sein Badge je nach gewählter Position in drei Standard-Twig-Blöcke ein: den Block des Produktnamens, den Block des Preiscontainers und den Block des Kaufcontainers. Das Badge selbst wird von einem eigenen Komponenten-Template gerendert, storefront/component/df-sales-counter/badge.html.twig, das zwei überschreibbare Blöcke bereitstellt, einen für das Symbol und einen für den Text.

Aus einem Theme oder Plugin heraus ist die Erweiterung in Twig am Produkt der Seite unter dem Namen dfSalesCounter erreichbar. Sie stellt die Rohzahl, die formatierte Zahl, die Position, den Stil, das Symbol, die Akzentfarbe, den eigenen Text und den Zählmodus bereit. So können Sie den Zähler auch ausserhalb der Kaufbox ausgeben, etwa in einem Produktinformationsreiter, indem Sie die Erweiterung abrufen und die Komponente einbinden.

Die Styles sind in Resources/app/storefront/src/scss/base.scss rund um die Klassen df-sales-counter, df-sales-counter__icon und df-sales-counter__text definiert, mit einem Modifikator je Darstellungsstil. Jede Regel Ihres Themes, die nach der des Plugins kompiliert wird, hat Vorrang, ohne dass das Plugin geändert werden muss.

Fehlerbehebung

Es erscheint kein Badge

Prüfen Sie der Reihe nach: das Plugin ist aktiviert, der Aktivierungsschalter steht für den richtigen Verkaufskanal auf ja, das Produkt hat die konfigurierte Schwelle erreicht, und der gewählte Bestellumfang schliesst nicht sämtliche Bestellungen aus. Eine Schwelle von 5 mit dem Umfang Nur bezahlte Bestellungen in einem Testshop, dessen Bestellungen nie als bezahlt markiert werden, führt nie zu einer Anzeige.

Das Badge erscheint ohne Styling

Das Theme wurde nach der Aktivierung nicht neu kompiliert. Führen Sie bin/console theme:compile aus oder nutzen Sie die Schaltfläche zum Neukompilieren in der Administration.

Die Zahl wirkt eingefroren

Die Cache-Laufzeit ist noch nicht abgelaufen. Leeren Sie den Anwendungs-Cache mit bin/console cache:pool:clear cache.app, oder setzen Sie die Laufzeit vorübergehend auf 0, um die Berechnung zu prüfen.

Das Badge sitzt an der falschen Stelle

Ein stark angepasstes Theme kann die Twig-Blöcke der Kaufbox entfernt oder umbenannt haben. Probieren Sie eine andere Position in der Konfiguration, oder binden Sie die Komponente manuell in Ihrem Template ein, indem Sie die Produkterweiterung abrufen.

Update und Deinstallation

Ein Update erfolgt durch Hochladen des neuen ZIP und Klick auf Aktualisieren, gefolgt von einer Theme-Neukompilierung, wenn die Version Style-Änderungen enthält. Die Konfiguration bleibt erhalten.

Bei der Deinstallation bietet ein Kontrollkästchen an, die Benutzerdaten zu behalten. Ohne Haken werden sämtliche Konfigurationsschlüssel des Plugins entfernt. Das Plugin legt keine Tabelle an und führt keine Migration aus, die Deinstallation hinterlässt also nichts in der Datenbank ausser seiner Konfiguration.

Referenz der Konfigurationsschlüssel

Alle Schlüssel tragen das Präfix DfSalesCounter.config. und lassen sich über die Admin API oder den Befehl system:config:set setzen:

• active, boolesch
• countMode, Werte quantity oder orders
• orderScope, Werte all, notCancelled oder paid
• minThreshold, ganze Zahl
• periodDays, ganze Zahl
• aggregateVariants, boolesch
• scopeToSalesChannel, boolesch
• position, Werte afterName, afterPrice oder afterBuy
• style, Werte badge, inline oder banner
• icon, Werte none, flame, cart oder check
• accentColor, hexadezimale Zeichenkette
• thousandSeparator, Werte space, comma, dot oder none
• customText, Zeichenkette
• cacheTtl, ganze Zahl in Sekunden