FAQ

Haben Sie Probleme mit Ihrer Magento 2-Integration? Dieses FAQ behandelt die häufigsten Probleme und deren Lösungen, von Bildgrößen bis zu Synchronisierungsfehlern.

Bildgrößen #

Standardmäßig verwendet die Erweiterung die originalen Bildgrößen, die in Magento 2 festgelegt sind.

Diese können bei Bedarf geändert werden.

Melden Sie sich zunächst im Magento 2 Backend an und gehen Sie zu:

Unter Synchronization > Image type können Sie genau auswählen, in welcher Auflösung Bilder gesendet werden sollen:

Klicken Sie anschließend auf Save Config.

Nun müssen Sie einfach einen neuen Sync in my.clerk.io durchführen, und Ihre neuen Bildgrößen werden importiert.

Nutzung von Formatters #

Clerk.js ermöglicht es Ihnen, eigene JavaScript-Funktionen zu schreiben, die Ihren Designs neue Funktionalität hinzufügen.

Formatters können auf zwei Wegen hinzugefügt werden:

• Über my.clerk.io > Developers > Formatters, wobei jeder Formatter als eigener Eintrag erstellt werden kann.

• Als Konfiguration für Clerk.js, im tracking-script, das auf allen Seiten eingefügt wird und wo mehrere Formatters gleichzeitig hinzugefügt werden können.

Für Magento 2 enthält diese Datei das tracking-script:

vendor->view->frontend->templates->tracking.phtml

Beispiel Formatter #

Ein Beispiel ist unten zu sehen. Bitte beachten Sie, dass dies für Clerk V2 (neueste Version) ist:

    Clerk('config', {
      key: 'O7UITkJIXqXibeQF9ONobiGGKYYKtbvh',
      formatters: {
             log_price: function(price) {
             console.log(price);
    }
          }
      });

Mehrere Formatters #

Sie können beliebig viele Formatters schreiben, getrennt durch Kommas:

formatters: {
   log_price: function(price) {
      console.log(price);
   },
  calculate_discount: function(price, special_price) {
    return price - special_price;
   },
   substring: function(text) {
    var short_string = text.substring(0, 20);
      return short_string;
   }
}

Verwendung in Designs #

Nach dem Erstellen Ihrer Formatters können Sie diese in Ihren Designs mit folgender Syntax verwenden:

{% raw %}{{ price | log_price }} {{ price | calculate_discount | special_price }}{% endraw %}

Damit können Sie jede gewünschte Funktionalität in Ihren Designs erstellen.

In den Warenkorb legen mit Form Key #

Magento 2 nutzt einen form_key als CSRF-Schutz. Beim Erstellen von “In den Warenkorb”-Buttons in Clerk-Designs müssen Sie diesen form_key integrieren, damit die Warenkorb-Funktionalität funktioniert.

Das Clerk.js-Skript für Magento 2 enthält eine eingebaute globale Variable formkey, die automatisch den form_key-Wert der Seite enthält.

Verwendung im Design #

Fügen Sie in Ihrem Clerk-Design den form_key als verstecktes Feld in Ihrem Add to Cart-Formular über {{ formkey }} ein:

<form action="{{ product.url }}checkout/cart/add/product/{{ product.id }}" method="post">
    <input name="form_key" type="hidden" value="{{ formkey }}">
    <input type="hidden" name="product" value="{{ product.id }}">
    <input type="hidden" name="qty" value="1">
    <button type="submit" class="clerk-add-to-cart">Add to Cart</button>
</form>

Die globale Variable {{ formkey }} ist in der Magento 2-Erweiterung vorkonfiguriert, es ist keine zusätzliche Einrichtung erforderlich.

HTTP-Authentifizierung #

HTTP-Authentifizierung wird häufig auf Staging-Seiten verwendet, um unerwünschte Besucher fernzuhalten.

Dies blockiert den Clerk Importer und zeigt einen 401 Unauthorized-Fehler im Sync-Log an.

Sie können dies beheben, indem Sie die Authentifizierungsdaten in die Import-URL einfügen.

In my.clerk.io > Data > Configuration aktualisieren Sie Ihre Import-URL wie folgt:

http://USER:PASS@magento2.clerk.io/

Häufige Synchronisationsfehler #

Hinweis: Wir empfehlen, die Erweiterung stets auf die neueste Version zu aktualisieren, um alle aktuellen Funktionen von Clerk zu erhalten.

Beim Import von Daten mit Clerks Magento 2-Erweiterung ist Ihr Webshop-Server dafür verantwortlich, Produkt-, Kategorie- und Verkaufsdaten an Clerk zu senden.

In manchen Fällen kann jedoch die Serverkonfiguration den Zugriff auf die Daten verhindern und so einen Fehler in der Data Sync verursachen.

