Extension

Konfigurieren Sie Ihre Magento 2 Extension-Einstellungen, verwalten Sie Daten-Synchronisationsoptionen und passen Sie Such-, Recommendations- und Logging-Funktionen an. Dieser Leitfaden behandelt außerdem die Installation über das Toolbox Script, das Upgrade und die Deinstallation.

Installation mit Toolbox #

Das Clerk Toolbox Script wurde entwickelt, um es einfach zu machen, die Clerk Extension in Ihrem Magento-Webshop zu installieren, ohne Magento Connect zu benutzen.

Das Toolbox Script wird direkt aus einem Terminal ausgeführt.

Wir empfehlen diese:

- Apple: iTerm, Sie müssen es aus dem Internet herunterladen;

- Windows: Eingabeaufforderung (Command Prompt), sie ist bereits auf Ihrem Computer installiert.

Das Script erstellt außerdem ein Backup des Magento2-Ordners, sodass dieser wiederhergestellt werden kann, falls etwas schiefgeht.

Was Sie benötigen #

Um die Extension zu installieren, benötigen Sie SSH- oder SFTP-Zugang zu Ihrem Webshop, einschließlich Benutzername und Passwort.

Zum Ordner navigieren #

1. Beginnen Sie damit, sich über ein Terminal mit Ihrem Magento-Server einzuloggen, indem Sie Ihren Benutzernamen und Ihre Domain wie folgt verwenden:

ssh Stefan@mywebshop.com

2. Sie werden aufgefordert, das Passwort für Ihren Benutzer einzugeben (das Terminal gibt beim Tippen keine Rückmeldung, nimmt das Passwort aber trotzdem entgegen).

Navigieren Sie zum Root-Ordner von Magento2. Das können Sie mit folgendem Befehl tun:

cd /var/www/html

und geben Sie ein:

ls

Der Befehl ls listet die Ordner auf, sodass Sie Ihr Magento-Root-Verzeichnis finden können.

Suchen Sie in der Ordnerliste nach dem richtigen Ordner, in diesem Fall wäre es magento2.

An diesem Punkt müssen Sie in den Ordner wechseln. Das machen Sie so:

cd NAME_FOLDER

NAME_FOLDER wird durch den tatsächlichen Ordnernamen ersetzt.

Extension installieren #

1. Wenn Sie sich in Ihrem Root-Ordner befinden, laden Sie das Toolbox Script mit folgendem Befehl herunter:

sudo wget https://raw.githubusercontent.com/clerkio/clerk-magento2/master/clerk_toolbox_magento2.sh

2. Geben Sie anschließend diese Zeile ein, um eine Liste der verfügbaren Optionen im Toolbox Script zu sehen:

sh clerk_toolbox_magento2.sh

3. Da Sie die Extension installieren möchten, verwenden Sie -i zusammen mit der neusten Versionsnummer der Extension. Geben Sie Folgendes ein:

sudo sh clerk_toolbox_magento2.sh -i

4. Sie werden nun aufgefordert, Ihr Passwort einzugeben. Nachdem Sie dies getan haben, erstellt das Script ein Backup des Magento2-Ordners und beginnt mit der Installation der Extension:

5. Fertig! Die Extension ist jetzt installiert und Sie können sie im Magento2-Backend konfigurieren.

Optionale Befehle #

Deinstallation

Mit dem Toolbox Script können Sie die Extension auch deinstallieren. Geben Sie dazu diese Zeile ein:

sudo sh clerk_toolbox_magento2.sh -u

Wiederherstellung

Falls in Ihrem Webshop etwas schiefgeht, können Sie diesen jederzeit über das Backup wiederherstellen, das beim Installieren der Extension erstellt wurde.

Nutzen Sie dazu diese Zeile:

sudo sh clerk_toolbox_magento2.sh -r

Backup

Beim Installieren der Extension erstellt das Script immer zuerst ein Backup, aber Sie können auch eigenständig ein Backup mit diesem Befehl erstellen:

sudo sh clerk_toolbox_magento2.sh -b

my.clerk.io Einstellungen #

Um Ihre Magento-2-Daten-Einstellungen in Clerk zu bearbeiten, gehen Sie zu my.clerk.io, klicken Sie auf “Data” im linken Menü und gehen Sie dann zu “Configuration”.

Hinweis: Informationen zur Magento-2-Clerk-Extension, die im Magento Admin Portal verfügbar ist, finden Sie weiter unten in diesem Artikel.

