English Version

Zurück zur Übersicht

Newsletter Management: Storefront-Integration

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Diese Seite beschreibt, was Kunden im Twig-Storefront sehen und erleben: die Anmeldeseite, das Formular im Footer, den Double-Opt-in-Ablauf, die Seiten zum Bestätigen, Verwalten und Abmelden, die Mails des Plugins und die Verbindung zur Newsletter-Checkbox von Sylius. Für Headless-Shops gibt es dieselben Abläufe über die Shop API.

Alle Seiten sind nur für Channels erreichbar, in denen „Newsletter aktiv“ eingeschaltet ist (siehe Konfiguration). Sonst liefert die Anmeldeseite 404.

Routen

Alle Routen stehen in config/routes/shop.yaml. Der Routenname beginnt immer mit mmd_sylius_newsletter_management_plugin_shop_, in der Tabelle steht nur das Ende.

{token} ist das geheime Token der Anmeldung mit 64 Hexzeichen. Die Links in den Mails enthalten es, deshalb braucht keine der Seiten einen Login. Die Routen für die Tracking-Pixel und die Klick-Weiterleitung sind signiert und lassen sich nicht erraten.

Anmeldeseite

Die Seite /newsletter enthält folgende Felder:

Ist ein Kunde eingeloggt, füllt das Plugin E-Mail-Adresse, Vor- und Nachname aus seinem Konto vor. Ein Parameter ?email= in der URL hat Vorrang für die E-Mail-Adresse; so übergibt das Footer-Formular seine Eingabe. Ein abgesendetes Formular behält, was der Besucher getippt hat. Verknüpft wird die Anmeldung mit dem Kundenkonto nur, wenn der Eingeloggte seine eigene Adresse einträgt.

Nach dem Absenden leitet die Seite auf /newsletter zurück und zeigt eine Meldung. Die Meldung ist immer dieselbe, egal ob die Adresse neu, noch unbestätigt oder schon angemeldet ist („Wir haben Dir eine E-Mail geschickt …“). So lässt sich über das Formular nicht herausfinden, wer auf der Liste steht. Ohne Double-Opt-in lautet die Meldung stattdessen „Danke - Du erhältst den Newsletter …“. Weist eine zusätzliche Prüfung (zum Beispiel ein Spam-Schutz, siehe Erweiterbarkeit) die Anmeldung ab, erscheint eine Fehlermeldung, und nichts wird gespeichert.

Formular im Footer

Das Footer-Formular ist ein Teaser: Es besteht aus einem E-Mail-Feld und dem Button „Newsletter abonnieren“ und schickt die Adresse per GET an die Anmeldeseite. Dort gibt der Besucher Einwilligung, Namen und Kategorien an. Das Formular erscheint nur, wenn

• der Newsletter im Channel aktiv ist,
• „Anmeldeformular im Footer“ eingeschaltet ist und
• die aktuelle Seite keine Newsletter-Seite des Plugins ist (dort würde es das Formular doppeln oder direkt nach einer Bestätigung zur nächsten Anmeldung einladen).

Eingehängt ist es als Twig Hook im Footer:

Die Priorität 150 platziert das Formular zwischen dem Link-Menü des Footers (200) und der Zeile mit den Zahlungsarten (100).

Double-Opt-in-Ablauf

graph TD
    A["Anmeldung per Formular oder Shop API"] --> B{"Newsletter im Channel aktiv?"}
    B -->|"Nein"| C["404 / nicht verfügbar"]
    B -->|"Ja"| D{"Zusätzliche Prüfung lehnt ab?"}
    D -->|"Ja"| E["Fehlermeldung, nichts wird gespeichert"]
    D -->|"Nein"| F{"Adresse schon bestätigt?"}
    F -->|"Ja"| G["Mail Bereits angemeldet, nichts ändert sich"]
    F -->|"Nein"| H{"Double-Opt-in aktiv?"}
    H -->|"Ja"| I["Status ausstehend, Bestätigungsmail"]
    H -->|"Nein"| J["Status bestätigt, Willkommensmail"]
    I --> K["Klick auf den Bestätigungslink"]
    K --> L["Status bestätigt, Willkommensmail"]