Im Folgenden finden Sie die häufigsten Fehler und deren Behebung.

401 Unauthorized #

Dieser Fehler tritt auf, wenn Ihr Webshop oder Ihre Entwicklerumgebung eine HTTP-Authentifizierung zum Zugriff erfordert.

Dies wird behoben, indem Sie Benutzername und Passwort als Teil der Import-URL einfügen:

http://username:password@magento2.clerk.io

403 Forbidden #

Dieser Fehler tritt häufig aus einem der folgenden Gründe auf:

• Ihr Server blockiert den Importer. In den meisten Fällen müssen Sie einfach die IP-Adresse des Importers auf die Whitelist setzen, um den Zugriff zu ermöglichen. Die aktuelle IP-Adresse finden Sie hier.

• Sie haben möglicherweise einen falschen public key, private key und/oder import URL im Shop in my.clerk.io angegeben.

• Sie verwenden Storeviews mit versteckten URLs, wie mywebshop.com?__store=b2b. Manchmal enthalten diese URLs auch drei Unterstriche wie mywebshop.com?___store=b2b.

Wenn Letzteres zutrifft, fügen Sie einfach den __store-Parameter in der URL in Data hinzu:

Was, wenn ich bereits auf die Whitelist gesetzt habe, aber der Fehler weiterhin auftritt?

Es gibt einige Fälle, in denen Sie die Importer-IP-Adresse auf die Whitelist gesetzt haben, der Fehler aber weiter besteht.

In diesen Fällen empfehlen wir, Folgendes zu überprüfen:

• Der Authentifizierungsteil des Bodys wird eventuell vom Server des Shops entfernt.

• Rate-Limitierung des Servers in Bezug auf Cloudflare.

404 Not Found #

Dieser Fehler tritt auf, wenn der Importer den Link, der die Daten vom Webshop sendet, nicht erreichen konnte.

In den meisten Fällen liegt es daran, dass die Erweiterung entweder:

• überhaupt nicht installiert ist

• ein Cache verhindert, dass der Link initialisiert wird

Stellen Sie zunächst sicher, dass Sie die Erweiterung korrekt installiert haben.

Leeren Sie anschließend den Cache Ihres Webshops, bevor Sie einen neuen Import starten.

429 Too Many Requests #

Dieser Fehler tritt auf, wenn Ihr Server dem Importer den Zugriff aufgrund zu vieler eingehender Anfragen verweigert.

Sie können dies beheben, indem Sie das Request-Limit für Ihren Server erhöhen oder die Page Size unter my.clerk.io > Data > Configuration erhöhen, sodass der Importer weniger, aber größere Anfragen stellt:

Wenn Sie den Hosting-Anbieter hypernode.com/nl nutzen, tritt dieser Fehler beim Importer meist wegen des dortigen Rate-Limiters auf. In diesem Fall wenden Sie sich an hypernode.com/nl und bitten Sie darum, den User-Agent des Importers “clerk” auf die Whitelist zu setzen.

500 Internal Server Error #

Dieser Fehler bedeutet, dass Ihr Server auf einen internen Fehler gestoßen ist und nicht angeben konnte, welcher Fehler aufgetreten ist.

Prüfen Sie in diesen Fällen Ihr Server Log, um herauszufinden, welcher Prozess abgestürzt ist und warum.

In den meisten Fällen liegt es einfach an einem Produkt mit einem ungültigen Attribut oder einer falsch aufgerufenen Funktion im Webshop.

503 Service Unavailable #

Dieser Fehler ist in der Regel vorübergehend und wird dadurch verursacht, dass der Server zu stark ausgelastet ist, um die Anfrage zu verarbeiten.

Versuchen Sie es später erneut.

Falls das Problem weiterhin auftritt, kann es bedeuten, dass der Server mit Prozessen überlastet ist und sich an der Kapazitätsgrenze befindet.

Prüfen Sie die Serverauslastung, um festzustellen, ob dies der Fall ist.

Ungültige Antwort #

Dieser Fehler tritt meist auf, wenn Ihr Webshop ein Umleitungssystem nutzt, das Kunden auf verschiedene Domains leitet.

Zum Beispiel kann “ https://mywebshop.com” auf “ https://mywebshop.com/it" weiterleiten.

In diesem Fall müssen Sie beim Import in my.clerk.io einfach die vollständige URL verwenden:

MSI-Lagerbestand importieren #

Wenn Ihr Magento 2-Shop MSI (Multi-Source Inventory) nutzt, können Sie den Gesamtbestand aller Quellen in Clerk importieren, indem Sie den folgenden Attribut-Code zu den Additional Fields der Erweiterung hinzufügen.

1. Gehen Sie im Magento Admin zu Stores > Configuration > Clerk > Configuration.

2. Unter Synchronization > Additional Fields fügen Sie hinzu: multi_source_stock.