Hier können Sie die URL Ihres Shops, die Seitenanzahl Ihrer Daten-Syncs sowie die Uhrzeit, zu der Ihre Daten mit Clerk synchronisiert werden, festlegen (Standard ist “bei Bedarf”).

Extension Einstellungen #

Wenn Sie die v6.7.0 oder eine neuere Version der Extension verwenden, können Sie nach dem Hinzufügen Ihrer Public und Private Keys auf die folgenden Einstellungen auf zwei Wegen zugreifen:

• Über das Magento2 Backend unter Stores > Settings > Configuration > Clerk > Configuration

• Über my.clerk.io unter Developers > Extensions

Es spielt keine Rolle, wo Sie Änderungen vornehmen, da die Extension Änderungen mit my.clerk.io synchronisiert – und umgekehrt.

In my.clerk.io können Sie auch die aktuelle Version der Extension, Ihre Plattform und die PHP-Version sehen.

Klicken Sie auf Edit bei einer Einstellung, um deren verfügbare Optionen anzuzeigen.

Übersicht #

Um auf Ihre Clerk Extension in Magento 2 zuzugreifen, melden Sie sich im Admin-Portal Ihres Webshops an und gehen Sie zu Stores > Settings > Configuration > Clerk > Configuration

Allgemein #

Im Bereich General finden Sie Ihre Clerk Extension Versionsnummer sowie die öffentlichen und privaten API-Keys Ihres Shops.

Um Pages in die Daten-Synchronisierung mit Clerk einzubeziehen, wählen Sie im nächsten Dropdown „Yes“ und geben die zusätzlichen Felder ein, die Sie mit Ihren Seiten-Daten synchronisieren möchten (z. B. Bilder oder Seitentyp), als kommagetrennte Werte.

Im letzten Dropdown in General können Sie außerdem die Standardsprache für Ihre synchronisierten Shopdaten festlegen.

Legacy Authentication #

Diese Einstellung steuert, ob die Extension JWT-Header-Authentifizierung oder die ältere Methode mit Private Key verwendet. Das Deaktivieren wird dringend empfohlen, da JWT einen sicheren, modernen Authentifizierungsfluss für alle API-Anfragen zwischen Magento 2 und Clerk.io bietet.

Store ID #

Dies ist ein veraltetes Konfigurationsfeld, das bei modernen Installationen von Clerk.io nicht mehr benötigt wird. Sie können es ignorieren, da die Extension automatisch Store-Scopes mithilfe der nativen Store- und Website-APIs von Magento identifiziert und verwaltet.

Synchronisierung #

Im Bereich Synchronization des Clerk-Plugins können Sie Ihre synchronisierten Kunden-, Bestell-, Warenkorb- und Produktdaten individuell anpassen.

Optionen sind ausgegraut und nicht bearbeitbar, wenn die Website-Daten genutzt werden (sichtbar durch das Häkchen rechts in jedem Abschnitt).

Deaktivieren Sie einfach das entsprechende Kästchen zum Bearbeiten.

• Use Real-time Updates: Wählen Sie “Yes”, um Echtzeit-Updates für Ihre mit Clerk synchronisierten Daten zu aktivieren.

Mit aktivierten Echtzeit-Updates wird der Lagerbestand nun nach Bestellungen und nach dem Speichern von Produkten im Magento-2-Admin aktualisiert.

• Collect Emails: Wählen Sie hier “Yes”, um Kunden-Emails zu synchronisieren.

• Collect Baskets: Um Warenkorb-Daten zu sammeln und mit Clerk zu synchronisieren, wählen Sie hier “Yes”.

• Wählen Sie in den nächsten beiden Dropdowns “yes”, um nur verkaufbare Produkte zu synchronisieren und/oder nur Produkte mit Sichtbarkeit zu Clerk zu synchronisieren.

• Falls Sie die Bestell-Synchronisierung deaktivieren möchten, können Sie dies tun, indem Sie “Yes” in diesem Dropdown wählen.

Additional Fields #

Eine kommagetrennte Liste zusätzlicher Produktattribute, die Sie mit Clerk.io synchronisieren möchten (z.B. color, size, material). So können Sie diese benutzerdefinierten Attribute in Ihren Clerk.io Recommendation-Designs, Suchfiltern oder E-Mail-Kampagnen verwenden.

Search Non-Indexed Attributes #

