FAQ

Probleme bei der Integration von Magento 2? In diesem FAQ werden die häufigsten Probleme und deren Lösungen behandelt, von Bildgrößen bis zu Synchronisierungsfehlern.

Bildgrößen #

Standardmäßig verwendet die Erweiterung die in Magento 2 eingestellten Originalbildgrößen.

Diese können bei Bedarf geändert werden.

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

Unter Synchronization > Image type wählen Sie die Bildauflösung, die an Clerk gesendet werden soll.

Anschließend klicken Sie auf Save Config.

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

Verwendung von Formatters #

Clerk.js ermöglicht Ihnen, eigene JavaScript-Funktionen zu schreiben, die neuen Funktionen zu Ihren Designs hinzufügen.

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

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

• Als Konfiguration für Clerk.js im tracking-script, das auf allen Seiten eingefügt ist, sodass mehrere Formatter 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 Formatter #

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 #

Nachdem Sie Ihre Formatters erstellt haben, können Sie diese in Ihren Designs mit folgendem Syntax verwenden:

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

So lässt sich jede gewünschte Funktionalität in Ihren Designs abbilden.

Add to Cart mit Form Key #

Magento 2 verwendet einen form_key zum Schutz vor CSRF. Beim Erstellen von Add-to-Cart-Buttons in Clerk Designs müssen Sie diesen form_key einfügen, damit der Warenkorb funktioniert.

Das Clerk.js-Script für Magento 2 enthält eine integrierte formkey-Globale Variable, die automatisch den form_key-Wert der Seite erhält.

Verwendung im Design #