Der Ablauf im Detail:

1. Anmeldung. Das Plugin legt eine Anmeldung pro E-Mail-Adresse und Channel an. Die Adresse wird kleingeschrieben und von Leerzeichen befreit. Die gewählten Kategorien werden gespeichert, nicht verfügbare ignoriert.
2. Bestätigungsmail (bei Double-Opt-in). Die Anmeldung hat den Status „Bestätigung ausstehend“. Wer sich vor der Bestätigung erneut anmeldet, bekommt die Bestätigungsmail erneut. Wer sich nach einer Abmeldung wieder anmeldet, startet von vorn: neuer Status „ausstehend“, neue Tokens, neue Bestätigung.
3. Bestätigung. Der Klick auf den Link öffnet /newsletter/confirm/{token}, setzt den Status auf „Bestätigt“ und speichert Zeitpunkt und IP-Adresse. Die Seite zeigt „Anmeldung bestätigt“. Ein zweiter Klick auf denselben Link zeigt die Seite erneut, ohne etwas zu ändern oder eine weitere Mail zu senden; ein Link, den es nicht (mehr) gibt oder der zu einer abgemeldeten Anmeldung gehört, zeigt „Link ungültig oder abgelaufen“ (Status 404) mit einem Button, um sich erneut anzumelden.
4. Willkommensmail. Sie geht nach der Bestätigung raus, bei ausgeschaltetem Double-Opt-in direkt bei der Anmeldung.

Mails, die das öffentliche Formular auslöst, sind pro Anmeldung gedrosselt: Zwischen zwei solchen Mails an dieselbe Adresse liegen mindestens 10 Minuten. Das verhindert, dass jemand über das Formular das Postfach eines Fremden flutet. Die Willkommensmail direkt nach dem Klick auf den Bestätigungslink ist davon ausgenommen. Scheitert der Versand einer Mail, bleibt die Anmeldung trotzdem gespeichert, und der Fehler wird ohne E-Mail-Adresse protokolliert.

Seite „Anmeldung verwalten“

Der Link steckt in der Willkommens- und der „Bereits angemeldet“-Mail sowie im Fuß jedes Newsletters. Die Seite ist nur für bestätigte Anmeldungen erreichbar, alle anderen Tokens zeigen „Link ungültig“. Kunden ändern hier:

• Vor- und Nachname,
• die gewählten Kategorien und
• im Tracking-Modus „Personenbezogen“ die freiwillige Tracking-Einwilligung. Der Widerruf löscht die einzelnen Tracking-Daten dieses Abonnenten sofort.

Die E-Mail-Adresse wird angezeigt, ist aber nicht änderbar. Sie ist die Grundlage des Einwilligungsnachweises, der Bestätigung und der Verknüpfung mit dem Kundenkonto. Wer eine andere Adresse verwenden möchte, meldet sich ab und mit der neuen Adresse neu an.

Abmelden

Der Abmeldelink öffnet /newsletter/unsubscribe/{token} und zeigt nur eine Frage mit dem Button „Abmelden“. Erst der Klick auf den Button (ein POST) meldet ab. Das ist Absicht: Mailprogramme und Sicherheitsscanner rufen Links in Mails vorab ab, und das darf niemanden abmelden.

Die Abmeldung

• setzt den Status auf „Abgemeldet“ und speichert den Zeitpunkt,
• widerruft eine Tracking-Einwilligung und löscht die einzelnen Tracking-Daten und
• zählt als Abmeldung des Newsletters, aus dem der Link stammt, wenn der Link aus einem Newsletter kommt.

Die Seite danach lautet „Du wurdest abgemeldet“. Wer sich später wieder anmeldet, durchläuft den Ablauf von vorn. Der Link im Header List-Unsubscribe der Newsletter zeigt auf dieselbe Route.

„Bereits angemeldet“-Mail

Meldet jemand über das öffentliche Formular eine Adresse an, die schon bestätigt ist, ändert sich nichts an der Anmeldung: weder Kategorien noch Namen. Die Seite antwortet wie bei einer neuen Adresse. Stattdessen bekommt der Inhaber der Adresse die Mail „Du bist bereits für den Newsletter von {Channel-Name} angemeldet“ mit den Links zum Verwalten und Abmelden. Sie unterliegt der Drosselung von 10 Minuten.