Wenn aktiviert, wird Clerk.io eine tiefere Abfrage ausführen, um Werte für benutzerdefinierte Attribute abzurufen, die nicht im Standard-Magento-Produktindex enthalten sind. So werden alle angeforderten benutzerdefinierten Felder erfolgreich synchronisiert – dies kann jedoch etwas mehr Serverressourcen beanspruchen.

Stellen Sie sich das so vor, als würde ein höflicher Assistent im staubigen Hinterzimmer Ihres Lagers nachsehen, statt sich nur den Klemmbrettzettel an der Tür durchzulesen.

Track Returned Orders #

Wenn diese Option aktiviert ist, erkennt die Extension die Erstellung von Gutschriften in Magento 2. Gutschriften synchronisieren Lagerbestandsänderungen und verfolgen zurückgesendete Artikel in Clerk.io.

Image Type #

Mit diesem Dropdown wählen Sie, welcher Magento-Bildtyp und welche Dimensionen (z.B. Basisbild, kleines Bild oder Thumbnail) an Clerk.io gesendet werden sollen. Dies ist besonders nützlich, um Bildqualität und Seitenverhältnis an das jeweilige Shop-Design anzupassen.

Kundensynchronisierung #

Aktivieren Sie die Kundendaten-Synchronisierung, indem Sie in diesem Bereich “Yes” im Dropdown wählen.

Falls Sie weitere Kundenattribute in die Clerk-Synchronisierung einbeziehen möchten, geben Sie diese als kommagetrennte Werte in das Textfeld ein.

Sync Subscribers #

Durch Aktivieren dieser Option werden die Newsletter-Abonnenten Ihres Shops mit Clerk.io synchronisiert.

Für registrierte Kunden, die auch Newsletter-Abonnenten sind, aktualisiert die Extension automatisch deren bestehendes Kundenprofil mit subscribed: true und fügt deren individuellen Abbestell-Link hinzu.

Für Gast-Abonnenten (die sich für den Newsletter angemeldet, aber kein Kundenkonto erstellt haben) synchronisiert die Extension diese als unabhängige Profile – in Clerk.io werden sie einfach durch ihre E-Mail-Adresse und ein SUB-ID-Präfix identifiziert. So wird das gesamte Zielpublikum erfasst, ohne doppelte Kundenprofile für registrierte Nutzer zu erzeugen. Das ist besonders hilfreich für umfassende E-Mail-Marketing-Audiences und personalisierte E-Mail-Kampagnen.

Search #

Aktivieren Sie die Search Page Ihres Shops, indem Sie hier „Yes“ im Dropdown wählen.

• Nach dem Aktivieren der Search Page geben Sie den Elementnamen aus dem data-template-Feld des Embed-Codes ein. Beispiel: search-page, wenn dies der Name Ihres Elements ist.

• Sie können den “Load more”- und “No results”- Text festlegen, indem Sie die gewünschte Phrase in die entsprechenden Textfelder eingeben.

Kategorien einbeziehen #

Durch Aktivieren dieser Option werden Kategorietreffer direkt auf Ihrer Haupt-Suchseite neben den Produkt-Ergebnissen angezeigt. Das hilft Ihren Kunden, sich leichter zurechtzufinden, weil relevante Kollektionen und Kategorien, die zur Suchanfrage passen, präsentiert werden.

Anzahl der Kategorien #

Legt die maximale Zahl der anzuzeigenden Kategorie-Ergebnisse auf der Suchseite fest. Bei einem Wert von 5 werden bis zu fünf passende Kategorien angezeigt, sodass Nutzer schnell zu relevanten Katalogbereichen springen können.

Anzahl der Seiten #

Legt die maximale Zahl der CMS- oder Content-Seiten-Ergebnisse fest, die auf der Suchseite angezeigt werden. Ideal, um auch Blogbeiträge, Guides oder Infoseiten (wie Rückgaberichtlinien) neben Produkten anzuzeigen.

Pages Type #

Filtert die Typen von CMS- oder Content-Seiten, die im Suchergebnis angezeigt werden sollen. Sie können nur Standard-CMS-Seiten, spezifische Blogbeiträge oder alle mit Clerk.io synchronisierten Inhaltsseiten anzeigen.

Live-Suche #

