Plugware Bonuspunkte

Ein Bonuspunkte-Programm für Shopware 6.7. Angemeldete Kunden sammeln mit jeder Bestellung Punkte, steigen in Treuestufen auf und lösen ihr Guthaben im Warenkorb als Rabatt ein oder wandeln es in einen Gutschein um. Verwaltet wird alles im Adminbereich; Bezeichnungen, Grafik und Treuestufen sind frei wählbar. Ohne Node/npm-Build.

Inhalt

1. Was das Plugin macht 2. Installation 3. So funktioniert es 4. Der Block für die Erlebniswelt 5. Teilnahme am Programm 6. Was Kunden sehen 7. Der Adminbereich 8. Einstellungen 9. Konfiguration 10. Konsolenbefehle 11. Der gespeicherte Verlauf 12. Datenmodell 13. Schutz vor Manipulation 14. Für Entwickler 15. Werkzeuge im Quellverzeichnis

Was das Plugin macht

Kunden sammeln Punkte je Euro Bestellwert. Mit der Zeit steigen sie in Treuestufen auf, die den Punktefaktor erhöhen. Das Guthaben lässt sich im Warenkorb direkt als Rabatt einsetzen oder — wenn freigeschaltet — in einen Gutscheincode umwandeln.

Gastbestellungen nehmen nicht teil: Gäste sind in Shopware zwar echte Kundendatensätze, können sich aber nicht anmelden und kämen an ein Guthaben nie wieder heran.

Alles, was Kunden zu sehen bekommen, ist benennbar. Aus "Bonuspunkte" kann "Treuepunkte", "Chips" oder ein eigener Name werden, ebenso aus den fünf Treuestufen. Sämtliche Werte lassen sich je Verkaufskanal unterschiedlich setzen.

Das Plugin kommt ohne Node- und npm-Build aus: Die Storefront läuft über Twig-Vorlagen, der Adminbereich über eine handgeschriebene JavaScript-Datei. Nach dem Einspielen genügen assets:install und ein Leeren des Caches.

Installation

bin/console plugin:refresh bin/console plugin:install --activate PlugwareLoyalty bin/console assets:install bin/console cache:clear

Danach im Adminbereich hart neu laden (Strg+F5). Ohne assets:install fehlen die Oberfläche des Plugins und die mitgelieferte Münze.

Umstieg von der Vorgängerfassung

Bis Version 3.8.0 lief das Plugin unter einem anderen Namen. Für Shopware ist die umbenannte Fassung ein anderes Plugin, deshalb ist ein Umstieg nötig: das alte Plugin zuerst deaktivieren und dann mit --keep-user-data deinstallieren.

bin/console plugin:deactivate <alter Plugin-Name> bin/console plugin:uninstall --keep-user-data <alter Plugin-Name>

--keep-user-data ist entscheidend — ohne diesen Schalter löscht das alte Plugin Guthaben, Buchungen und Einstellungen. Anschließend den alten Ordner aus custom/plugins entfernen und die neue Fassung wie oben installieren. Beim Installieren holt sich das Plugin Konten, Buchungen, Kennzahlen und alle Einstellungen aus den alten Tabellen; die alten Tabellen bleiben als Sicherung stehen. Gutscheine aus der alten Fassung werden weiterhin als eigene erkannt.

So funktioniert es

Die grauen Kästen sind Einstellungen aus dem Adminbereich, die in die Rechnung eingehen. Die violette Spur ist der Weg der Punkte, der grüne Kasten das, was der Kunde davon hat. Nicht abgebildet sind die Spiele und das nachträgliche Verbuchen alter Bestellungen — beide münden an derselben Stelle ins Punktekonto.

Sammeln

Sobald eine Bestellung eingeht, wird der Bestellwert mit den Punkten je Euro und dem Faktor der aktuellen Treuestufe multipliziert und auf ganze Punkte abgerundet. Wann die Gutschrift erfolgt, ist einstellbar: sofort bei der Bestellung, bei Zahlungseingang oder erst, wenn die Bestellung im Adminbereich als abgeschlossen geführt wird. Der letzte Weg ist der sicherste und zugleich der späteste — der Kunde wartet dann bis nach der Lieferung auf seine Punkte.

Grundlage ist in der Vorgabe der Bestellbetrag nach Abzug eingelöster Punkte und Punkte-Gutscheine, also der tatsächlich gezahlte Betrag. So lassen sich Punkte nicht durch wiederholtes Einlösen vermehren. Wer möchte, dass Kunden auf den vollen Warenwert sammeln, schaltet "Punkte-Rabatte mindern die Gutschrift" ab; fremde Rabatt-Aktionen bleiben in beiden Fällen abgezogen.

Die Versandkosten zählen nicht mit. Gesammelt wird auf den Warenwert, sonst brächte allein die Wahl einer teureren Versandart mehr Punkte ein. Wer es anders möchte, setzt den Haken bei "Versandkosten bringen Punkte"; dann gilt der gesamte Bestellbetrag einschließlich Versand. Versandprämien bleiben in der Vorgabe konsequenterweise ebenfalls außen vor, da ihr Rabatt einem Betrag gilt, der gar nicht in die Rechnung eingeht.

Wer sammeln darf, ist auf zwei Arten steuerbar:

• Ganz abschalten über "Punkte sammeln möglich". Für neue Bestellungen gibt es dann keine Gutschrift mehr, vorhandenes Guthaben bleibt bestehen und einlösbar. Das ist der Weg, ein Programm auslaufen zu lassen, statt Kunden ihr Guthaben zu entziehen.
• Auf Kundengruppen begrenzen. Ohne Auswahl sammeln alle. Wird mindestens eine Gruppe gewählt, erhalten nur deren Kunden Punkte; maßgeblich ist die Gruppe zum Zeitpunkt der Buchung.

In beiden Fällen bleibt das Einlösen für alle möglich, damit niemand nach einer Umstellung auf seinem Guthaben sitzen bleibt. Im Kundenkonto erscheint ein Hinweis, und der Abstand zur nächsten Treuestufe wird ausgeblendet, weil er nicht mehr erreichbar wäre.

Memory

Das Memory erscheint wie die anderen beiden als Fenster über der Seite, nach einer einstellbaren Wartezeit ab dem ersten Seitenaufruf des Besuchs.

Verdeckt tragen die Karten die Münze — dasselbe Bild wie im Kundenkonto, also das unter Bild für die Punkte eingestellte oder die mitgelieferte. Sie liegt mittig auf der eingestellten Kartenfarbe und lässt ringsum Luft, damit der Rahmen sichtbar bleibt.

Aufgedeckt zeigen die Karten die Titelbilder Ihrer Artikel.

Sitzt ein Paar, nennt die Zeile unter dem Feld den Stand — „Paar gefunden! 3 von 6“ — und pocht dabei kurz zweimal. Das letzte Paar löst stattdessen die Gewinnmeldung aus, damit nicht beides übereinander steht.

Die Vorschau im Adminbereich spielt genauso: zwei Karten aufdecken, bei Gleichheit bleiben sie liegen, und dieselben Meldungen erscheinen. Am Ende nennt sie, wie viele Punkte es im Shop dafür gäbe. Gebucht wird dabei nichts. Es ist nichts zu pflegen: Das Spiel holt sie bei jedem Durchgang neu aus dem Sortiment, es sind also nicht immer dieselben. Wie viele Paare zu finden sind, legt Wie viele Artikelbild-Paare müssen gefunden werden fest, zwei bis zwölf. Jedes Paar zeigt ein Artikelbild, es liegen also doppelt so viele Karten auf dem Feld.

Die Spielzeit begrenzt eine Partie, 0 bis 600 Sekunden bei Vorgabe 0 — ohne Zeitdruck. Ist eine Zeit gesetzt, läuft im Fenster eine Uhr; in den letzten fünfzehn Sekunden wird sie rot. Bei null gibt es keine Gutschrift, und der Versuch ist verbraucht; im nächsten Zeitraum steht ein neuer offen.

Die Zeit beginnt erst mit der ersten aufgedeckten Karte, nicht schon beim Öffnen des Fensters: Wer das Feld nur ansieht, verliert nichts. Bis dahin steht die volle Zeit da.

Wenn die Zeit abgelaufen ist legt fest, was dann geschieht: Das Fenster schließt sich sofort, oder es bleibt stehen und das Feld ist gesperrt — der Kunde sieht dann, wie weit er gekommen ist, und schließt selbst. Die Uhr steht in diesem Fall auf 0:00; eine zusätzliche Meldung gibt es nicht. Die Vorschau im Adminbereich verhält sich in beiden Fällen wie der Shop.

Karten ohne Partner legt zusätzliche Karten aufs Feld, zu denen es kein Gegenstück gibt — null bis zwölf, Vorgabe null. Sie machen das Spiel schwerer, ohne dass mehr zu finden wäre: Gewonnen hat, wer alle Paare gefunden hat; die Einzelgänger bleiben verdeckt liegen. Bei sechs Paaren und drei Einzelgängern liegen also fünfzehn Karten auf dem Feld statt zwölf.

Aus wie vielen Artikeln auswählen bestimmt den Vorrat, aus dem gezogen wird, 10 bis 500 bei Vorgabe 60. Aus wie vielen Stellen des Sortiments lesen bestimmt, wie weit die Karten eines Spiels auseinanderliegen — eins bis zehn, Vorgabe drei. Gelesen wird an so vielen verstreuten Stellen und in wechselnder Reihenfolge. Aus einem einzigen Ausschnitt stünden sonst lauter Artikel auf den Karten, die im Sortiment nebeneinander liegen — dieselbe Kategorie, am selben Tag angelegt. Ein größerer Vorrat mischt zusätzlich, kostet aber etwas mehr Zeit beim Laden. Jede zusätzliche Stelle kostet eine weitere Abfrage; bei einem kleinen Sortiment, das der Vorrat ohnehin abdeckt, bleibt es bei einer.

Berücksichtigt wird nur, was der Kunde ohnehin sehen darf: aktive Artikel des Verkaufskanals mit Titelbild. Varianten bleiben außen vor, sonst zeigten mehrere Karten dasselbe Foto in anderer Farbe und das Paar wäre nicht mehr zu erkennen. Findet sich zu wenig — etwa in einem frisch aufgesetzten Shop —, greifen die mitgelieferten Motive, damit das Spiel spielbar bleibt.

Punkte für ein gelöstes Spiel ist ein fester Betrag, unabhängig von der Zahl der Züge. Das ist Absicht und der wichtigste Unterschied zu Rad und Kalender: Beim Memory spielt der Browser, und der meldet dem Server nur, dass alle Paare gefunden sind. Eine Gutschrift nach Zügen ließe sich von dort aus fälschen. Bei einem festen Betrag, den es ohnehin nur einmal je Zeitraum gibt, bringt Schummeln nichts, was der Kunde nicht auch ehrlich bekäme. Ob er überhaupt spielen darf und wie viel es bringt, entscheidet weiterhin allein der Server.

Wie oft gespielt werden darf, lässt sich täglich, wöchentlich oder einmalig einstellen. Ebenso lässt sich das Spiel auf angemeldete Kunden, auf bestimmte Kundengruppen und auf bestimmte Seiten begrenzen.

Unter Aussehen stehen Hintergrund und Textfarbe des Fensters, zwei Schriftgrößen, die Farbe der Kartenrückseite, die Farbe des Kartenrands und die Mindestbreite einer Karte. Aussehen des Memorys zurücksetzen stellt diese sieben Werte auf die mitgelieferten zurück; Bilder, Punkte und Schalter bleiben unberührt.

Die Punkte werden unmittelbar gutgeschrieben; im Kundenkonto erscheinen die Zeilen als „Memory“, ebenso in der Buchungsliste des Adminbereichs. Jede gelöste Partie wird zusätzlich im Protokoll von Shopware vermerkt.

Treuestufen

Mitgeliefert sind fünf Stufen: Bronze als Einstieg, darüber Silber, Gold, Platinum und Diamant. Sie lassen sich umbenennen, entfernen und um eigene ergänzen.

Alle Stufen starten mit dem Punktefaktor 1. Sie sind damit zunächst reine Auszeichnung und ändern nichts an der Menge gesammelter Punkte. Wer höhere Stufen schneller sammeln lassen will, erhöht den Faktor je Stufe im Reiter Treuestufen — etwa 1,25 für Gold, womit dieselbe Bestellung ein Viertel mehr Punkte bringt.