Fügen Sie in Ihrem Clerk Design den form_key als hidden input in Ihr Add-to-Cart-Formular mit {{ 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 {{ formkey }}-Variable ist in der Magento 2-Erweiterung vorkonfiguriert, es ist keine weitere Einrichtung notwendig.

HTTP-Authentifizierung #

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

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

Sie können das 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 Synchronisierungsfehler #

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

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

In einigen Fällen kann jedoch die Serverkonfiguration den Import blockieren und einen Fehler in Data Sync verursachen.

Unten finden Sie eine Liste der häufigsten Fehler sowie deren Lösungen.

401 Unauthorized #

Dieser Fehler tritt auf, wenn Ihr Webshop oder Ihre Entwicklungsumgebung eine HTTP-Authentifizierung für den Zugriff erfordert.

Lösen Sie dies, indem Sie den Benutzernamen und das Passwort in der Import-URL eintragen:

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

403 Forbidden #

Dieser Fehler tritt häufig aus folgenden Gründen auf:

• Ihr Server blockiert den Zugriff des Importers. In den meisten Fällen genügt es, die IP-Adresse des Importers auf die Whitelist zu setzen. Die aktuelle IP-Adresse finden Sie hier.

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

• Sie verwenden Storeviews mit versteckten URLs, wie mywebshop.com?__store=b2b. Solche URLs können manchmal auch drei Unterstriche enthalten, wie z.B. mywebshop.com?___store=b2b.

Wenn Ihr Storeview eine versteckte URL nutzt, fügen Sie dessen __store-Parameter in der Import-URL unter Data > Configuration hinzu.

Was, wenn ich bereits whiteliste, aber der Fehler weiterhin auftritt?

In wenigen Fällen bleibt der Fehler auch nach dem Whitelisting bestehen.

Wir empfehlen, in diesen Fällen Folgendes zu prüfen:

• Der Authentifizierungs-Teil im Body könnte durch den Shop-Server entfernt werden.

• Rate Limit des Servers bezüglich Cloudflare.

404 Not Found #

Dieser Fehler tritt auf, wenn der Importer den Link, der Daten aus Ihrem Shop liefert, nicht erreichen kann.

In den meisten Fällen passiert das, weil die Erweiterung entweder:

• gar 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 Shops, bevor Sie einen neuen Import versuchen.

429 Too Many Requests #

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

Sie können dies beheben, indem Sie das Anfrage-Limit Ihres Servers erhöhen oder die Page Size unter my.clerk.io > Data > Configuration auf einen höheren Wert setzen. Eine größere Page Size bewirkt, dass der Importer weniger, dafür größere Anfragen sendet.

Wenn Sie den Hostinganbieter hypernode.com/nl nutzen, gibt der Importer diesen Fehler in der Regel wegen ihres Rate Limiters zurück. In diesem Fall kontaktieren Sie bitte hypernode.com/nl und bitten diese, den User-Agent des Importers “clerk” auf die Whitelist zu setzen.

500 Internal Server Error #

Dieser Fehler bedeutet, dass Ihr Server einen internen Fehler festgestellt hat und nicht genau sagen kann, woran es liegt.

In diesen Fällen schauen Sie bitte ins Server Log, um zu identifizieren, welcher Prozess abgebrochen ist und warum.

Meistens ist der Grund ein Produkt mit einem ungültigen Attribut oder eine falsch aufgerufene Funktion im Shop.

503 Service Unavailable #

Dieser Fehler ist meist temporär und tritt auf, weil der Server zu beschäftigt ist, um die Anfrage zu bearbeiten.

Versuchen Sie es später erneut.

Falls das Problem weiterhin auftritt, könnte der Server durch zu viele Prozesse überlastet sein und an seine Kapazitätsgrenze stoßen.

Prüfen Sie die Server-Auslastung, um dies zu verifizieren.

Ungültige Antwort #

Dieser Fehler tritt meist dann auf, wenn Ihr Shop ein Redirect-System verwendet, um Kunden auf unterschiedliche Domains umzuleiten.

Zum Beispiel leitet “ https://mywebshop.com” möglicherweise auf “ https://mywebshop.com/it" weiter.

Wenn Ihr Shop auf eine sprachspezifische Domain oder einen Pfad umleitet, verwenden Sie unbedingt diese Ziel-URL als Import-URL in my.clerk.io.

MSI-Bestandsimport #

Wenn Ihr Magento 2 Store MSI (Multi-Source Inventory) verwendet, können Sie den Gesamtbestand über alle Quellen hinweg in Clerk importieren, indem Sie den unten genannten Attribut-Code in die zusätzlichen Felder der Erweiterung aufnehmen.

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

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

3. Klicken Sie auf Save Config und führen Sie anschließend einen neuen Sync in my.clerk.io > Data aus.

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

Dies ist hilfreich, wenn die Standard-Quelle 0 aufweist, aber Produkte in anderen Quellen noch vorrätig sind.

Upgrade auf 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 sich die beiden Versionen jedoch leicht unterscheiden, müssen Sie die folgenden Schritte befolgen, um erfolgreich zu upgraden.

Die zwei 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 Designs anlegen.

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 erfahren, wie das funktioniert.

Option Design Editor #

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

2. Geben Sie in der folgenden Ansicht Ihrem Design einen Name (wir empfehlen, “V2” anzuhängen, damit sofort klar ist, dass Sie Clerk.js 2 nutzen).

3. Wählen Sie den Design-Typ.

4. Im Design Editor können Sie jedes vorhandene Element wie den Namen, das Bild, den Button etc. anklicken, um es zu bearbeiten oder neue Elemente hinzufügen, um weitere Produktinfos abzubilden.

5. Klicken Sie auf Publish, wenn Sie fertig sind, und gehen Sie zu Schritt 2 in der Anleitung.

6. Gehen Sie zu Recommendations/Search > Elements und ändern Sie Ihr Clerk Element so, dass Ihr neues Design verwendet wird.

7. Klicken Sie auf Update Element. Dadurch werden die Elemente vorübergehend nicht im Webshop angezeigt, bis Sie mit Schritt 2 fertig sind. Wählen Sie für alle zu aktualisierenden Elemente das neue Design.

Sie sind nun bereit, vollständig auf Clerk.js 2 umzusteigen.

Erweiterung upgraden #

WARNUNG: Sichern Sie unbedingt alle geänderten Dateien, da diese überschrieben werden.

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

Gehen Sie dazu wie folgt vor:

1. Melden Sie sich über die Kommandozeile am Server an.

2. Navigieren Sie in das Webroot-Verzeichnis Ihres Shops (in der Regel _/var/www/your_domain/public_html_).

3. Aktivieren Sie Root-Zugriff mit su und geben Sie Ihr Passwort ein.

4. Geben Sie die folgenden Befehle in dieser Reihenfolge ein:

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

5. Warten Sie, bis die Erweiterung fertig installiert ist.

Ihr Magento 2 ist nun auf dem neuesten Stand.

Jetzt haben Sie die neueste Clerk-Version für Magento 2 installiert und Clerk.js 2 läuft in Ihrem Shop!

Die vollständige Dokumentation für Clerk.js 2 finden Sie hier:

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

Umgang mit require.js #

Diese Anleitung gilt nur bis Version 2.8.3 der Magento 2 Clerk Erweiterung.

In manchen Setups verhindert Require.js, dass Clerk.js geladen wird, sodass keine Slider oder Suchergebnisse angezeigt werden.

In diesem Fall erscheint im Konsolenfenster folgender Fehler:

Uncaught ReferenceError: Clerk is not defined

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

Dies können Sie in folgender Datei einstellen:

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

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

Nach dieser Anpassung ist Require.js mit Clerk kompatibel.