• Nachdem Sie im Dropdown “Enabled” gewählt haben, um die Live Search zu aktivieren, wählen Sie, ob Kategorien in Ihren Suchergebnissen angezeigt werden sollen.

  • Zusätzlich können Sie festlegen, wie viele Suchvorschläge, Kategorien und Content-Ergebnisse innerhalb der Live Search angezeigt werden, zusätzlich zu den Produkt-Ergebnissen.

• Sie haben auch die Möglichkeit zu wählen, welche Seitentypen als Suchergebnisse ausgegeben werden, z.B. “CMS Pages”, “Blog Posts” oder “All”.

• Sie können die Position des Live-Search-Dropdowns im Verhältnis zu Ihrem Suchfeld über Dropdown Positioning festlegen.

• Geben Sie als Nächstes den Element-Namen für Ihre Live-Suche an; diesen finden Sie neben data-template im Live Search Embed-Code Ihres my.clerk.io Elements – vermutlich „live-search“.

• Zuletzt können Sie den Live Search Input Selector und Form Selector angeben; diese finden Sie, indem Sie das Suchfeld Ihres Shops im Browser inspizieren und die zugehörige ID oder Klasse für das Input-Feld und das Formular identifizieren.

  • Für ein Eingabefeld mit der ID search verwenden Sie #search als Input Selector. Wählen Sie die geeignete Form-Selector-Option für Ihren Shop.

Facettierte Navigation #

Um Facets zu Ihrer Suchseite hinzuzufügen, wählen Sie zunächst das Kontrollkästchen “Enabled” unter Faceted Navigation.

• Klicken Sie auf die Attribute, die Sie zu Ihren Facets hinzufügen möchten, und klicken Sie auf „Save Config“.

• Nach dem Hinzufügen erscheinen Ihre hinzugefügten Attribute unter Titles. In diesem Abschnitt legen Sie fest, welcher Titel für das Facet angezeigt wird und an welcher Position in der Facettenliste sich das Attribut befinden soll.

Facets in der URL #

Wenn aktiviert, werden ausgewählte Filter (Facets) direkt als Query-Parameter an die URL angehängt. So können Kunden gefilterte Suchergebnisse als Lesezeichen speichern, aktualisieren oder mit anderen teilen, während der exakte Filterstatus erhalten bleibt.

Multiselect-Attribute #

Erlaubt Ihnen festzulegen, welche Facets die Auswahl mehrerer Optionen gleichzeitig unterstützen (z.B. gleichzeitiges Filtern nach „Rot“ und „Blau“). So wird die Filterung flexibler und benutzerfreundlicher.

Hinweis: Sie können nun Daten zu Kategorien und Seiten auf Ihrer Suchseite auf die gleiche Weise aufrufen wie bei der Live-Suche und somit ein größeres Spektrum an Informationen nutzen, um Ihre Kunden einzubinden. Mehr Informationen finden Sie hier.

Facets anpassen #

• Clerk erlaubt das Styling Ihrer Suchseiten-Facets direkt im Design, welches Sie über das Design-ID-Feld referenzieren können.

• Die Design-ID finden Sie im Clerk-Backend in der ganz linken Spalte jedes Designs auf der Design-Übersichtsseite sowie unten links, nachdem Sie das Design zur Bearbeitung geöffnet haben.

Powerstep und Exit Intent #

Ähnlich wie bei Search aktivieren Sie das Clerk Powerstep, indem Sie “Yes” im Dropdown wählen und dann den gewünschten Powerstep-Typ (Seite oder Popup) auswählen.

• Geben Sie den Powerstep-Elementnamen aus dem data-template Feld des Embed-Codes ein. Beispiel: power-step-others-also-bought, wenn dies der Name Ihres Elements ist.

• Führen Sie die gleichen Schritte für das Exit Intent durch und identifizieren und fügen Sie das entsprechende Exit Intent Element hinzu.

Powerstep Filter Duplicates #

Durch Aktivieren dieser Option verhindern Sie, dass Produkte mehrfach in verschiedenen Slidern des Powerstep empfohlen werden. Wird ein Produkt bereits in einem Slider angezeigt, filtert Clerk.io es für alle weiteren Slider auf derselben Seite automatisch heraus.

Recommendations #

Auch hier, ähnlich wie bei Search, aktivieren Sie Ihre Clerk Product-, Category- und Cart Page Settings, indem Sie “Enabled” im jeweils passenden Dropdown auswählen.