Maßgeblich ist nicht das aktuelle Guthaben, sondern die Summe aller je gesammelten Punkte. Einlösen kostet also keine Treuestufe. Wer eine Schwelle überschreitet, sammelt ab der nächsten Bestellung mit dem höheren Faktor.

Die Zuordnung richtet sich nach den eingestellten Schwellen, nicht nach einer festen Rangfolge: Es gilt immer die höchste erreichte Schwelle. Vertauschte Werte führen daher zu keinem widersprüchlichen Ergebnis.

Einlösen

Im Warenkorb erscheint ein Feld für die Punktzahl. Daraus wird eine Rabattposition, deren Höhe sich aus dem Gegenwert je Punkt ergibt.

Der Ablauf im Einzelnen:

Nur für angemeldete Kunden. Das Feld erscheint, sobald jemand eingeloggt ist und Guthaben hat. Gäste sehen im Warenkorb nur, wie viele Punkte der Einkauf einbringen würde.

Zwei Grenzen bestimmen, wie viel einlösbar ist. Zum einen das Guthaben des Kunden. Zum anderen ein Anteil am Warenwert: Bei 50 Prozent und einem Warenkorb von 200 € lassen sich höchstens 100 € über Punkte decken — bei einem Punktwert von 0,01 € also 10.000 Punkte. Der kleinere der beiden Werte gilt. Versandkosten zählen dabei nicht mit, nur die Ware.

Mindestmenge. Liegt die Eingabe unter der eingestellten Untergrenze, weist das Plugin sie mit einer Meldung ab. Liegt sie über dem Einlösbaren, wird stillschweigend auf das Mögliche gekürzt statt abgelehnt — das ist freundlicher als eine Fehlermeldung für einen Wunsch, den der Kunde nicht kennen konnte.

Die Rabattposition zählt nicht als Ware. Sie geht deshalb nicht in die Berechnung des Höchstanteils ein. Andernfalls würde der Rabatt die Grundlage schmälern, aus der er selbst berechnet wird.

Rückgängig machen. Eine Null im Feld entfernt die Position wieder, und die Punkte stehen sofort erneut zur Verfügung.

Abgebucht wird erst mit der Bestellung, nicht schon beim Einlegen in den Warenkorb. Ändert sich der Warenkorb zwischendurch, rechnet das Plugin die Grenze neu. Wird der Einkauf kleiner, kann der Rabatt dadurch schrumpfen — den überzähligen Teil behält der Kunde auf seinem Konto.

Die Punkteanzeige im Warenkorb

Unabhängig vom Einlösen zeigt das Plugin, wie viele Punkte der aktuelle Warenkorb einbringen würde.

In der Karte Warenkorb im Reiter Einstellungen lässt sich jede der beiden Stellen einzeln schalten: Punkte auf der Warenkorbseite anzeigen und Punkte im Off-Canvas-Warenkorb anzeigen. Auch Gästen anzeigen gilt für beide.

Die Zeile steht auf der Warenkorbseite unter der Überschrift "Zusammenfassung" und im Off-Canvas-Warenkorb über der Summe.

Auf der Warenkorbseite setzt ein Skript die Zeile, weil dort mehrere Erweiterungen um dieselben Twig-Blöcke streiten. Das Plugin meldet zwar eine erhöhte Priorität für seine Vorlagen an, doch das hilft nur gegen andere Plugins — das Theme kommt in jedem Fall zuletzt. Im Fenster genügt der einfache Weg über eine Vorlage.

Im Off-Canvas-Warenkorb steht außerdem, wie viele Punkte die aktuelle Zusammenstellung einbringt. Gerechnet wird wie bei der späteren Gutschrift: netto oder brutto nach Einstellung, und ohne Versandkosten, sofern diese nicht ausdrücklich mitzählen sollen. Über Auch Gästen anzeigen in derselben Karte lässt sich das getrennt regeln.

Die Zeile hängt nicht am Schalter Punkte sammeln möglich — sie erscheint auch dann, wenn das Sammeln gerade ruht. Die Eingrenzung auf Kundengruppen gilt dagegen weiter.

Die Zeile erscheint auch für Gäste, dann mit dem Hinweis, dass eine Anmeldung nötig ist, und mit dem Grundfaktor gerechnet — eine Stufe ist ohne Konto nicht bekannt. Sie bleibt weg, wenn gar keine Punkte zusammenkommen oder die Kundengruppe nicht sammeln darf.

Doppelte-Punkte-Aktion

Im Reiter Aktionen vervielfacht eine zeitlich begrenzte Aktion die Punkte für jeden Einkauf — etwa doppelte Punkte im Advent.

Der Faktor liegt zwischen 1 und 10 und kommt zur Treuestufe hinzu. Ab Werk stehen alle Stufen auf 1 — dann bedeutet Faktor 2 schlicht die doppelte Punktzahl. Haben Sie einer Stufe einen eigenen Faktor gegeben, etwa 1,5 für Gold, vervielfachen sich beide: Der Kunde erhielte dann das Dreifache.

Oben in der Karte steht in einem Satz, was gerade gilt — etwa „Eingerichtet: 2-fache Punkte ab dem 01.12.2026“ oder „Läuft: 2-fache Punkte bis einschließlich 24.12.2026“. Läuft die Aktion, ist die Zeile grün hinterlegt.

Beginn und Ende sind Tagesangaben, dazu lässt sich je eine Uhrzeit setzen. Ohne Uhrzeit zählt der ganze Tag: der Beginn ab 0:00 Uhr, das Ende bis 23:59 Uhr. Mit Uhrzeit beginnt oder endet die Aktion genau dann — die angegebene Minute zählt beim Ende vollständig mit. Bleibt ein Feld leer, ist die Seite offen: ohne Beginn gilt die Aktion sofort, ohne Ende läuft sie, bis Sie sie abschalten.

Die Aktion wirkt an allen Stellen gleich: auf der Produktseite, im Warenkorb und bei der Gutschrift zur Bestellung. Außerhalb des Zeitraums bleibt alles beim Alten — ein nachträgliches Umstellen ändert bereits gebuchte Punkte nicht.

Verfall

In der Vorgabe verfallen Punkte nie. Wird der Verfall eingeschaltet, verliert ein Kunde sein Guthaben, wenn er die eingestellte Zahl von Tagen lang weder gesammelt noch eingelöst hat. Jede Buchung setzt die Frist neu — wer bestellt oder einlöst, fängt von vorn an.

Was verfällt, ist über eine Auswahl schaltbar:

• Das gesamte Guthaben — die Vorgabe, das bisherige Verhalten.
• Ein Anteil des Guthabens, in Prozent, in der Vorgabe 10. Bei 25 Prozent und 999 Punkten verfallen 249; es wird abgerundet, damit nie mehr verfällt als eingestellt. Ergibt der Anteil weniger als einen Punkt, passiert nichts.
• Eine feste Punktzahl je Verfall. Ist das Guthaben kleiner, verfällt nur das Guthaben.

Beide Felder — Anteil und feste Punktzahl — stehen dauerhaft in der Karte. Es wirkt jeweils nur das zur Auswahl passende; die Hilfetexte sagen, welches wann gilt.

Da jede Buchung die Frist zurücksetzt, beginnt sie nach einem Teilverfall von Neuem. Ein Rechenbeispiel in der Karte zeigt das mit Ihren Werten: wie viele Punkte von einem Guthaben von 1000 beim ersten Verfall abgebucht werden und was nach vier Fristen übrig bleibt. Bei 25 Prozent sind das 750, 563, 423 und 318 Punkte. Ist der Verfall abgeschaltet, steht dort ein entsprechender Hinweis.

Der Verfall mindert nur das Guthaben. Die insgesamt gesammelten Punkte und damit die Treuestufe bleiben erhalten; niemand steigt durch Untätigkeit ab. In der Buchungsliste erscheint der Vorgang als eigene Art "Verfall".

Vor dem Verfall geht eine E-Mail-Erinnerung an den Kunden, in der Vorgabe fünf Tage vorher, mit Guthaben und Verfallsdatum. Eine 0 schaltet sie ab. Jeder Kunde wird je Frist nur einmal erinnert; das Konto merkt sich den Versand.

Beides erledigt eine tägliche Aufgabe. Sie erscheint im Adminbereich unter Einstellungen > System > Aufgaben als plugware_loyalty.expiry und setzt voraus, dass der Aufgabenlauf des Shops eingerichtet ist.

Die Texte der E-Mail stehen als Textbausteine unter plugwareLoyalty.expiryMail und lassen sich je Sprache anpassen.

Bis 1.44.0 wurde die Frist in Monaten geführt. Ein noch gespeicherter Wert wird mit 30 Tagen je Monat übernommen, damit eine bestehende Einstellung nicht stillschweigend auf die Vorgabe zurückfällt.

Storno

Wird eine Bestellung storniert, dreht das Plugin die zugehörigen Buchungen zurück: gutgeschriebene Punkte werden abgezogen, eingelöste wieder gutgeschrieben. Beides wird getrennt gebucht, damit die gesammelte Gesamtsumme und damit die Treuestufe korrekt bleiben.

Ein Rechenbeispiel

Mit den Vorgabewerten — 1 Punkt je Euro, Punktefaktor 1 in allen Stufen, ein Punkt entspricht 0,01 EUR, mindestens 100 Punkte je Einlösung, höchstens 50 Prozent des Warenwerts:

• Eine Bestellung über 120,00 EUR bringt in der Stufe Bronze 120 Punkte.
• Nach insgesamt 500 gesammelten Punkten gilt Silber. Am Faktor 1 ändert sich nichts, es bleibt bei 120 Punkten; wird für Silber 1,1 eingetragen, sind es 132.
• Ein Guthaben von 500 Punkten entspricht 5,00 EUR Rabatt.
• Bei einem Warenkorb von 8,00 EUR greift die 50-Prozent-Grenze: einlösbar sind höchstens 4,00 EUR, also 400 Punkte. Die übrigen 100 bleiben stehen.

Der Block für die Erlebniswelt

Unter Inhalte > Erlebniswelten steht in der eigenen Kategorie Bonuspunkte der Block Bonuspunkte: So funktioniert es. Er erklärt Kunden das Programm — und zwar mit den Zahlen aus den Einstellungen des jeweiligen Verkaufskanals, sodass die Beschreibung nicht von Hand nachgepflegt werden muss.

Aufgeführt wird, was tatsächlich eingeschaltet ist:

Verlangt der Shop eine Zustimmung, steht vor der Liste ein hervorgehobener Hinweis: Das Sammeln muss der Kunde einmalig selbst einschalten, sonst werden keine Punkte gesammelt. Er steht abgesetzt und nicht als Schritt in der Liste, weil er keine Möglichkeit beschreibt, sondern eine Voraussetzung.

Die Liste selbst nennt:

• wie viele Punkte es je Euro gibt, sofern das Sammeln aktiv ist,
• ab welcher Punktzahl sich einlösen lässt, was das wert ist und welcher Höchstanteil gilt — nur, wenn es überhaupt einen Weg zum Einlösen gibt,
• die festen Treueprämien mit vorab bekannter Punktzahl, sofern welche angelegt und eingeschaltet sind — gibt es darunter eine Versandprämie, wird auch das genannt,
• der Weg über einen Gutscheincode, sofern Gutscheine aktiv sind,
• die Zahl der Treuestufen, sofern es mehr als eine gibt,
• der Verfall samt Frist, sofern eingeschaltet — mit dem Hinweis auf die Erinnerung per E-Mail, sofern eine Erinnerungsfrist gesetzt ist.

Die Karte CMS Erlebniswelt-Block im Reiter Einstellungen hat einen einzigen Schalter: Erklärung im Block anzeigen. Ist er aus, bleibt der Block leer.

Darunter steht Welche Zeilen erscheinen als Liste von Auswahlkästchen — neun Stück, in mehreren Spalten. Abgewählte Zeilen bleiben weg, angehakte erscheinen — unabhängig davon, ob der zugehörige Bereich im Shop eingeschaltet ist. Damit steuern Sie den Text des Blocks selbst. Prüfen Sie deshalb, was Sie ankreuzen: Eine Zeile über Gutscheine erscheint auch dann, wenn Sie keine anbieten.