3. Klicken Sie auf Save Config und führen Sie dann einen neuen Sync in my.clerk.io > Data durch.

Clerk importiert multi_source_stock als Summe der Mengen über alle MSI-Quellen hinweg.

Das ist nützlich, wenn die Standard-Lagerquelle auf 0 steht, Produkte aber noch in anderen Quellen auf Lager sind.

Upgrade zu Clerk.js 2 #

Clerk.js 2 ist eine schnellere und flexiblere Version unserer JavaScript-Bibliothek.

Sie erleichtert die Installation von Clerk auf jedem Webshop.

Da die beiden Versionen jedoch leicht unterschiedlich funktionieren, müssen Sie folgende Schritte ausführen, um erfolgreich zu aktualisieren.

Die beiden Hauptunterschiede in Clerk.js 2 sind, dass die Designs in my.clerk.io die Liquid Template-Sprache nutzen, aber auch einfach mit dem Design Editor erstellt werden können.

Designs erstellen #

Da Clerk.js 2 einen anderen Ansatz für Designs verfolgt, müssen Sie neue erstellen.

Sie können Ihre Clerk.js 2 Designs auf zwei Arten erstellen:

• Verwenden Sie den intuitiven Design Editor, um neue Designs zu erstellen, wie in den folgenden Punkten beschrieben.

• Konvertieren Sie Ihre alten Designs. Folgen Sie dieser Anleitung, um zu sehen, wie das funktioniert.

Option Design Editor #

1. Gehen Sie zu my.clerk.io > Recommendations/Search > Designs > New Design.

2. Geben Sie auf dem folgenden Bildschirm Ihrem Design einen Namen (wir empfehlen, “V2” hinzuzufügen, damit klar ist, dass Sie Clerk.js 2 verwenden).

3. Wählen Sie den Design-Typ.

4. Bearbeiten Sie im Design Editor beliebige vorhandene Elemente wie Name, Bild, Button usw., oder fügen Sie neue Elemente zum Design hinzu, um mehr Informationen über Produkte einzubinden.

5. Klicken Sie auf Publish, wenn Sie fertig sind, und fahren Sie mit Schritt 2 in der Anleitung fort.

6. Gehen Sie zu Recommendations/Search > Elements und ändern Sie Ihr Clerk-Element, damit es Ihr neues Design verwendet.

7. Klicken Sie auf Update Element. Dies führt dazu, dass es vorübergehend nicht in Ihrem Webshop angezeigt wird, bis Sie mit Schritt 2 fertig sind. Wählen Sie das neue Design für alle Elemente aus, die aktualisiert werden sollen.

Jetzt sind Sie bereit, auf Clerk.js 2 umzusteigen.

Erweiterung aktualisieren #

WARNUNG: Denken Sie daran, Backups aller modifizierten Dateien zu erstellen, da diese überschrieben werden!

Das Upgrade der Magento 2-Erweiterung erfolgt über die Kommandozeile.

Folgen Sie dazu diesen Schritten:

1. Melden Sie sich über die Kommandozeile auf Ihrem Server an.

2. Wechseln Sie in Ihr Webroot-Verzeichnis (in der Regel _/var/www/your_domain/public_html_).

3. Aktivieren Sie den Root-Zugang durch Eingabe von su und Ihr Passwort.

4. Geben Sie die folgenden Befehle der Reihe nach ein:

composer update clerk/magento2
php bin/magento setup:upgrade
php bin/magento setup:di:compile

5. Warten Sie, bis die Erweiterung fertig ist.

Ihr Magento 2 ist nun auf die neueste Version aktualisiert.

Sie haben jetzt die neuste Version von Clerk für Magento 2 installiert und Clerk.js 2 läuft in Ihrem Webshop!

Die vollständige Dokumentation zu Clerk.js 2 finden Sie hier:

https://docs.clerk.io/docs/clerkjs-quick-start

Umgang mit require.js #

Diese Anleitung gilt nur für Versionen bis v.2.8.3 der Magento 2 Clerk-Erweiterung.

In manchen Setups verhindert Require.js das Laden von Clerk.js, sodass keine Slider oder Suchergebnisse angezeigt werden.

Wenn dies passiert, wird folgender Fehler in Ihrer Konsole angezeigt:

Uncaught ReferenceError: Clerk is not defined

Die Magento 2-Erweiterung berücksichtigt bereits Require.js, aber in manchen Fällen ist es notwendig, dass Require.js Clerk.js ignoriert.

Dies können Sie in folgender Datei einstellen:

vendor->clerk->magento2->templates->tracking.phtml

Fügen Sie einfach window.__clerk_ignore_requirejs = true; am Anfang des Tracking-Skripts ein:

Nach dieser Anpassung ist Require.js nun mit Clerk kompatibel.