• Wie bei den Search-Funktionalitäten finden Sie den Elementnamen im Embed-Code neben data-template unter my.clerk.io > Recommendations > Elements.

  • Beispiel: Sie können Category-, Product- und Cart-Page-Settings aktivieren und category-page-popular, product-page-alternatives, product-page-others-also-bought sowie cart-others-also-bought den jeweiligen Seiten zuweisen.

Category Filter Duplicates #

Durch Aktivierung dieser Option verhindern Sie, dass auf Ihren Kategorieseiten doppelte Produkte in mehreren Slidern empfohlen werden. So erhalten Kunden eine größere Vielfalt an Produkten und sehen nicht immer dieselben Artikel in verschiedenen Abschnitten.

Product Filter Duplicates #

Durch Aktivierung dieser Option verhindern Sie, dass auf Ihren Produktdetailseiten doppelte Produkte in mehreren Slidern empfohlen werden. Damit bleiben die Recommendations frisch und erhöhen die Wahrscheinlichkeit, dass verschiedene Produkte das Interesse der Kunden wecken.

Cart Filter Duplicates #

Durch Aktivierung dieser Option verhindern Sie, dass auf der Warenkorbseite doppelte Produkte in mehreren Slidern empfohlen werden. Das ist besonders effektiv fürs Cross-Selling, da eine größere und spannendere Produktvielfalt für Last-Minute-Käufe präsentiert wird.

Denn wenn ein Kunde den neongrünen Toaster im ersten Slider schon abgelehnt hat, wird es vermutlich auch nach dreimaliger Wiederholung bis zur Kasse nicht anders sein – und der Kunde könnte sogar an der Vernunft Ihres Shops zweifeln.

Logging #

Um die Logging-Einstellungen zu ändern, öffnen Sie Stores > Configuration > Clerk > Configuration in Ihrem Magento 2 Backend.

Suchen Sie das Dropdown Logging Settings und wählen Sie Ihre bevorzugte Einstellung.

Klicken Sie auf Save, um die Änderungen zu übernehmen.

Zu den Logging-Einstellungen gehören:

Wählen Sie das Logging-Level

• Nur Fehler: Es werden nur Fehler protokolliert, die das ordnungsgemäße Funktionieren des Moduls verhindern.

• Fehler + Warnungen: Zusätzlich werden Warnungen protokolliert, die das Modul nicht stoppen, aber dennoch beachtet werden sollten.

• Fehler + Warnungen + Debug: Protokolliert alles, womit das Modul interagiert. Das sollte nicht auf einem Live-Webshop aktiviert werden, da es die Seite verlangsamt.

Wählen Sie, wo geloggt werden soll

• Datei: Speichert das Log auf dem Magento2-Server in einer Datei.

• my.clerk.io: Alle Logs werden im my.clerk.io Backend unter Developers->Logs gespeichert.

Log File Link #

Zeigt den absoluten Pfad zur lokalen Logdatei auf Ihrem Magento-Server an (typischerweise /var/log/clerk_log.log). So können Entwickler oder Administratoren das Rohlog einfach finden und zur Fehlersuche einsehen.

Upgrade #

Wenn Sie eine Version vor 3.0.0 verwenden, bricht das Upgrade Ihre Designs, da Clerk.js 2 verwendet wird. Bei älteren Versionen folgen Sie bitte stattdessen diesem Guide.

Wichtig: Denken Sie daran, Backups aller geänderten Dateien zu machen, da diese überschrieben werden.

Das Upgrade der Magento 2 Extension erfolgt über die Kommandozeile.

Das Upgrade erfolgt folgendermaßen:

1. Melden Sie sich per Kommandozeile an Ihrem Server an.

2. Navigieren Sie in Ihren Webroot-Ordner (meistens " /var/www/your_domain/public_html")

3. Aktivieren Sie Root Access, indem Sie su tippen und dann Ihr Passwort eingeben.

4. Geben Sie folgende Befehle nacheinander ein:

   composer update clerk/magento2

   php bin/magento setup:upgrade

   php bin/magento setup:di:compile

5. Warten Sie, bis die Extension die Aktualisierung abgeschlossen hat.

Ihr Magento 2 ist nun auf die neueste Version aktualisiert.

Deinstallation #

Die Deinstallation erfolgt – wie die Installation – per Kommandozeile in Magento 2.

Geben Sie folgende Befehle in der angegebenen Reihenfolge ein, um die Extension zu entfernen:

1. php bin/magento setup:module:disable Clerk_Clerk

2. composer remove clerk/magento2