Der Hinweis auf den Stichtag ist eine gewöhnliche Zeile: "Es werden keine Punkte von Bestellungen vor dem 02. September 2026 nachgetragen." Das Datum steht im Text und lässt sich im Reiter Texte ändern. Der Satz beschreibt nur — er hält das Nachtragen selbst nicht auf. Ab Werk ist die Zeile abgeschaltet.

Grafik: So funktioniert es zeigt unter den Zeilen eine Übersicht in vier Schritten — einkaufen, Coins sammeln, Guthaben ansehen, Rabatt einlösen. Sie ist für Kunden gedacht und nennt keine Einstellungen. Ab Werk ist sie abgeschaltet.

Ein Eintrag darunter ist keine Zeile: Stufenleiter als Abbildung zeigt unter der Liste dieselbe Leiter wie das Kundenkonto, mit den Bildern der Stufen, ihren Namen und den nötigen Punkten. Sie erscheint beispielhaft, ohne eine Stufe hervorzuheben — der Block wird zwischengespeichert und für alle Besucher gleich ausgeliefert, dürfte also nichts Persönliches zeigen. Angezeigt wird sie nur, wenn es mehr als eine Stufe gibt.

Ein Häkchen erzwingt nichts: Die Zeile erscheint nur, wenn Ihr Shop den Bereich auch anbietet. Sind Gutscheine abgeschaltet, fehlt die Zeile dazu, selbst wenn sie angehakt ist. Die Auswahl kann also weglassen, nicht hinzufügen — damit verspricht der Block nichts, was der Shop nicht einlöst.

Die Texte selbst passen Sie im Reiter Texte an.

Im Blockeditor lässt sich davon abweichend eine eigene Überschrift eintragen, die nur für diesen einen Block gilt. Ohne Angabe greift der Text aus dem Reiter Texte, sonst der mitgelieferte. Angemeldeten Kunden wird zusätzlich eine Schaltfläche zu ihren Bonuspunkten gezeigt.

Ist das Programm für den Verkaufskanal abgeschaltet, bleibt der Block leer, statt etwas zu versprechen.

Teilnahme am Programm

Jeder Kunde entscheidet in seinem Konto selbst, ob er sammelt. Die Karte Teilnahme am Bonusprogramm steht dort ganz oben und zeigt den aktuellen Stand.

Beim Einschalten ist eine Zustimmung nötig. Der Kunde setzt ein Häkchen, das benennt, was geschieht: Zu seinem Konto wird ein Punktestand geführt, der sich aus seinen Bestellungen ergibt. Ohne Häkchen passiert nichts. Der Zeitpunkt der Zustimmung wird am Konto festgehalten und ist damit später belegbar.

Nach der Zustimmung geht eine Bestätigung per E-Mail an den Kunden, mit seinem Guthaben und dem Datum. Scheitert der Versand, bleibt die Zustimmung trotzdem bestehen — sie ist wichtiger als die Nachricht; der Fehlschlag landet im Protokoll.

Beim Beenden bleibt das Guthaben erhalten. Es wird nur nicht weiter gesammelt; Einlösen, Prämien und Gutscheine stehen weiterhin offen. Jederzeit lässt sich wieder teilnehmen.

Die Einstellung Zustimmung zum Sammeln verlangen ist in der Vorgabe eingeschaltet: Neue Kunden sammeln erst, wenn sie im Kundenkonto zugestimmt haben. Schalten Sie sie ab, nehmen neue Konten von Anfang an teil und können die Teilnahme selbst beenden.

Bestehende Konten bleiben in beiden Fällen unverändert und nehmen weiter teil. Sollen auch sie erst zustimmen, lässt sich das mit einer Anweisung auf der Datenbank nachholen:

UPDATE plugware_loyalty_account SET opted_in = 0, opted_in_at = NULL;

Danach sammelt niemand mehr, bis er im Kundenkonto zustimmt. Vorhandenes Guthaben bleibt dabei unberührt.

Was Kunden sehen

Alle Bilder tragen einen Alt-Text mit Inhalt: die Grafik der Punkte nennt deren Bezeichnung, Stufenbilder den Namen der Stufe, Prämienbilder den Namen der Prämie. Vorleseprogramme geben damit etwas Sinnvolles wieder statt eines Dateinamens. ./check.sh prüft, dass kein Bild ohne oder mit leerem Alt-Text ausgeliefert wird.

Plakette am Produktbild

Über Plakette am Produktbild zeigen in der Karte Frontend-Einstellungen erscheint die mögliche Punktzahl als Plakette über dem Produktbild: auf der Produktseite über der Bildergalerie sowie in Listen, im Suchergebnis und überall dort, wo Artikel als Kachel dargestellt werden. In der Vorgabe ist sie abgeschaltet.

Vor der Zahl steht die mitgelieferte Münze, die mit der Schriftgröße der Plakette mitwächst. Die Lage ist wählbar: oben auf Höhe der übrigen Plaketten oder unten am Bildrand. Sie sitzt jeweils rechts, damit sie Shopwares eigene Plaketten wie Angebot und Topseller nicht überdeckt. Der Abstand zum rechten Rand ist in Pixeln einstellbar, zwischen 0 und 200 bei einer Vorgabe von 10 — nützlich, wenn Ihr Theme dort bereits eigene Plaketten setzt. Ebenso der Abstand nach oben, Vorgabe 40, und nach unten, Vorgabe 20; es zählt jeweils der Wert, der zur gewählten Lage passt.

Farben und die Eingrenzung auf Kundengruppen übernimmt sie von der Punkteangabe auf der Produktseite; der Punktefaktor der Treuestufe fließt hier nicht ein.

Mit Plakette zeigt nur die Punktzahl steht auf ihr nur die Zahl, etwa „+26", und die Bezeichnung dahinter entfällt. Das hält sie auf schmalen Kacheln kurz. Die Münze bleibt davor stehen. Ein eigener Text aus dem Reiter Texte wird dann nicht verwendet, da er die Bezeichnung fest enthält.

Auf der Produktseite

Unter dem Preis steht mit der Grafik davor, wie viele Punkte der Artikel einbringt: „Sie sammeln 119 Bonuspunkte mit diesem Artikel." Gezeigt wird die eingestellte Grafik, sonst die mitgelieferte Münze. Die Zeile ist farbig hinterlegt; die Farbe wählen Sie in derselben Karte unter Hintergrund der Punkteangabe am Artikel. In der Vorgabe ein kräftiges Gelb (#ffc505).

Daneben stehen Schriftfarbe der Punkteangabe und Schriftgröße der Punkteangabe in Pixeln, in der Vorgabe ein dunkles Braun und 15 Pixel; auf dem gelben Grund ergibt das ein Kontrastverhältnis von 6,9:1 und damit gut lesbaren Text. Die Größe der Grafik davor steht in einem eigenen Feld, Größe der Grafik in Pixeln. In der Vorgabe 0: dann richtet sie sich nach der Schriftgröße und wächst mit ihr. Ein eigener Wert zwischen 12 und 96 löst diese Kopplung.

Ebenfalls dort: Eckenradius der Punkteangabe in Pixeln, in der Vorgabe 6. Eine 0 ergibt einen eckigen Kasten, hohe Werte eine Pille; begrenzt ist der Wert auf 40.

Angenommen werden bei beiden Farben Hexwerte und rgb-Angaben. Andere Eingaben werden verworfen und durch die Vorgabe ersetzt — der Wert landet in einem style-Attribut, und dort hat nichts anderes etwas zu suchen. Abschalten lässt sich die Zeile über Punkte auf der Produktseite anzeigen in der Karte Frontend-Einstellungen, wo auch Farbe und Eckenradius stehen.

Gerechnet wird mit demselben Verfahren wie bei der späteren Gutschrift, samt Netto- oder Bruttowahl und dem Faktor der Treuestufe. Angemeldete Kunden sehen ihren eigenen Faktor, alle übrigen den der Einstiegsstufe — mehr ließe sich nicht versprechen, weniger wäre zu pessimistisch.

Kommen die vorbereiteten Angaben nicht an — etwa weil ein Theme oder eine Erlebniswelt den Kaufbereich mit einem anderen Produktobjekt füllt —, rechnet die Vorlage selbst aus den Einstellungen. Dann fehlt allein der Faktor der Treuestufe; die Zahl entspricht der Einstiegsstufe.

Über Nur für diese Kundengruppen sichtbar lässt sich die Zeile zusätzlich auf bestimmte Gruppen begrenzen. Ohne Auswahl sehen sie alle. Nicht angemeldete Besucher gehören zur voreingestellten Gruppe des Verkaufskanals — wählen Sie diese nicht mit aus, bleibt die Zeile für Gäste unsichtbar.

Die Einschränkung gilt an beiden Stellen, an denen die Zahl entstehen kann; sie lässt sich also nicht dadurch umgehen, dass die vorbereiteten Angaben ausbleiben.

Nichts angezeigt wird darüber hinaus bei Gästen, bei vom Sammeln ausgeschlossenen Kundengruppen, bei abgeschaltetem Sammeln und wenn der Preis weniger als einen Punkt ergibt.

Im Kundenkonto liegt eine Kachel, auf der das Guthaben als große Zahl neben der Grafik steht, mit der Treuestufe als Plakette daneben. Auf der eigenen Seite erscheint die Stufe ebenfalls als Plakette statt als Textzeile.

Darunter steht Ihr Weg durch die Treuestufen: alle Stufen der Reihe nach mit Bild, Name und Schwelle. Erreichte Stufen erscheinen kräftig, noch offene abgeblendet, die aktuelle ist umrandet und mit "Sie sind hier" versehen. Maßgeblich sind die insgesamt gesammelten Punkte — eingelöste Punkte nehmen keine Stufe weg. Bei nur einer Stufe entfällt die Darstellung. Dazu gibt es eine eigene Seite unter /account/loyalty mit dem Abstand zur nächsten Stufe und allen Buchungen. Sind Treueprämien hinterlegt, zeigt die Kachel darunter die drei günstigsten mit ihrer Punktzahl und je einer Schaltfläche zum Einlösen. Nicht erreichbare erscheinen abgeblendet und nennen die fehlende Punktzahl statt der Schaltfläche. Alle weiteren stehen auf der Detailseite.

Nach dem Einlösen landet der Kunde auf der Bonuspunkte-Seite, wo der Gutscheincode steht — von der Kachel aus wäre er sonst nicht zu sehen. Angezeigt wird nur die Punktzahl, nicht ihr Gegenwert in Euro — der ergibt sich erst beim Einlösen aus dem Warenkorb oder aus dem gewählten Gutschein. Im Warenkorb steht das Einlöseformular neben dem Gutscheinfeld, und auf der Bestätigungsseite erscheint eine Zeile mit Guthaben oder eingelösten Punkten.

Grafik für die Punkte

Das Plugin bringt eine goldene Münze mit, die ohne weitere Einstellung neben dem Guthaben erscheint: im Kundenkonto, vor jeder Treueprämie, im Warenkorb, auf der Bestätigungsseite und im Kopfbereich des Reiters Überblick im Adminbereich.

Über die Medienverwaltung lässt sich stattdessen ein eigenes Bild hinterlegen. Solange nichts gewählt ist, zeigt das Feld in den Einstellungen die Münze als Vorschau. Empfohlen ist ein quadratisches Bild um 128x128 Pixel.

Die Anzeigegröße steht im Template (24 Pixel, im Kundenkonto 32) und ist bewusst dort hinterlegt statt in einer Stildatei, weil das Plugin ohne Theme-Build auskommt. Die Münze liegt unter src/Resources/public/img/coin.svg.

Eigene Bezeichnungen

Das Feld "Bezeichnung der Punkte" ersetzt das Wort in allen Texten der Storefront: Kontoseite, Kachel, Menüeintrag, Warenkorbformular und Rabattposition. Bleibt es leer, gilt je nach Sprache "Bonuspunkte" oder "Loyalty points". Ebenso lassen sich alle Treuestufen umbenennen.