Newsletter-Checkbox von Sylius

Sylius bringt im Registrierungsformular und auf der Profilseite eine eigene Newsletter-Checkbox mit, die nur ein Feld am Kunden setzt. Das Plugin macht daraus eine echte Anmeldung mit Double-Opt-in:

• Registrierung und Profil. Haken Kunden die Checkbox an, legt das Plugin eine Anmeldung mit der Quelle „Registrierung“ an. Bei Double-Opt-in bekommt der Kunde die Bestätigungsmail, und das Sylius-Feld wird auf „nicht angemeldet“ zurückgesetzt, bis der Link geklickt wurde.
• Nur echtes Ankreuzen zählt. Beim Profil-Update wird nur der Wechsel von „aus“ auf „an“ ausgewertet. Ein Bestandskunde, dessen Feld schon „an“ war (Altdaten, Import), verliert es nicht und bekommt keine Mail, nur weil er seine Telefonnummer ändert.
• Speichern durch einen Administrator wird ignoriert. Es ist keine Einwilligung des Kunden.
• Newsletter im Channel aus: Das Plugin lässt das Sylius-Feld unverändert.

Danach hält das Plugin das Feld synchron: Es steht auf „angemeldet“, sobald der Kunde (nach der E-Mail-Adresse zugeordnet) in irgendeinem Channel bestätigt ist, und auf „nicht angemeldet“ nach einer Abmeldung, solange er nirgends bestätigt ist. Eine unbestätigte Anmeldung aus einem anderen Weg (etwa dem Footer-Formular) fasst das Feld nicht an, weil sie auch von einem Fremden stammen kann, der die Adresse nur kennt.

Die Shop API von Sylius zur Registrierung (POST /shop/customers) setzt das Sylius-Feld, ohne dass das Plugin davon erfährt. Headless-Clients melden Kunden deshalb über den Endpunkt des Plugins an (siehe Shop API).

Gespeicherter Einwilligungsnachweis

Pro Anmeldung speichert das Plugin, was du im Streitfall zeigen musst. Im Admin siehst du es auf der Detailseite des Abonnenten.

Wie lange abgemeldete und nie bestätigte Anmeldungen aufbewahrt werden, legst du pro Channel fest (siehe Konfiguration).

Mails an Abonnenten

Die drei Mails laufen über den Mailer von Sylius (Mail-Codes unter sylius_mailer.emails). Sie sind HTML-Mails auf Basis des Sylius-Mail-Layouts und kommen in der Sprache der Anmeldung. Den Absender legst du pro Channel fest (siehe Konfiguration). Die Newsletter selbst sind ein eigener Mailweg und stehen auf der Seite Newsletter schreiben und versenden.

Der Button in allen drei Mails kommt aus dem Partial emails/_cta.html.twig. Seine Farben stellst du in der Konfigurationsdatei ein (siehe Konfiguration).

Templates im eigenen Theme anpassen

Alle Templates des Plugins liegen im Namensraum @MmdSyliusNewsletterManagementPlugin. Du überschreibst sie wie bei jedem Symfony-Bundle, indem du eine Datei mit demselben Pfad unter templates/bundles/MmdSyliusNewsletterManagementPlugin/ anlegst. Praktisch sinnvoll sind diese:

Die Seiten erweitern @SyliusShop/shared/layout/base.html.twig und füllen dessen Block content. Die Mails erweitern @SyliusCore/Email/layout.html.twig.

Ersetzt dein Theme das Footer-Template von Sylius, ohne den Hook sylius_shop.base.footer.content zu rendern, erscheint das Teaser-Formular nicht. Verlinke dann auf /newsletter.

Auf der Anmeldeseite rendert das Plugin nach der Einwilligungs-Checkbox und vor dem Absenden-Button noch den Hook mmd_altcha.widget.newsletter, in den das ALTCHA-Plugin sein Widget einhängt. Ohne dieses Plugin bleibt der Hook leer. Wie andere Plugins das Formular erweitern, steht auf der Seite Erweiterbarkeit.