Die technischen Schlüssel bronze, silver, gold, platinum und diamond bleiben unverändert; in der Datenbank steht der Schlüssel, nicht der angezeigte Name. Ein Umbenennen ändert daher weder gespeicherte Daten noch die Schwellenwerte.

Zwei Einschränkungen:

• Der Name lässt sich je Verkaufskanal setzen, aber nicht je Sprache. Wer je Sprache unterschiedliche Namen braucht, lässt das Feld leer und überschreibt stattdessen den Textbaustein plugwareLoyalty.defaultLabel.
• Die Beschriftung der Kachel unter Einstellungen im Adminbereich folgt der Sprache des Adminbereichs, nicht dem frei gewählten Namen — sie steht fest, bevor die Konfiguration gelesen werden kann. Innerhalb der Seite gilt dein Name.

Rabattpositionen in abgeschlossenen Bestellungen behalten den Namen, der zum Zeitpunkt der Bestellung galt.

Gutscheine aus Punkten

Ist die Umwandlung erlaubt, erscheint im Kundenkonto ein Formular. Der Kunde gibt eine Punktzahl ein und erhält einen Gutscheincode, den er im Warenkorb im Gutscheinfeld einlöst — auf demselben Weg wie jeden anderen Aktionsgutschein.

Sind Treueprämien hinterlegt, entfällt die freie Eingabe: Der Kunde sieht stattdessen die festgelegten Prämien mit Punktzahl und Wert und wählt eine davon aus.

Reicht sein Guthaben für eine Prämie nicht, erscheint diese abgeblendet, statt der Schaltfläche steht "Noch nicht erreichbar", und darunter wird die fehlende Punktzahl genannt. Das Formular fehlt in dem Fall vollständig, die Prämie lässt sich also auch nicht über einen nachgebauten Aufruf anfordern — und selbst dann prüft der Server das Guthaben erneut.

Technisch entsteht eine Shopware-Aktion mit Code. Sie ist auf den Kunden beschränkt (customerRestriction mit Eintrag in personaCustomers), auf den Verkaufskanal begrenzt und nur einmal einlösbar. Ein weitergegebener Code nützt also niemandem sonst.

Über die Höchstpunktzahl lässt sich begrenzen, wie viel ein Kunde auf einmal umwandeln darf; die Vorgabe sind 1000 Punkte. Bei 0 gilt keine Grenze. Das Formular schlägt nur den zulässigen Höchstwert vor, und die Prüfung greift zusätzlich auf dem Server.

Drei Punkte, die vor dem Einschalten bedacht sein wollen:

• Die Punkte werden sofort abgebucht, nicht erst beim Einlösen des Gutscheins. Löst der Kunde ihn nie ein, sind sie verbraucht.
• Abgelaufene Gutscheine erstatten nichts zurück. Bei 365 Tagen Laufzeit verfallen die eingesetzten Punkte mit dem Gutschein. Laufzeit 0 heißt: kein Ablauf.
• Jeder Gutschein ist eine eigene Aktion unter Marketing; bei vielen Kunden sammelt sich dort einiges an.

Der Code steht zusätzlich im Vermerk der Buchung und ist damit in der Buchungsliste des Kunden nachvollziehbar.

Ist "Gutscheincode per E-Mail senden" aktiv, bekommt der Kunde den Code zusätzlich per E-Mail, mit Wert, eingesetzten Punkten und Laufzeit. Die Texte liegen als Textbausteine unter plugwareLoyalty.voucherMail und lassen sich unter Einstellungen > Textbausteine je Sprache anpassen. Absender sowie Kopf- und Fußzeile kommen aus den Grundeinstellungen des Verkaufskanals. Schlägt der Versand fehl, bricht der Vorgang nicht ab: Der Gutschein besteht bereits, der Fehler landet im Protokoll, und der Code bleibt im Kundenkonto sichtbar.

Der Adminbereich

Zehn Reiter in dieser Reihenfolge: Überblick, Einstellungen, Texte, Treuestufen, Treueprämien, Gewinnspiele, Aktionen, Konten, Sichern und Übernehmen, Über dieses Plugin.

Die Reihenfolge folgt der Zusammengehörigkeit: erst der Einstieg, dann was eingestellt und formuliert wird, danach was das Programm ausmacht, dann die zeitlich begrenzten Aktionen, schließlich die Daten und zuletzt das Plugin selbst.

Die folgenden Abschnitte gehen die Reiter in dieser Reihenfolge durch. Nicht jeder braucht eine eigene Erklärung — was sich von selbst versteht, steht als Hinweis am Feld im Adminbereich.

Überblick

Ein hervorgehobener Kopfbereich mit der hinterlegten Grafik, den Punkten im Umlauf, der Anzahl der Konten und dem Schnitt je Konto. Darunter die Verteilung nach Treuestufe als Balken mit Anteilen, die letzten zehn Einlösungen mit Datum und Uhrzeit, Kunde, Vorgang und Punktzahl sowie die fünf Konten mit dem höchsten Guthaben. Solange kein Konto besteht, steht dort ein entsprechender Hinweis.

Die vollständige Liste mit Suche steht im Reiter Konten; der Überblick zeigt nur die Spitze und braucht dafür keine zusätzliche Abfrage.

Einlöseprotokoll. Eine zweite Karte im selben Reiter führt die letzten zehn Einlösungen mit Datum und Uhrzeit, Kunde, Vorgang und Punktzahl.

Jede Zeile trägt am Ende ein Löschen für den einzelnen Eintrag. Vor dem Löschen fragt der Adminbereich das Passwort ab, wie bei jeder Buchung.

Mehrere Einträge auf einmal entfernt Buchungen löschen im Reiter Sichern und Übernehmen.

Datum und Uhrzeit folgen der Sprache des Adminbereichs und der Zeitzone des Browsers, nicht der des Servers.

Das Einlöseprotokoll führt Buchungen der Art redeem — also Rabatte im Warenkorb und in Gutscheine umgewandelte Punkte. Gutschriften, Rückbuchungen, Handbuchungen und Verfall stehen nicht darin; die vollständige Historie eines Kunden liegt auf seiner Kundenseite und im Kundenkonto der Storefront.

Die Karte im Dashboard

Auf der Startseite des Adminbereichs erscheint direkt unter der Begrüßung eine Karte Bonuspunkte mit drei Zahlen für den gewählten Zeitraum: gesammelte Punkte, eingelöste Punkte und die Zahl der Buchungen.

Der Zeitraum lässt sich oben in der Karte umschalten — 24 Stunden, 2 Tage, 7 Tage oder 30 Tage. Die Auswahl gilt für die aktuelle Sitzung, beim nächsten Aufruf stehen wieder 24 Stunden.

Abschalten lässt sich die Karte im Reiter Einstellungen, Karte Darstellung, über Karte im Dashboard anzeigen. Ist sie abgeschaltet, wird auch nichts abgefragt.

Gezählt werden alle Buchungen über alle Verkaufskanäle. Gesammelte und eingelöste Punkte werden getrennt ausgewiesen, nicht verrechnet.

Gewinnspiele

Der Reiter Gewinnspiele trägt drei Karten: Glücksrad-Spiel, Adventskalender und Memory-Spiel.

Adventskalender

Der Kalender erscheint wie das Glücksrad als Fenster über der Seite, nach einer einstellbaren Wartezeit ab dem ersten Seitenaufruf des Besuchs.

Erster Tag legt das Datum des ersten Türchens fest. Ohne Angabe läuft der Kalender nicht — ein Kalender ohne Anfang hätte kein heutiges Türchen. Die Anzahl der Türchen liegt zwischen 1 und 31, Vorgabe 24. Nach dem letzten Türchen endet der Kalender von selbst; das Fenster erscheint dann nicht mehr.

Geöffnet werden darf nur das Türchen von heute, und das einmal. Verpasst ist verpasst.

Mit Türchen gemischt anordnen stehen die Nummern durcheinander wie bei einem gedruckten Kalender; ohne den Haken der Reihe nach. Die Anordnung ist dabei nicht zufällig im Wortsinn: Sie wird aus Startdatum, Anzahl und Verkaufskanal abgeleitet und liegt damit fest. Alle Besucher sehen dieselbe, und sie bleibt über Seitenwechsel und Tage hinweg gleich — andernfalls sprängen die Türchen bei jedem Aufruf umher und niemand fände sein Datum wieder. Ändern Sie das Startdatum, ergibt sich eine neue Anordnung.

Die Türchen sind leicht unterschiedlich geneigt und mit einem Verlauf unterlegt, damit das Gitter handgemacht wirkt statt wie eine Tabelle. Das heutige hebt sich durch einen Rahmen ab und pocht alle paar Sekunden kurz auf. Beim Öffnen klappt das Türchen um und zeigt auf der Rückseite die gewonnenen Punkte. Wer im Betriebssystem bewegungsarme Darstellung eingestellt hat, sieht das Ergebnis ohne Bewegung.

Das Gitter unterscheidet vier Zustände: Schon geöffnete Türchen sind ausgegraut und gestrichelt umrandet, verpasste blass ohne Rahmenwechsel, künftige hell und das heutige hervorgehoben. So sieht ein Kunde auf einen Blick, welche Türchen er bekommen hat und welche ihm entgangen sind. Welche er geöffnet hat, liest der Shop aus seinen Buchungen — die Nummer steht als Kommentar daran, dafür braucht es keine zusätzliche Tabelle.

Hinter einem gewöhnlichen Türchen stecken die Punkte je Türchen, hinter dem letzten die Punkte am letzten Türchen — es darf mehr einbringen, sonst lohnt das Durchhalten nicht. Null Punkte sind erlaubt; das Türchen zählt dann trotzdem als geöffnet.

Welches Türchen an der Reihe ist und ob es noch offensteht, entscheidet der Server. Eine verstellte Uhr im Browser hilft also nicht, alle Türchen im Voraus zu leeren. Der Tageswechsel richtet sich nach der Zeitzone des Servers. Wie beim Rad lassen sich der Kalender auf angemeldete Kunden, auf bestimmte Kundengruppen und auf bestimmte Seiten begrenzen.

Mit Hintergrundbild des Fensters legen Sie ein Bild hinter Gitter und Text. Es füllt das Fenster und passt sich seiner Größe von selbst an — ein Bild in bestimmten Maßen brauchen Sie also nicht. Wie das Bild ins Fenster passt wählt zwischen füllend, wobei es an den Rändern beschnitten wird, und vollständig, wobei Ränder in der Fensterfarbe bleiben. Der Schleier über dem Bild, zwischen 0 und 100 Prozent bei Vorgabe 55, legt die Fensterfarbe halbdurchsichtig darüber, damit Text und Türchen lesbar bleiben. Ohne Bild trägt die Fensterfarbe wie bisher, und der Schleier hat keine Wirkung.

Unter Aussehen lassen sich Hintergrund und Textfarbe des Fensters, die Schriftgröße im Fenster und die des Gewinns, die Farbe der Türchen, die Farbe von Rand und Hervorhebung, die Farbe der Zahlen sowie die Mindestbreite eines Türchens einstellen. Der Verlauf auf den Türchen entsteht aus der gewählten Farbe, jede trägt also dieselbe Tiefe. Die Mindestbreite bestimmt mittelbar die Spaltenzahl: Je breiter ein Türchen, desto weniger stehen nebeneinander.

Aussehen des Kalenders zurücksetzen stellt diese acht Werte auf die mitgelieferten zurück. Das Glücksrad bleibt dabei unberührt — jedes Spiel hat seine eigene Schaltfläche, die nur die Werte der eigenen Karte anfasst. Sie ist gesperrt, solange ohnehin alles auf der Vorgabe steht. Alle Farbangaben werden geprüft, bevor sie ins Fenster gelangen.

Die Schaltfläche Vorschau zeigt das Gitter so, wie es heute im Shop aussieht — mit dem Türchen von heute hervorgehoben, den vergangenen ausgegraut und den künftigen blass. Darunter steht in einem Satz, was gerade gilt: welches Türchen an der Reihe ist und wie viele Punkte dahinterstecken, oder dass der Zeitraum noch nicht begonnen hat, vorbei ist oder kein Startdatum gesetzt wurde. Derselbe Satz steht auch in der Karte neben der Schaltfläche, sodass Sie den Zustand ohne Öffnen des Fensters sehen. In der Vorschau lässt sich zum Ausprobieren jedes Türchen auf- und wieder zuklappen; geöffnet zeigt es die Punkte dahinter. Im Shop geht nur das von heute, und nur einmal — die Vorschau ist hier bewusst grosszügiger, damit Sie alle Werte prüfen können, ohne auf den jeweiligen Tag zu warten. Gebucht wird dabei nichts.

Die Punkte werden unmittelbar gutgeschrieben; im Kundenkonto erscheinen die Zeilen als „Adventskalender“, ebenso in der Buchungsliste des Adminbereichs. Jedes geöffnete Türchen wird zusätzlich im Protokoll von Shopware vermerkt.

In der ersten Karte steht das Glücksrad. Es erscheint in der Storefront als Fenster über der Seite, nach einer einstellbaren Wartezeit ab dem Laden.

Glücksrad läuft schaltet es ein. Es erscheint nur, wenn zusätzlich das Programm im Verkaufskanal aktiv ist und mindestens zwei Felder angelegt sind.

Wartezeit bis zum Öffnen liegt zwischen 0 und 600 Sekunden, Vorgabe 20. Gemessen wird ab dem ersten Seitenaufruf des Besuchs, nicht ab jedem einzelnen. Wer nach zwölf Sekunden weiterblättert, sieht das Rad also acht Sekunden später auf der neuen Seite, statt wieder von vorn zu warten. Ist die Zeit beim Aufruf schon um, erscheint es sofort. Wer das Fenster schließt, bekommt es im selben Besuch nicht erneut; beides merkt sich der Browser für die Dauer der Sitzung.

Nur angemeldeten Kunden zeigen hält das Fenster von Gästen fern. Ohne Haken sehen Gäste das Rad, an der Stelle des Drehknopfs steht dann aber ein Anmeldeknopf — Punkte brauchen ein Konto. Mit Haken erfährt ein Gast nicht einmal, dass es ein Rad gibt: Die Auskunft des Servers meldet schlicht, es sei keines vorhanden.

Nur auf diesen Seiten zeigen grenzt ein, wo das Rad auftaucht. Zur Wahl stehen Startseite, Kategorieseiten, Produktseiten, Suchergebnisse, Warenkorb, Kasse, Kundenkonto und die übrigen Seiten. Ohne Auswahl erscheint es überall. Die Kasse auszunehmen ist ratsam: Dort soll nichts vom Abschluss ablenken.

Diese Prüfung findet in der Vorlage statt und nicht auf dem Server — sie hängt an der Seite und nicht am Kunden, lässt sich also gefahrlos mit zwischenspeichern. Auf einer nicht gewählten Seite wird das Rad gar nicht erst geladen.

Nur für diese Kundengruppen grenzt ein, wem das Rad überhaupt erscheint. Ohne Auswahl allen Besuchern. Mit Auswahl bleibt es für alle übrigen aus, und ein Aufruf der Schnittstelle von Hand wird abgewiesen. Gäste haben keine bekannte Kundengruppe und sehen ein eingegrenztes Rad daher nicht.

Unter Nur für diese Kundengruppen lässt sich festlegen, wem das Rad überhaupt erscheint. Ohne Auswahl allen Besuchern; mit Auswahl ausschließlich Kunden dieser Gruppen, für alle anderen wird es gar nicht erst geladen. Gäste zählen zur Standardgruppe des Verkaufskanals. Geprüft wird auf dem Server, sowohl beim Anzeigen als auch beim Drehen.

Wie oft ein Kunde drehen darf — täglich ab Mitternacht, wöchentlich ab Montag oder ein einziges Mal überhaupt. Gezählt werden die Buchungen des Kunden. Auch eine Drehung ohne Gewinn wird als Buchung über null Punkte festgehalten, sonst ließe sie sich nicht zählen. Im Kundenkonto erscheinen diese Zeilen als „Glücksrad", ebenso in der Buchungsliste des Adminbereichs.

Die gewonnenen Punkte werden unmittelbar dem Konto gutgeschrieben, mit dem Feldnamen als Kommentar der Buchung. Sie zählen wie jede andere Gutschrift in die gesammelte Gesamtsumme und damit in die Treuestufe ein und erscheinen in der Tagesstatistik unter „Gesammelt". Zusätzlich vermerkt das Plugin jede Drehung im Protokoll von Shopware — mit Kunde, Verkaufskanal, getroffenem Feld und Punktzahl, auch bei einer Niete. So lässt sich eine Rückfrage nachvollziehen, ohne die Datenbank zu durchsuchen.

Felder des Rades — zwei bis vierundzwanzig Stück mit Beschriftung, Punkten und Gewicht. Im Auslieferzustand sind dreizehn Felder vorbelegt: eine Niete und 5 bis 250 Punkte, kleine Gewinne häufig, große selten. Die Gewichte ergeben zusammen 1000, jedes lässt sich also unmittelbar als Promille lesen. Die Niete kommt in 15 von 100 Drehungen, es gewinnen also 85 Prozent; im Mittel bringt eine Drehung 20,55 Punkte. Die Niete trägt einen Strich als Beschriftung — eine „0“ ließe sich als Gewinn missdeuten. Die Beschriftungen sind bloße Zahlen, damit sie in jeder Sprache passen — ändern Sie sie nach Belieben. Bleiben weniger als zwei Felder übrig, gilt beim nächsten Laden wieder die Vorbelegung: ein Rad ohne Felder wäre kein Rad. Abgestellt wird es über Glücksrad läuft. Ab etwa vierzehn Feldern rückt die Beschriftung enger zusammen und wird kleiner gesetzt; halten Sie sie dann kurz.

Die Beschriftung liegt entlang des Radius und steht immer aufrecht: Auf der linken Hälfte wird sie um 180 Grad gekippt, damit sie nicht kopfüber erscheint. Zu lange Texte werden am Ende abgeschnitten, statt über den Rand hinauszulaufen. Das Gewicht steuert die Wahrscheinlichkeit im Verhältnis zu den übrigen Feldern; die Spalte Chance rechnet es in Prozent um. Null Punkte ergeben eine Niete.

Die Felder stehen nach Punkten aufsteigend, in der Tabelle wie auf dem Rad. Sortiert wird beim Laden der Seite und beim Hinzufügen eines Feldes, nicht während des Tippens — sonst spränge die Zeile unter dem Cursor weg, sobald Sie eine Zahl ändern. Eine geänderte Punktzahl rückt also erst beim nächsten Laden an ihren Platz. Das Rad im Shop ist immer sortiert.

Felder zurücksetzen stellt die mitgelieferten dreizehn Felder wieder her. Eigene Felder gehen dabei verloren. Die Schaltfläche ist gesperrt, solange die Liste ohnehin der Vorgabe entspricht.

Die Schaltfläche Vorschau, am Ende des Abschnitts Aussehen neben dem Zurücksetzen, zeigt das Rad so, wie es im Shop aussieht, samt Aufteilung und Beschriftung. Sie dreht sich im Browser und bucht nichts; sie zieht nach denselben Gewichten, damit sich die Verteilung ausprobieren lässt. Der echte Gewinn fällt im Shop auf dem Server.

In der Mitte des Rades sitzt die Münze — dasselbe Bild wie im Kundenkonto, also das unter Bild für die Punkte eingestellte oder die mitgelieferte. Sie dreht sich nicht mit, damit ihre Aufschrift lesbar bleibt, und trägt einen Ring in der Farbe des Radrandes.

Der Durchmesser des Rades ist frei wählbar, Vorgabe 260 Pixel. Die Grenzen von 50 und 2000 sind nur Notnägel gegen unbrauchbare Werte: darunter wäre das Rad nicht bedienbar, darüber nirgends darstellbar. Das Fenster wächst mit. Auf schmalen Bildschirmen wird das Rad zusätzlich auf die verfügbare Breite verkleinert und bleibt dabei rund, ein großer Wert schadet dort also nicht. Die Vorschau im Adminbereich zeigt den Durchmesser maßstäblich: Passt das Rad nicht ins Fenster, werden Rad, Beschriftung und Münze gemeinsam im selben Verhältnis verkleinert, und darunter steht, auf wie viel Prozent.

Unter Aussehen lassen sich Hintergrund und Textfarbe des Fensters, die beiden Feldfarben, die Farbe von Rand und Zeiger sowie die Farbe der Beschriftung einstellen, dazu drei Schriftgrößen: eine für das Fenster, 10 bis 32 Pixel bei Vorgabe 16, eine für den erdrehten Gewinn unter dem Rad, 10 bis 64 bei Vorgabe 24, und eine für die Beschriftung der Felder, 6 bis 96 bei Vorgabe 12. Richten Sie letztere am Durchmesser aus — etwa vier bis fünf Prozent davon sind ein guter Anhaltspunkt, bei einem 800er-Rad also rund 32 bis 40 Pixel.

Gewinn pulsieren lassen lässt die Gewinnzeile nach dem Drehen viermal pochen, dann steht sie still. Es ist bewusst ein ruhiges Pulsieren mit gut einem Wechsel je Sekunde und kein hartes Blinken: schnelle Hell-Dunkel-Wechsel ab etwa drei Wechseln je Sekunde können Anfälle auslösen. Wer im Betriebssystem bewegungsarme Darstellung eingestellt hat, sieht die Zeile ruhig. Ab fünfzehn Feldern wird letztere auf vier Fünftel verkleinert, sonst überlappen die Beschriftungen. Die Vorschau zeigt alle Einstellungen sofort, sie sieht also nie schöner aus als der Shop.

Aussehen zurücksetzen stellt die acht Werte auf die mitgelieferten zurück. Felder, Schalter, Wartezeit und Kundengruppen bleiben unberührt. Die Schaltfläche ist gesperrt, solange ohnehin alles auf der Vorgabe steht, und nennt darunter, was sie tun würde.

Alle Farbangaben werden geprüft, bevor sie ins Fenster gelangen: erlaubt sind Hex- und rgb-Schreibweisen, alles andere fällt auf die Vorgabe zurück. So kann über diese Felder nichts Fremdes in die Seite gelangen.

Welches Feld gewinnt, entscheidet der Server. Der Browser erfährt erst danach, wo das Rad stehen bleibt, und dreht es dorthin. Ein manipulierter Browser kann sich also keinen Gewinn aussuchen. Ebenso wird die Berechtigung serverseitig geprüft: Gäste sehen das Rad, können aber nicht drehen, da die Punkte kein Konto hätten; wer die Teilnahme nicht bestätigt hat, ebenso wenig.

Ob das Fenster erscheint, entscheidet nicht die Seite selbst, sondern eine Anfrage an den Server. Seiten werden zwischengespeichert, diese Antwort nicht — so bekommt kein Besucher den Stand eines anderen zu sehen.

Die Seite liegt unter Einstellungen > Bonuspunkte. Das Symbol des Plugins steht vor jeder Überschrift — vor dem Seitentitel, vor jeder Karte, vor jeder Reiterbeschriftung und in jedem Fenster, auch in der Karte auf der Kundenseite. In der Reiterleiste erscheint es kleiner und zurückgenommen; erst der aktive Reiter und der unter dem Mauszeiger zeigen es in voller Deckkraft. Es ist dieselbe Datei, die im Menü erscheint; ein Austausch von plugin.png wirkt überall.

Unter der Überschrift stehen zwei Plaketten: die installierte Versionsnummer, gelesen aus der Plugin-Verwaltung, und daneben die Punkte im Umlauf mit der hinterlegten Grafik. Die Summe wird beim Öffnen der Seite und nach jeder Buchung neu geholt. Das Info-Symbol öffnet die Dokumentation.

Die Seite hat sieben Reiter. Beim Wechsel bleiben Eingaben erhalten; Überblick und Konten holen ihre Zahlen bei jedem Aufruf frisch aus der Datenbank.

Aktionen

Der Reiter Aktionen trägt die Karte Doppelte-Punkte-Aktion. Sie vervielfacht die Punkte für jeden Einkauf in einem Zeitraum; Einzelheiten stehen weiter unten im Abschnitt zur Doppelte-Punkte-Aktion.

Oben in der Karte sagt eine Zeile, was gerade gilt. Läuft die Aktion, erscheint zusätzlich eine rote Plakette neben den Punkten im Umlauf — sichtbar aus jedem Reiter heraus.

Einstellungen

Ein Formular mit je einer Karte für Geltungsbereich, Allgemein, Sammeln und Einlösen, Verfall der Punkte, Gutscheine, Frontend-Einstellungen und Adminbereich. Treueprämien und Treuestufen haben eigene Reiter.

Sammeln und Einlösen. Diese Karte ist in zwei Abschnitte gegliedert, Sammeln und Einlösen, getrennt durch eine Linie. Darunter stehen die Punktefaktoren je Treuestufe und darunter ein Rechenbeispiel mit fünf Zeilen, das mit Ihren Werten mitrechnet:

• Wie viele Punkte eine Bestellung über 100 EUR bringt.
• Was die eingestellte Mindestpunktzahl beim Einlösen wert ist.
• Die Rückvergütung, gemessen am Umsatz — bei einem Punkt je Euro und einem Punktwert von einem Cent sind das 1,00 Prozent. Diese Zahl sagt, was das Programm den Shop kostet.
• Wie viel sich bei einem Warenkorb von 100 EUR höchstens einlösen lässt, nach Anwendung des Höchstanteils.
• Wie viele solcher Bestellungen bis zur ersten Stufe über dem Einstieg nötig sind.

Ein Faktor unter 1 mindert die Gutschrift: Bei 0,95 bekommt der Kunde fünf Prozent weniger Punkte, als der Bestellwert hergibt. Solche Zeilen sind in der Faktorentabelle rot hinterlegt und mit mindert gekennzeichnet, weil das an der Zahl allein kaum auffällt — bei der Einstiegsstufe beträfe es alle Kunden.

Ändern Sie einen Wert oben, ändert sich das Beispiel sofort mit. Der Punktefaktor der Treuestufe ist darin nicht enthalten; er kommt beim Sammeln noch hinzu.

Automatisches Speichern. Änderungen werden selbst gespeichert, eine Schaltfläche dafür gibt es nicht. Geschrieben wird erst, wenn eine knappe Sekunde lang nichts mehr passiert — beim Tippen entsteht also ein Schreibvorgang je Eingabe, nicht je Zeichen. In der Kopfzeile läuft der Stand als Plakette mit: "Änderung erkannt", "Wird gespeichert", schließlich "Gespeichert" mit Haken auf grünem Grund. Die Bestätigung blinkt zwei Sekunden und verschwindet dann von selbst; bei aktivem "Bewegung reduzieren" erscheint sie ruhig.

Wird die Seite verlassen, solange eine Änderung aussteht, wird sie sofort geschrieben. Schlägt das Speichern fehl, wechselt der Stand auf "Speichern fehlgeschlagen" und daneben erscheint eine Schaltfläche für einen erneuten Versuch; die Eingaben bleiben stehen.

Geschrieben werden nur Felder, die tatsächlich geändert wurden. Bei einem gewählten Verkaufskanal erben alle unberührten Felder weiterhin von "Alle Verkaufskanäle", statt ungewollt festgeschrieben zu werden.

Frontend-Einstellungen. Was Kunden im Shop sehen: der Schalter für die Punkteangabe auf der Produktseite samt Farbe und Eckenradius.

Adminbereich. Was nur Sie sehen: die Karte auf der Startseite sowie die Schriftgröße der Hinweistexte, zwischen 11 und 24 Pixeln, Vorgabe 13. Sie wirkt nur auf diese Seite. Ein unsinniger Wert fällt auf 13 zurück.

Automatisch speichern legt fest, ob Änderungen auf der Einstellungsseite von selbst gespeichert werden. Ohne Haken bleiben sie stehen, bis Sie oben auf Speichern klicken; die Schaltfläche erscheint dann, sobald etwas offen ist.

Dazu die Wartezeit bis zum Speichern, zwischen 1 und 60 Sekunden, Vorgabe 5. Sie gilt nur beim automatischen Speichern und wird sonst ausgeblendet. Änderungen auf dieser Seite werden nicht sofort geschrieben, sondern erst, wenn so lange nichts mehr geändert wurde; jede weitere Eingabe startet die Wartezeit neu. Wer die Seite vorher verlässt, verliert nichts: dann wird sofort gespeichert. Ein unsinniger Wert fällt auf 5 zurück.

Treueprämien

Jede Prämie hat eine Art:

• Gutschein auf den Warenwert — mindert die Bestellsumme um den Wert der Prämie.
• Artikel im Warenkorb — legt den hinterlegten Artikel hinein und zieht seinen Preis ab.
• Minderung der Versandkosten — der Rabatt gilt dem Versand statt der Ware.

Bei den ersten beiden entsteht ein Rabatt auf den Warenwert, bei der dritten einer auf die Lieferung. Der Kunde sieht im Kundenkonto einen entsprechenden Hinweis.

Ältere Prämien ohne diese Angabe gelten weiterhin: Ist ein Artikel hinterlegt, zählen sie als Artikelprämie, sonst als Gutschein.

Im Kundenkonto stehen Treueprämien und die freie Umwandlung in zwei getrennten Karten, jede mit eigenem Schalter:

• Treueprämien anbieten zeigt die angelegten Angebote — feste Punktzahl, fester Gegenwert.
• Umwandlung in Gutscheine erlauben lässt den Kunden die Punktzahl selbst wählen.

Beide sind unabhängig voneinander. Sie können also nur Prämien anbieten, nur die freie Umwandlung, beides oder nichts. Die Prüfung erfolgt auch beim Einlösen selbst, nicht nur in der Anzeige — ein abgeschalteter Weg lässt sich nicht über einen direkten Aufruf nutzen.

Treueprämien. Eine Tabelle mit Bezeichnung, Bild, Produkt, Mindeststufe, Kundengruppen, benötigten Punkten und Wert. Bearbeiten öffnet ein Fenster für die jeweilige Zeile, Entfernen löscht sie, Prämie hinzufügen legt eine neue an. Sortiert wird nach der Punktzahl.

Im Fenster lässt sich unter Nur für diese Kundengruppen festlegen, wer die Prämie bekommt. Ohne Auswahl steht sie allen offen; die Übersicht zeigt dann „alle". Mit Auswahl erscheint sie ausschließlich Kunden dieser Gruppen — anders als bei der Mindeststufe wird sie fremden Gruppen gar nicht erst angezeigt, denn hier gibt es nichts zu erreichen. Die Einschränkung wirkt zusätzlich zur Stufe, beide Bedingungen müssen erfüllt sein.

Geprüft wird nicht nur in der Anzeige, sondern auch beim Einlösen, im Warenkorb und bei der Zahl der Prämien, die der Erlebniswelt-Block ankündigt. Ein direkter Aufruf mit fremder Kennung führt also nicht zum Ziel. Beim Einlesen von Einstellungen aus einem anderen Shop wird die Auswahl gelöscht, da Kundengruppen-Kennungen nur im Ursprungsshop gelten; die Prämie steht danach zunächst allen offen.

Ohne Eintrag gibt der Kunde die Punktzahl selbst ein, wie bisher. Mit Einträgen wählt er stattdessen eine der festgelegten Treueprämien. Der Wert darf vom Gegenwert je Punkt abweichen — damit lassen sich größere Prämien günstiger anbieten, etwa 1000 Punkte für 12,50 EUR statt 10,00 EUR. Bei Wert 0 wird aus dem Gegenwert je Punkt gerechnet.

Im Fenster lässt sich über die Medienverwaltung ein eigenes Bild hinterlegen. Es erscheint im Kundenkonto anstelle der Grafik der Punkte — auf der Bonuspunkte-Seite mit 64 Pixeln, auf der Kachel in der Übersicht mit 28. Ohne Auswahl gilt weiterhin die Grafik der Punkte. Empfohlen ist ein quadratisches Bild um 128x128 Pixel.

Im Fenster lässt sich eine Mindeststufe wählen. Die Prämie erscheint im Kundenkonto dann erst, wenn der Kunde diese Treuestufe erreicht hat; darunter steht sie abgeblendet mit dem Hinweis "Ab Treuestufe Gold". Ohne Auswahl steht sie allen offen.

Verglichen wird über die Reihenfolge der Stufen, nicht über den Namen: Wer Platinum hat, kommt auch an Prämien ab Gold. Wird die verlangte Stufe später gelöscht, ist die Prämie wieder für alle verfügbar, statt unerreichbar zu werden.

Im Fenster lässt sich zusätzlich ein Produkt auswählen. Der Gutschein übernimmt dann dessen Namen und Bruttopreis als Vorschlag, beides bleibt änderbar. Im Kundenkonto steht darunter, wofür der Gutschein gedacht ist.

Prämien mit Artikel wirken anders als Prämien ohne. Ist ein Produkt hinterlegt, entsteht kein Gutscheincode: Der Kunde legt die Prämie direkt in den Warenkorb, wo der Artikel und ein Rabatt in Höhe des Prämienwerts erscheinen. Die Schaltfläche heißt dann "In den Warenkorb".

Die Punkte werden dabei nicht sofort abgebucht, sondern erst mit der Bestellung — wie bei der gewöhnlichen Einlösung. Wer den Warenkorb wieder leert, verliert also nichts.

Der Rabatt gilt für den gesamten Warenkorb, nicht nur für den Artikel. Wer ihn entfernt und andere Ware bestellt, behält den Rabatt. Mindestpunktzahl und Höchstanteil greifen hier nicht, weil die Prämie ihren Umfang selbst festlegt; gedeckelt wird nur am Warenwert, damit keine negative Summe entsteht.

Mindest- und Höchstpunktzahl gelten für Treueprämien nicht, weil der Eintrag den Umfang bereits festlegt.

Der Verkaufskanal wird im Reiter Einstellungen gewählt und gilt auch hier; die Prämien lassen sich also je Kanal unterschiedlich festlegen. Gespeichert wird automatisch, die Anzeige dazu läuft in der Kopfzeile mit.

Texte

Ein eigener Reiter für Texte, die Kunden im Shop lesen. Alle sechs stehen als Tabelle mit drei Spalten: Bezeichnung samt Ort, aktueller Text und die Schaltflächen.

Die Texte stehen in drei Karten, eine je Bereich: Produktseite, Kundenkonto und Erlebniswelt-Block. So findet man den gesuchten Text an der Stelle, an der man ihn vermutet.

Jede Karte hat ein eigenes Suchfeld. Gesucht wird in der Bezeichnung und im Textinhalt, dabei in beiden Sprachen und sowohl im eigenen als auch im mitgelieferten Text. Wer also weiß, wie ein Satz im Shop lautet, findet ihn, ohne die Bezeichnung zu kennen. Die Suche wirkt nur in ihrer Karte.

Jeder Text wird in beiden Sprachen gepflegt. Die Tabelle hat je eine Spalte für Deutsch und Englisch und zeigt darin den geltenden Text: Ihren eigenen, oder — kursiv — den mitgelieferten. Sie sehen also stets, was im Shop steht.

Welche Fassung erscheint, entscheidet die Sprache des Verkaufskanals, nicht die Ihres Adminbereichs.

Bearbeiten öffnet ein Fenster mit beiden Sprachen untereinander, jeweils mit dem geltenden Text vorbelegt. Sie können also eine Sprache anpassen und die andere unberührt lassen. Zurücksetzen stellt beide Sprachen auf den mitgelieferten Stand zurück.

Speichern Sie einen Text, der sich mit dem mitgelieferten deckt, wird nichts hinterlegt. Sonst bliebe er bei einer Aktualisierung des Plugins auf dem alten Stand stehen, während der mitgelieferte längst verbessert wurde.

Enthalten sind zweiunddreißig Texte:

• Produktseite — die Punkteangabe unter dem Preis und die Plakette am Bild.
• Kundenkonto — die Überschriften von Konto-Karte, Punkteseite, Guthaben, Stufenleiter und Buchungen, der Eintrag im Kundenmenü, sämtliche Texte der Teilnahme-Karte samt Schaltflächen sowie Überschriften, Einleitungen und Schaltflächen von Treueprämien und Gutschein-Umwandlung.
• Erlebniswelt-Block — die Überschrift, alle Zeilen und die Beschriftung der Schaltfläche.

Die Platzhalter unterscheiden sich je Text; der Hilfetext im Fenster nennt sie. Verbreitet sind %points% für eine Punktzahl und %label% für Ihre Bezeichnung der Punkte.

Ein Feld leer zu lassen bedeutet: In dieser Sprache gilt der mitgelieferte Text.

./check.sh prüft, dass jedes Feld in einer Vorlage tatsächlich ausgewertet wird; ein Feld ohne Wirkung wäre ein leeres Versprechen.

Der Reiter Treuestufen

Die Stufen stehen als Tabelle mit Name, Bild, Schwelle und Faktor. Bearbeiten öffnet ein Fenster für die jeweilige Zeile, Entfernen löscht sie, Stufe hinzufügen legt eine neue an. Die unterste Stufe ist immer der Einstieg; dort steht "Einstieg", und das Schwellenfeld fehlt im Fenster. Sortiert wird nach der Schwelle, die Reihenfolge ergibt sich von selbst.

Für alle fünf mitgelieferten Stufen bringt das Plugin geprägte Münzen mit — Bronze, Silber, Gold, Platinum und Diamant; sie erscheinen ohne weitere Einstellung. Eigene Stufen bleiben ohne Bild, bis eines zugewiesen wird. Über die Medienverwaltung lässt sich je Stufe ein eigenes Bild hinterlegen, das dann Vorrang hat. Solange nichts gewählt ist, zeigt das Feld im Bearbeitungsfenster die mitgelieferte Münze als Vorschau. Es erscheint im Kundenkonto neben der Treuestufe — auf der Bonuspunkte-Seite mit 40 Pixeln, auf der Kachel in der Übersicht mit 28. In der Tabelle steht es als Vorschau vor dem Namen. Ohne Auswahl erscheint kein Bild.

Bei einer neuen Stufe wird aus dem Namen einmalig eine technische Kennung gebildet ("Innerer Zirkel" wird zu innerer-zirkel). Sie bleibt beim Umbenennen erhalten, damit bestehende Konten ihre Zuordnung behalten. Wird eine Stufe entfernt, behalten Konten zunächst ihre alte Kennung und werden erst bei der nächsten Buchung neu eingestuft. Die letzte verbliebene Stufe lässt sich nicht entfernen.

Auch hier gilt der im Reiter Einstellungen gewählte Verkaufskanal, und gespeichert wird automatisch.

Konten

Die Konten mit dem höchsten Guthaben, mit Suche nach Name, E-Mail und Kundennummer.

Punkte buchen. Die Tabelle ist reine Anzeige. Gebucht wird über die Schaltfläche Punkte buchen neben der Suche; darin wird der Kunde ausgewählt — alle Kunden des Shops stehen zur Wahl, auch solche ohne Konto.

Eingetragen wird das gewünschte Guthaben, nicht die Differenz; darunter steht der bisherige Stand und die entstehende Buchung. Gesendet wird ebenfalls das Zielguthaben — verrechnet wird erst im Backend, damit eine zwischenzeitlich eingegangene Bestellung nicht überschrieben wird. Die Differenz landet als Buchung der Art manual in der Historie und ist damit auch für den Kunden sichtbar.

Besteht für den gewählten Kunden noch kein Konto, wird es angelegt. Bleibt das Guthaben dabei auf 0, entsteht nur das Konto, ohne Eintrag in der Historie.

Vor jeder Buchung fragt der Adminbereich das Passwort ab. Siehe den nächsten Abschnitt.

Die Passwortabfrage

Vor jeder Buchung erscheint ein Fenster, das nach dem Passwort des gerade angemeldeten Benutzers fragt — nicht nach einem eigenen Plugin-Passwort und nicht nach dem eines Administrators. Wer angemeldet ist, gibt sein eigenes Passwort ein.

Verwendet wird sw-verify-user-modal, dieselbe Komponente, mit der Shopware Rollen und Zugangsdaten absichert. Das Passwort wird an den Server geschickt und dort gegen das Konto geprüft; das Plugin sieht es nie und speichert nichts davon.

Was passiert wann:

• Richtiges Passwort — die Buchung läuft, das Fenster schließt sich, die Liste wird neu geladen.
• Falsches Passwort — eine Fehlermeldung, das Fenster bleibt offen, es wird nichts gebucht. Ein zweiter Versuch ist sofort möglich.
• Abbrechen — es passiert nichts. Deine Eingaben im Buchungsfenster bleiben stehen, du kannst sie ändern und erneut absenden.

Was sie leistet und was nicht. Sie schützt davor, dass an einem unbeaufsichtigten, angemeldeten Arbeitsplatz Guthaben verändert wird. Sie ist aber keine Berechtigung: Jeder Adminbenutzer, der die Plugin-Seite öffnen darf, kann mit seinem eigenen Passwort buchen. Eine Trennung nach Rollen gibt es bislang nicht, siehe die Hinweise für Entwickler.

Die Abfrage gilt für jede Buchung über die Oberfläche, also für das Ändern eines Guthabens ebenso wie für das Anlegen eines Kontos. Nicht betroffen sind das Nachtragen vergangener Bestellungen im selben Fenster, die Konsolenbefehle und die Admin-Routen — die Konsole setzt Zugriff auf den Server voraus, und dort wäre die Abfrage kein zusätzlicher Schutz.

Eine Erhöhung zählt zu den insgesamt gesammelten Punkten und kann eine Treuestufe auslösen. Eine Verringerung senkt diese Summe nicht.

Nachtragen. Im Bearbeiten-Fenster liegt Vergangene Bestellungen nachtragen. Näheres steht im Abschnitt Einstellungen unter "Punkte nachträglich vergeben".

Sichern und Übernehmen

Einstellungen sichern legt eine JSON-Datei mit allen Werten an, Datei einlesen holt sie zurück. Damit lässt sich eine Einrichtung vom Testshop in den Livebetrieb übertragen oder vor größeren Änderungen sichern. Maßgeblich ist der Geltungsbereich, der im Reiter Einstellungen gewählt ist; die Karte zeigt an, welcher gerade gilt.

Gesichert werden alle Einstellungen des Formulars, auch Treuestufen und Treueprämien — die Liste wächst automatisch mit, wenn neue Felder dazukommen.

Zwei Felder werden beim Einlesen übersprungen: die Grafik und die Kundengruppen. Bei Treueprämien gilt dasselbe für Produkt und Bild. Beide bestehen aus Kennungen, die nur im Ursprungsshop gelten — eingelesen würden sie auf nichts verweisen, und bei den Kundengruppen hätte das die stille Folge, dass niemand mehr sammelt. Sie stehen in der Datei, müssen im Zielshop aber von Hand gesetzt werden. Die Meldung nennt die Zahl der übernommenen und der übersprungenen Felder.

Bei Treueprämien mit Produkt wird aus demselben Grund der Produktbezug gelöst: Die Prämie kommt mit Bezeichnung, Punktzahl und Wert an, das Produkt muss im Zielshop neu gewählt werden. Eine Meldung nennt, wie viele Prämien das betrifft. Andernfalls zeigte die Prämie im Kundenkonto auf einen Artikel, den es dort nicht gibt.

Enthalten sind ausschließlich Einstellungen. Konten, Guthaben und Buchungen bleiben unberührt.

Daten löschen. Unter demselben Reiter, in einem leicht rot hinterlegten Kasten, lassen sich Daten dauerhaft aus der Datenbank entfernen. Zwei Auswahlen bestimmen den Umfang:

• Nur Einlösungen, alle Buchungen oder der gespeicherte Verlauf. Bei „alle Buchungen" sind auch Gutschriften, Handbuchungen, Rückbuchungen und Verfall betroffen; der Verlauf liegt in einer eigenen Tabelle und bleibt dabei unberührt.
• Alle oder nur solche, die älter als 90, 180 oder 365 Tage sind.

Damit verschwinden auch die Zahlen, die daraus berechnet werden: das Einlöseprotokoll, die Karte auf der Startseite und die Buchungsliste, die Ihre Kunden im Kundenkonto sehen. Eine gespeicherte Statistik gibt es nicht — alle Kennzahlen entstehen bei jedem Aufruf aus den Buchungen und den Konten.

Guthaben, gesammelte Punkte und Treuestufen bleiben unverändert; sie stehen am Konto, nicht an den Buchungen. Rückgängig lässt sich das Löschen nicht. Für vergangene Bestellungen hilft danach nur das Nachtragen im Reiter Konten.

Beim Umfang „der gespeicherte Verlauf" entfällt die Neuberechnung: Der Verlauf ist eine Aufzeichnung und beeinflusst keine Guthaben.

Wer möchte, kann im Bestätigungsfenster Guthaben und Stufen neu berechnen einschalten. Dann werden nach dem Löschen alle Konten aus den verbliebenen Buchungen abgeleitet: Guthaben als Summe aller Buchungen, gesammelte Punkte als Summe der Gutschriften abzüglich Rückbuchungen, die Stufe aus der Schwelle.

Diese Rechnung ist mit Bedacht zu verwenden. Löschen Sie Gutschriften, verlieren Kunden Guthaben und rutschen womöglich eine Stufe tiefer. Löschen Sie nur Einlösungen, steigt ihr Guthaben, weil die Abbuchungen fehlen. Sinnvoll ist die Neuberechnung daher fast nur beim Umfang „alle Buchungen" — etwa nachdem Sie versehentlich entstandene Buchungen entfernt haben. In der Vorgabe ist sie abgeschaltet.

Vor dem Löschen wird das Passwort abgefragt.

Über dieses Plugin

Name, Version, Autor, Lizenz, Hersteller sowie Installations- und Aktualisierungsdatum, dazu der Zugang zur Dokumentation.

Darunter die Karte Plugin-Medien mit den Bildern, die das Plugin mitbringt: dem Symbol des Plugins, der Münze für die Punkte und den fünf Stufenmünzen. Jede Zeile zeigt eine Vorschau, den Dateipfad, die Dateigröße und wofür das Bild verwendet wird. Zum Austauschen genügt es, die Datei im Plugin zu ersetzen; eigene Bilder wählen Sie stattdessen über die Medienverwaltung in den jeweiligen Einstellungen.

Dokumentation im Adminbereich

Das Info-Symbol in der Kopfzeile öffnet ein Fenster mit dieser Anleitung und der Änderungsliste, umschaltbar zwischen beidem und zwischen Deutsch und Englisch. Das Fenster öffnet in der Sprache des Adminbereichs; für Sprachen ohne eigene Fassung erscheint die englische. Regionale Fassungen zählen mit, de-AT öffnet also ebenfalls auf Deutsch. Die Sprache wird bei jedem Öffnen neu bestimmt, nicht einmalig beim Laden der Seite — sonst bliebe eine beim Seitenaufbau noch nicht geladene Sitzung dauerhaft folgenlos. Liegt die Erkennung im Einzelfall daneben, lässt sich im Fenster jederzeit umschalten.

Angezeigt werden die Dateien README_de-DE.md, README_en-GB.md, CHANGELOG_de-DE.md und CHANGELOG_en-GB.md aus dem Plugin-Verzeichnis, gelesen über die Route /api/_action/plugware-loyalty/documentation. Sie werden also nur an einer Stelle gepflegt.

Auf der Kundenseite

Im Reiter Allgemein steht ganz oben eine Karte mit Guthaben, insgesamt gesammelten Punkten und Treuestufe, dazu die letzten zehn Buchungen. Besteht noch kein Konto, sagt die Karte das.

In der Kundenübersicht erscheint eine Spalte ganz vorn mit dem Guthaben. Sie trägt den eingestellten Namen der Punkte; Kunden ohne Konto zeigen 0. Sortieren lässt sich danach nicht, weil das Guthaben in einer eigenen Tabelle liegt und nicht Teil der Kundenabfrage ist.

Sprachen

Oberfläche und Konfiguration liegen auf Deutsch und Englisch vor und folgen der Sprache des Adminbereichs. Die Sprachbausteine werden zur Laufzeit eingehängt, ein npm-Build ist dafür nicht nötig.

Konfiguration

Erreichbar an zwei Stellen, die dieselben Werte bearbeiten:

• Einstellungen > Bonuspunkte, Reiter Einstellungen — das Formular des Plugins
• Erweiterungen > Meine Erweiterungen, Schaltfläche Konfigurieren — die von Shopware aus der config.xml erzeugte Maske

Alle Werte sind je Verkaufskanal setzbar.

Treuestufen und Darstellung stehen nicht in dieser Tabelle: Sie werden ausschließlich im Formular des Plugins gepflegt. Eine wachsende Stufenliste lässt sich in der erzeugten Maske nicht abbilden, und die Schriftgröße ist eine Angabe zur Darstellung, kein Wert des Programms.

Punkte nachträglich vergeben

Wer das Programm erst später einführt, kann Punkte für vergangene Bestellungen nachtragen — im Reiter Konten, je Kunde oder für den gesamten Bestand.

Ob die Schaltfläche überhaupt erscheint, legt Nachtragen anbieten im Reiter Einstellungen fest, in der Karte Kritische Einstellungen am Ende des Reiters. Ohne Haken bleibt sie weg, und ein Aufruf der Schnittstelle von Hand wird abgewiesen — die Prüfung liegt auf dem Server, nicht nur in der Anzeige. Der Vorgang liest sämtliche Bestellungen eines Kunden und kann in großen Shops dauern; wer ihn nicht braucht, blendet ihn aus.

Übersprungen werden Gastbestellungen, stornierte Bestellungen und alles, wofür bereits eine Gutschrift besteht. Ein wiederholter Lauf ist deshalb ungefährlich und vergibt keine Punkte doppelt. Steht die Gutschrift auf "bei Zahlungseingang", zählen nur bezahlte Bestellungen.

Zwei Punkte: Gerechnet wird mit dem Faktor der heutigen Treuestufe, nicht der zum Bestellzeitpunkt — die lässt sich nachträglich nicht zuverlässig rekonstruieren. Und der Schalter "Punkte sammeln möglich" wird nicht geprüft, weil das Nachtragen eine ausdrückliche Handlung ist; die Begrenzung auf Kundengruppen gilt dagegen weiter.

Konsolenbefehle

bin/console plugware:loyalty:balance # Liste der Konten bin/console plugware:loyalty:balance kunde@example.com -t # einzeln, mit Buchungen bin/console plugware:loyalty:book kunde@example.com 250 -c "Gutschein" bin/console plugware:loyalty:book kunde@example.com -100 # abbuchen

Als Kunde wird die E-Mail-Adresse oder die Kundennummer erkannt.

Der gespeicherte Verlauf

Einmal täglich hält das Plugin die Kennzahlen des Tages in einer eigenen Tabelle fest: Zahl der Konten, Punkte im Umlauf, insgesamt gesammelte Punkte, die Bewegung des Tages getrennt nach gesammelt, eingelöst und verfallen, dazu die Verteilung auf die Treuestufen.

Der Reiter Überblick zeigt die letzten vierzehn Tage als Tabelle. Die Werte bleiben erhalten, auch wenn Buchungen später gelöscht werden — dafür ist der Verlauf da.

Der Lauf setzt einen funktionierenden Aufgabenlauf voraus. Läuft er zweimal am selben Tag, wird der Eintrag überschrieben statt verdoppelt. Beim Deinstallieren mit „Daten löschen" verschwindet die Tabelle mit.

Datenmodell

plugware_loyalty_account — ein Konto je Kunde mit Guthaben, insgesamt gesammelten Punkten und Treuestufe. Der Fremdschlüssel auf customer löscht mit; ein gelöschter Kunde nimmt sein Konto mit.

plugware_loyalty_transaction — jede Buchung mit Art (earn, redeem, revoke, manual, expire), Punkten, Vermerk und optionaler Bestellung.

Das Guthaben steht doppelt da: als Spalte und als Summe aller Buchungen. Das ist Absicht, weil Kontoseite und Warenkorb den Saldo bei jedem Aufruf brauchen. Beides wird ausschließlich in LoyaltyService::book() gemeinsam fortgeschrieben — wer direkt in die Tabellen schreibt, bekommt eine Historie, die nicht mehr zum Saldo passt.

Was beim Deinstallieren geschieht

Wird beim Deinstallieren "Daten behalten" gewählt, bleibt alles erhalten: Konten, Buchungen, Einstellungen und die erzeugten Gutscheine. Eine spätere Neuinstallation findet die Guthaben wieder vor.

Ohne diesen Haken entfernt das Plugin sämtliche Spuren:

• die Tabellen plugware_loyalty_transaction und plugware_loyalty_account
• alle gespeicherten Einstellungen unter PlugwareLoyalty.config., auch die je Verkaufskanal
• alle Aktionen, die aus Punkten entstanden sind, samt ihrer Rabatte, Übersetzungen und Verkaufskanal-Zuordnungen

Fremde Rabatt-Aktionen und übrige Shop-Einstellungen bleiben unberührt. Erkannt werden die eigenen Gutscheine am Merkmal, das beim Erzeugen gesetzt wird.

Nicht entfernt werden Bilder aus der Medienverwaltung — die gehören dem Shop, auch wenn eines als Grafik für die Punkte gedient hat.

Schutz vor Manipulation

Alles, was Guthaben kostet, wird auf dem Server entschieden. Die Storefront zeigt nur an, was ohnehin geprüft wird.

• Einlösen im Warenkorb. Die eingegebene Punktzahl ist ein Wunsch. Bei jeder Neuberechnung des Warenkorbs prüft das Plugin sie erneut gegen Guthaben, Mindestpunktzahl und Höchstanteil und kürzt sie bei Bedarf. Eine im Browser veränderte Eingabe ändert daran nichts.
• Treueprämien. Punktzahl, Wert und verlangte Treuestufe werden bei jeder Neuberechnung erneut aus den Einstellungen gelesen, nicht aus der Position im Warenkorb. Wird eine Prämie gelöscht oder ihre Stufe angehoben, verschwindet der Rabatt aus bestehenden Warenkörben.
• Gutscheine. Guthaben, Mindest- und Höchstpunktzahl sowie die Treuestufe werden im Controller geprüft, bevor Punkte abgebucht werden. Nicht erreichbare Prämien erscheinen im Kundenkonto ohne Formular.
• Abgebucht wird erst mit der Bestellung, und zwar aus der berechneten Position, nicht aus der Eingabe. Ein abgebrochener Warenkorb kostet nichts.
• Gäste nehmen nicht teil. Weder Sammeln noch Einlösen, an jeder Stelle geprüft.
• Gutscheincodes sind an den Kunden gebunden und einmal einlösbar; ein weitergegebener Code nützt niemandem sonst.

Rechte im Adminbereich. Unter Einstellungen > Benutzer und Rechte trägt jede Rolle drei Stufen unter Bonuspunkte:

• Betrachten — die Seite öffnen, Konten, Buchungen und Kennzahlen lesen.
• Bearbeiten — Guthaben buchen, Konten anlegen, Bestellungen nachtragen, Einstellungen speichern. Setzt Betrachten voraus.
• Löschen — Buchungen entfernen. Setzt Bearbeiten voraus.

Ohne Betrachten erscheint der Eintrag im Menü gar nicht. Fehlt Bearbeiten, bleiben die Schaltflächen gesperrt, und die zugehörigen Routen weisen den Aufruf ab — die Sperre in der Oberfläche ist also nicht der einzige Schutz.

Die Passwortabfrage bleibt daneben bestehen: Sie ist eine Bestätigung, keine Berechtigung, und schützt den unbeaufsichtigten Arbeitsplatz.

Für Entwickler

• Der Seitenaufbau im Kundenkonto ist abgesichert. Grafik, Treueprämien und Buchungen werden einzeln gekapselt: Schlägt einer dieser Schritte fehl, fehlt nur der betroffene Teil, die Seite bleibt erreichbar, und der Fehler landet im Protokoll unter PlugwareLoyalty.
• Rückerstattungen. Eine vollständige Rückerstattung und eine Rücklastschrift buchen die Punkte der Bestellung zurück, genau wie eine Stornierung. Abschalten lässt sich das über Punkte bei Rückerstattung zurückbuchen in der Karte Sammeln und Einlösen.

Eine Teilrückerstattung bleibt ohne Buchung. Der Statuswechsel nennt keinen Betrag, ein Anteil ließe sich daraus nur raten. Der Fall wird stattdessen im Protokoll unter PlugwareLoyalty mit Bestellnummer vermerkt; die Korrektur nehmen Sie im Reiter Konten von Hand vor.

• Doppelbuchungen sind abgesichert: je Bestellung entsteht höchstens eine Gutschrift, eine Abbuchung und eine Rückbuchung, auch bei mehrfachen Statuswechseln.
• Der Cart-Prozessor liegt auf Priorität 4000. Beim Zusammenspiel mit Rabatt-Aktionen im Testshop prüfen, ob Punkte-Rabatt und Promotion in der gewünschten Reihenfolge greifen; verschieben lässt sich das über die Priorität in services.yaml.
• Neue Einstellungen gehören an drei Stellen eingetragen: config.xml, die Liste CONFIG_GROUPS in plugware-loyalty.js und beide Sprachblöcke derselben Datei. Braucht PHP den Wert, kommt ein Leser in LoyaltyConfig dazu. Die Darstellung darf sich zwischen beiden Wegen unterscheiden, gespeichert wird dasselbe.
• Eine Karte landet über tab: in einem Reiter. Ohne Angabe erscheint sie im Reiter Einstellungen; Treueprämien und Treuestufen tragen dort ihren eigenen Wert. Neue Reiter gehören zusätzlich in die Liste CONFIG_TABS, damit die Anzeige des Speicherns dort mitläuft.
• Eigenschaften von Komponenten werden im Adminbereich mit Bindestrich übergeben, also :help-text statt :helpText. In gemischter Schreibweise kommen sie nicht an, und die Angabe fehlt kommentarlos.
• Der Elternblock wird je Bereich anders eingesetzt. Im Adminbereich gilt {% parent %}; die gewohnte Schreibweise mit doppelten geschweiften Klammern wird dort von Vue ausgewertet und ergibt einen leeren Block. In der Storefront ist es umgekehrt: dort gilt {{ parent() }}, und {% parent %} macht die Vorlage ungültig. In beiden Fällen bleibt die Seite ohne Fehlermeldung weiß. ./check.sh prüft die Storefront-Vorlagen darauf.
• Die Admin-Routen prüfen eigene Rechte (plugware_loyalty.viewer zum Lesen, plugware_loyalty.editor für Buchungen). Sie werden in der Rollenverwaltung vergeben; siehe den Abschnitt Schutz vor Manipulation.
• Controller brauchen setContainer. Storefront- und Admin-Controller werden mit public: true, dem Tag controller.service_arguments und dem Aufruf setContainer registriert. Fehlt der Aufruf, bricht Symfony mit "has no container set" ab, sobald die Route aufgerufen wird.
• Dienste und Routen liegen als YAML (services.yaml, routes.yaml). Die XML-Form ist seit symfony/dependency-injection 7.4 als veraltet gemeldet; die config.xml für die Konfigurationsmaske bleibt davon unberührt, sie gehört zu Shopware und nicht zum Dienstcontainer.
• Geprüft gegen Shopware 6.7.13.1. Die Anforderung in der composer.json lautet ~6.7.0. Alle Klassenverweise, die überschriebenen Twig-Blöcke und die genutzten Methoden der Kernkomponenten wurden gegen diese Fassung abgeglichen.
• Die Adressen der Admin-Dateien tragen eine Kennung aus Version und Prüfsumme des Inhalts, etwa plugware-loyalty.js?v=1.43.1-e43562a3. Ohne sie liefert der Browser nach einem Update die alte Datei aus dem Zwischenspeicher, und neue Felder fehlen scheinbar grundlos.

pack.sh frischt die Kennung beim Packen selbst auf. Wer zwischendurch am Adminbereich arbeitet, ruft ./stamp.sh auf. Danach genügt bin/console assets:install — ein harter Reload und ein Build sind nicht nötig. Weil die Prüfsumme am Inhalt hängt, wirkt das auch ohne Versionssprung.

• Beim Aktualisieren bleiben gelöschte Dateien liegen. Der Erweiterungs-Manager ergänzt den Ordner, statt ihn zu ersetzen. Wurde eine Datei umbenannt oder entfernt, gehört sie auf dem Server von Hand gelöscht — Shopware lädt etwa jede Datei, die auf services.* passt, und eine liegengebliebene services.xml würde neben der services.yaml mitgelesen.