Jeder (Webshop)

FAQ

Antworten auf häufig gestellte Fragen zu benutzerdefinierten Integrationen

Stoßen Sie auf Probleme mit Ihrer benutzerdefinierten Integration? Diese FAQ behandelt die häufigsten Probleme und deren Lösungen – von Single-Page-Apps bis hin zur Nachverfolgung von Verkäufen.

Single-Page-Apps #

Diese werden auch Progressive Web Apps (PWA) genannt und laden die Website in der Regel als einzelne Seite, anstatt einzelne Seiten wie gewöhnlich zu laden.

Wenn eine Seite zum ersten Mal geladen wird, löst die Clerk.js-Bibliothek automatisch eine Funktion aus, um alle Element-Blöcke auf dieser Seite zu rendern.

Bei Single-Page-Apps, die Frameworks wie vue.js oder next.js nutzen, werden Seiten jedoch mit JavaScript statt durch einen normalen Seitenaufruf gerendert.

Daher müssen Sie die Darstellung mit Clerk.js steuern, um sie an die Art des Ladens der Seiten in der App anzupassen.

Clerk.js einbinden #

Clerk.js muss nur einmal geladen werden, wenn die Website initial geladen wird.

Danach steht die Bibliothek während der gesamten Sitzung zur Verfügung.

Fügen Sie sie direkt vor dem </head> in Ihr HTML ein:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
    (function(w,d){
    var e=d.createElement('script');e.type='text/javascript';e.async=true;
    e.src='https://cdn.clerk.io/clerk.js';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
    w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){w.__clerk_q.push(arguments)};
    })(window,document);

    Clerk('config', {
    key: 'INSERT_PUBLIC_API_KEY'
    });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Rendering steuern #

Standardmäßig rendert Clerk.js alle Elemente mit der Klasse clerk, unabhängig davon, ob sie beim initialen Seitenladen oder bei einer DOM-Änderung eingefügt werden.

Sie können das Timing steuern, indem Sie das Element erst einfügen, wenn es bereit zum Rendern ist.

Alternativ können Sie das Rendering mit der Funktion Clerk("content", "SELECTOR") steuern.

Jedes Mal, wenn eine Seite geladen wird, führen Sie diese Schritte der Reihe nach aus:

Fügen Sie das Clerk-Snippet mit einem eindeutigen Selektor in das HTML ein, den Sie ansprechen können.
Führen Sie Clerk("content", "SELECTOR") aus, um das Element zu rendern.

Wenn der Besucher die Seite verlässt, entfernen Sie das Snippet und rendern es erneut, wenn der Besucher auf dieselbe Seite zurückkehrt.

Dies stellt sicher, dass Clerk.js das Snippet nicht als bereits gerendert betrachtet und es somit nicht visualisiert.

Beispiel:

<span 
  id="clerk-custom-snippet"
  data-template="@home-page-visitor-recommendations">
</span>

<script>
  Clerk("content", "#clerk-custom-snippet")
</script>

Clerk.js kann zudem automatisch Elemente initialisieren, die Sie mit eigenen Selektoren versehen, nachdem Sie es zum ersten Mal gerendert haben.

Impact auf die Pagespeed #

Das Hinzufügen eines externen Tools wie Clerk.js erhöht die Ladezeit Ihrer Website, aber dies ist vernachlässigbar im Vergleich zu den zusätzlichen Conversions, die dadurch generiert werden.

Im folgenden Abschnitt wird erklärt, was Clerk.js zum Laden der Seite beiträgt.

Performance #

Die Clerk.js-Bibliothek ist nur 37,5 kB groß und wird dementsprechend sehr schnell geladen.

Außerdem lädt sie Elemente asynchron, wodurch der Rest der Seite geladen wird, während Clerk.js Inhalte rendert.

Ein Anstieg der Ladezeit entsteht meist dadurch, dass mehr Bilder als zuvor geladen werden, da die Suchergebnisse und Empfehlungen von Clerk am besten funktionieren, wenn sie visuell ansprechend sind.

Um die zusätzliche Ladezeit zu minimieren, empfehlen wir Bilder im webp Format zu verwenden, deren Auflösung mit der in den Clerk-Elementen angezeigten Größe übereinstimmt.

Zum Beispiel: Wenn die Bilder in Empfehlungen im Desktop-View eine Auflösung von 400x400px haben, senden Sie Bilder in einer maximalen Auflösung von 420x420px oder ähnlich.

Google Page Speed #

Wenn Sie Google Page Speed Insights oder ein ähnliches Tool zur Analyse der Website-Performance nutzen, kann es sein, dass Clerk.js unter Leverage browser caching. aufgeführt wird.

Der Zweck von Clerk.js ist es, das Einfügen von Ergebnissen von Clerk in jede Website extrem einfach zu machen.

Clerk.js enthält viele Funktionen zur Handhabung von Tracking und UI-Komponenten wie Instant Search, Slider, Popups und mehr.

Wenn wir neue UI-Features hinzufügen oder bestehende verbessern, werden sie in Clerk.js aufgenommen und müssen vom Endnutzer heruntergeladen werden, um sie nutzen zu können.

Eine Cache-Verfallszeit von 60 Minuten bedeutet, dass neue Features allen Nutzern innerhalb von maximal 60 Minuten zur Verfügung stehen.

Je länger die Cache-Zeit, desto länger dauert es, bis alle Nutzer Zugriff auf neue Funktionen haben.

Wichtig ist, dass Endnutzer Clerk.js nur einmal herunterladen müssen, wenn neue Funktionen verfügbar sind.

Die 60-minütige Cache-Gültigkeit bedeutet lediglich, dass der Browser des Endnutzers alle 60 Minuten bei Clerk nachfragt.

Wenn sich an Clerk.js nichts geändert hat, wird nichts erneut heruntergeladen.

Die Cache-Gültigkeit von 60 Minuten ist also ein Kompromiss zwischen der Minimierung von Webanfragen und der Darstellung neuer Funktionen und Verbesserungen.

Die meisten Sitzungen sind kürzer als 60 Minuten, sodass die Anfrage meist nur einmal pro Sitzung erfolgt.

Eine solche Cache-Gültigkeit ist normal und wird z. B. auch von Google Analytics, Facebook und Trustpilot genutzt.

CLS-Auswirkung #

Cumulative Layout Shift (CLS) kann sich negativ auf SEO und die Benutzererfahrung auswirken, wenn dynamisch eingefügter Inhalt Elemente auf einer Seite verschiebt.

In manchen Fällen kann Clerk – neben anderen Faktoren – zum CLS-Score beitragen.

Lesen Sie mehr über CLS hier.

Folgen Sie dieser Anleitung nur, wenn Ihr CLS-Score über 0,2 liegt und Clerk-Elemente im sichtbaren Bereich erscheinen.

Um ein Verschieben von Inhalten zu verhindern, sollte ein Platzhalter für Clerk-Empfehlungen reserviert werden, bevor Clerk.js diese einfügt.

Fügen Sie dazu eine Mindesthöhe entsprechend der erwarteten Inhaltshöhe hinzu.

Beispielcode:

.clerk-slider-wrapper {
    min-height: 300px; /* Passen Sie die erwartete Inhaltshöhe an */
    width: 100%;
}

API-Calls durchführen #

Sie können Clerk.js verwenden, um API-Calls durchzuführen, indem Sie die eingebaute Funktion Clerk("call") nutzen.

Diese Funktion nimmt drei Argumente entgegen:

Einen API-Endpunkt
Ein JSON-Dictionary mit Parametern
Eine Callback-Funktion zur Verarbeitung der Antwort

Requests #

Unten finden Sie ein Beispielskript, das die 10 beliebtesten Produkte abfragt und die Antwort in der Konsole ausgibt.

Die Antwort enthält ein JavaScript-Objekt mit dem Status des API-Calls und dem Ergebnis.

Skript #

function popularProducts(){
  Clerk("call",
    "recommendations/popular",
    {
      limit: 10,
      labels:["Home Page / Bestsellers"]
    },
    function(response){
      console.log(response);
    },
    function(response){
      console.error(response);
    }
  );
}

Antwort #

__clerk_cb_1(
  {
    "status":"ok",
    "count":72,
    "facets":null,
    "result":[399,410,551,338,403,439,425,402,406,456]
  }
);

Callbacks #

Wenn Sie API-Calls durchführen, können Sie Callback-Funktionen verwenden, um die Antwort beliebig zu verarbeiten.

Die Funktionen nehmen response als Argument, das alle von der API zurückgegebenen Daten enthält.

Unten ein Beispiel, das eine Liste von HTML-Elementen erstellt, die auf Kategorien verlinken, die zu der Suchanfrage “men” passen.

Clerk("call",
  "search/categories",
  {
      'query': "men",
      'limit': "10"
  },
  function(response) {
      var cat = response.categories;
      if (cat.length > 0) {
          let heading = document.createElement('h3');
          heading.textContent = 'Related Categories';
          document.querySelector('#your-target').append(heading);
      }
      for (var index in cat) {
          var clerkName = cat[index].name;
          var clerkUrl = cat[index].url;
          let link = document.createElement('a');
          link.href = clerkUrl;
          link.textContent = clerkName;
          document.querySelector('#your-target').append(link);
      }
  }
)

Add-to-Cart-Buttons #

Diese Buttons funktionieren je nach Plattform unterschiedlich und die Funktionalität kann sich je nach verwendeten Plugins ändern.

Da die Designs von Clerk aus HTML & CSS bestehen, können Sie die Funktionalität in der Regel hinzufügen, wenn Sie wissen, wie sie auf Ihrer Seite funktioniert.

Allgemeine Vorgehensweise #

Einige Add-to-Cart-Buttons erfordern für ihre Funktion JavaScript.

In diesen Fällen können Sie die Funktion in die bestehende cart-Methode von Clerk integrieren.

Lesen Sie, wie Sie das tun, in unserer Entwicklerdokumentation hier.

Untersuchen Sie den Add-to-Cart-Button, um den zugehörigen Code zu finden, z. B. auf einer Kategorieseite.

Der Code ist meist ein <div> oder ein button Element.

Kopieren Sie das gesamte Button-HTML.

Fügen Sie diesen Code in Ihr Design ein.

Nun müssen Sie die Variablen im Code identifizieren.

Meistens müssen Sie finden, wo der Code folgende Werte nutzt:

Produkt-ID
Produktmenge

Ersetzen Sie die Werte für die Produkt-ID durch die Liquid-Variablen für diese Datenpunkte.

Die ID wird immer {{ product.id }} sein, und die Menge hängt davon ab, wie Sie die Daten übermitteln.

In diesem Beispiel könnte es {{ product.qty }} sein.

Fügen Sie Ihren Code in das HTML Ihres Designs ein und testen Sie, ob es funktioniert.

Beispiel #

Der Add-to-Cart-Button nutzt ein <div> mit der Klasse button-container.

Die Menge findet sich im Warenkorb-Link nach /cart?add= und die Produkt-ID direkt nach &id_product=.

Die Produkt-ID ist zudem in data-id-product referenziert und die Produktmenge in .data-minimal_quantity.

Diese Werte sollten im Design durch Liquid-Tags ersetzt werden, damit beim HTML-Output die passenden Produkt-IDs und Mengen genutzt werden.

Nach diesen Änderungen sieht der finale Add-to-Cart-Button wie folgt aus:

<div class="button-container">
  <a 
    class="button ajax_add_to_cart_button btn btn-default" 
    style="position: relative;" 
    href="https://www.examplelinktocart.com/cart?add={{ product.qty }}&amp;id_product={{ product.id }}&amp;" 
    rel="nofollow" 
    title="Add to Cart" 
    data-id-product-attribute="0" 
    data-id-product="{{ product.id }}" 
    data-minimal_quantity="{{ product.qty }}">
    <span style="color: orange !important">
      <i class="icon-shopping-cart" aria-hidden="true"></i>
    </span>
  </a>
</div>

Konsolenfehler #

Clerk.js loggt viele Fehler in die Konsole, die Sie zur Fehlerbehebung nutzen können.

Wenn Sie auf den Fehlerlink klicken, erhalten Sie weitere Informationen darüber, was schiefgelaufen ist. Diese können Sie zur Eigenrecherche nutzen oder an unser Support-Team senden, das Ihnen weiterhilft.

Nachfolgend finden Sie eine Liste der häufigsten Fehler.

Unbekannter Inhalt #

Dieser Fehler erscheint, wenn das von Ihnen eingefügte Snippet auf ein Element verweist, das im data-template-Attribut nicht existiert.

Um das zu beheben, stellen Sie sicher, dass der Name im Embed-Code mit einem von Ihnen in my.clerk.io erstellten Element-Block übereinstimmt.

Sie können für jedes Element auf Edit Element klicken, um nachzusehen, wie die Referenz lauten muss.

Ungültiger API-Endpunkt #

Dieser Fehler tritt auf, wenn Sie die Klasse clerk an anderer Stelle in Ihrem HTML genutzt haben.

Diese Klasse ist für unsere Snippets reserviert, da Clerk.js diese Klasse nutzt, um die darzustellenden Elemente zu erkennen.

Um das zu beheben, nennen Sie die Klasse z. B. clerk-product.

Ungültiges Produkt-Argument #

Dieser Fehler bedeutet, dass die übergebene Produkt-ID einen falschen Typ oder eine falsche Syntax hat.

Zum Beispiel: Wenn Ihre Produkt-IDs Ganzzahlen sind, müssen sie dies auch im Embed-Code sein.

Denken Sie auch an die Klammern um die ID, damit daraus eine Liste wird.

<span 
  class="clerk" 
  data-template="@product-page" 
  data-products="[123]">
</span>

Ungültiges Kategorie-Argument #

Dieser Fehler bedeutet, dass die übergebene Kategorie-ID einen falschen Typ oder eine falsche Syntax hat.

Meist liegt es daran, dass der Platzhalter im Kategorie-Embed-Code nicht durch eine tatsächliche ID ersetzt wurde:

<span 
  class="clerk" 
  data-template="@category-page" 
  data-category="INSERT_CATEGORY_ID">
</span>

Das Ausgabe-HTML sollte die Kategorie-ID enthalten:

<span 
  class="clerk" 
  data-template="@category-page" 
  data-category="257">
</span>

Wenn Sie das Snippet manuell kopiert haben, sollten Sie im Dropdown Choose your platform zuerst Ihr Shop-System auswählen, bevor Sie das Snippet kopieren.

Dadurch ändert sich das Snippet automatisch, sodass die passende Logik für Ihr System zur Auswahl der Kategorie-ID eingebaut wird.

Ist Ihr System nicht aufgeführt, müssen Sie selbst die Logik ergänzen, um anhand Ihres Shopsystems die richtige Kategorie-ID einzufügen.

Falscher API-Key #

Dieser Fehler erscheint, wenn der von Ihnen angegebene Public API Key keinem Konto bei Clerk entspricht.

Um dies zu beheben, loggen Sie sich in my.clerk.io ein und gehen Sie zu Developers > API Keys.

Hier finden Sie den Public API Key, den Sie dann in Ihrem Clerk.js-Tracking-Skript – entweder direkt im Code oder in den Integrationseinstellungen (je nach Plattform) – hinterlegen können.

Iubenda-Blockierung #

Wenn Sie für das Cookie-Consent iubenda mit aktiviertem Automatic blocking verwenden, kann es passieren, dass Besucher, die Cookies ablehnen, dazu führen, dass Clerk.io-Skripte oder -Anfragen blockiert werden.

Dies führt typischerweise zu zwei Problemen:

Das sale-Request wird nie gesendet; Bestellungen werden nicht nachverfolgt oder nicht zugeordnet in Clerk.io.
Clerk.io-Elemente werden überhaupt nicht gerendert oder Clerk.js meldet einen Konsolenfehler, dass es mehrmals geladen wurde (da iubenda Skripte umschreibt oder verzögert).

Domains freigeben #

Um das zu beheben, fügen Sie Clerk.io zur Whitelist in iubenda hinzu, damit Skripte und Anfragen nicht blockiert werden, wenn ein Besucher Cookies ablehnt.

Mindestens sollten diese Domains zur Whitelist hinzugefügt werden:

cdn.clerk.io (Clerk.js)
api.clerk.io (Tracking und Sales Requests)

Die genauen UI-Bezeichnungen können abweichen, aber diese Einstellung findet sich meist unter den Cookie-Lösung-Einstellungen Ihres iubenda-Projekts für Automatic blocking.

Für die eigene Anleitung von iubenda siehe deren Artikel zu was tun, wenn der Automatic blocking mode zu viel blockiert.

Korrektur prüfen #

Nach dem Update der iubenda-Einstellungen:

Laden Sie den Shop, lehnen Sie Cookies ab und öffnen Sie die Browser-Konsole.
Prüfen Sie, ob Clerk.js verfügbar ist — typeof Clerk sollte nicht "undefined" ergeben.
Führen Sie Clerk("debug") aus, platzieren Sie eine Testbestellung und prüfen Sie, ob ein sale-Request an Clerk.io geschickt und mit status: "ok" quittiert wird.

POS/ERP-Umsatzdaten #

Für einige Webshops ist es relevant, Umsatzdaten aus anderen Systemen als dem eigentlichen Webshop hochzuladen.

Zum Beispiel, wenn Sie den Algorithmus auf Basis von Verkäufen aus einem stationären Geschäft oder B2B-Store optimieren wollen.

Clerk unterscheidet nicht, woher Bestellungen kommen – solange Sie eine ID, einen Zeitstempel und eine Produktliste übergeben, können diese bei Clerk hochgeladen werden.

Der empfohlene Ansatz ist die Nutzung der CRUD API, da Sie so den Prozess vollständig automatisieren können.

Indem Sie diese API-Calls implementieren, können Sie Bestelldaten direkt an Ihren Store in Clerk übertragen.

Erstellen Sie einfach einen POST-Call zum /orders-Endpunkt in Ihrem ERP-System oder Webshop, lassen Sie den Job regelmäßig laufen, z. B. einmal im Monat, und Sie können Offline-Bestellungen nutzen, um Ihre Online-Empfehlungen und Suchergebnisse zu verbessern.

Alternativ können Sie auch eine CSV-Datei manuell hochladen, ohne Code schreiben zu müssen.

Mehr dazu lesen Sie unter CSV-Dateien hier.

Währungsumrechnung #

Es gibt verschiedene Wege, mit Währungsumrechnung in Clerk zu arbeiten.

Ein einfacher Weg wird im Folgenden beschrieben.

Währungen übersetzen #

Wenn Besucher Google Translate auf Ihrem Shop nutzen, können Preiswerte auf eine Weise übersetzt werden, die das Format zerstört oder die Währungsausgabe verändert.

Um dies zu verhindern, umschließen Sie die Preisausgabe in Elementen, die nicht übersetzt werden sollen.

Empfohlene Auszeichnung #

Nutzen Sie sowohl translate="no" als auch die Klasse notranslate am Preiselement:

<span class="clerk-price notranslate" translate="no">
  {{ product.price | money }}
</span>

Wenn Sie Listenpreis und Angebotspreis anzeigen, wenden Sie das gleiche Schema auf jeden Preiswert an:

<span class="clerk-old-price notranslate" translate="no">
  {{ product.list_price | money }}
</span>
<span class="clerk-new-price notranslate" translate="no">
  {{ product.price | money }}
</span>

Anwendungsorte #

In Ihrem Clerk Design, wo Preise gerendert werden
In allen eigenen HTML-Wrappern, die Preiswerte ausgeben

Dadurch bleibt der Rest der Seite übersetzbar, während Preis- und Währungsformatierungen erhalten bleiben.

Preisobjekte senden #

Clerk muss die Preise jedes Produkts in den verschiedenen Währungen kennen.

Am einfachsten ist es, diese als string-enkodiertes JSON-Objekt mit formatierten Preisen (Schlüssel: ISO der Währung) in Ihrem Data Feed zu senden.

"products": [
  {
    "id": 1,
    "name": "Cheese",
    "description": "A nice piece of cheese.",
    "price": 100,
    "list_price": 50,
    "categories": [25, 42],
    "image": "http://example.com/images/products/1.jpg",
    "url": "http://example.com/product/1",
    "on_sale": true,
    // String-encoded JSON examples
    "prices_formatted": "{\"USD\":\"$100\", \"EUR\":\"€87.70\", \"GBP\":\"£68.68\"}",
    "list_prices_formatted": "{\"USD\":\"$120\", \"EUR\":\"€97.70\", \"GBP\":\"£78.68\"}"  
  },
  {
    "id": 2,
    "name": "A pound of nuts",
    "description": "That's a lot of nuts!",
    "price": 150,
    "categories": [1],
    "image": "http://example.com/images/products/2.jpg",
    "url": "http://example.com/product/2",
    "on_sale": false,
    // String-encoded JSON example
    "prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}",
    "list_prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}"
  }
]

Formatter erstellen #

Im Clerk.js können Sie JavaScript-Funktionen definieren, die in Designs genutzt werden können.

Hier können Sie eine Funktion definieren, die Ihr price-dict als Argument nimmt und abhängig von der im Frontend gewählten Währung den passenden Preis zurückgibt.

Stellen Sie sicher, dass Sie currency durch die aktuell ausgewählte Währung im Frontend ersetzen.

Clerk('config', {
  key: 'Your_API_Key',
  formatters: {
      currency_selector: function (price_list) {
      const currency = "EUR";
      price_groups_obj = JSON.parse(price_list)
        return price_groups_obj[currency];
      }
  }
});

Formatter verwenden #

Nach dem Definieren des Formatters kann dieser im Design so genutzt werden:

<div class="price">
   <span class="price">
      {{ product.prices_formatted | currency_selector }}
   </span>
</div>

Kundenspezifische Preise #

Clerk unterstützt das Anzeigen unterschiedlicher Preise für eingeloggte Kunden – entweder durch Fetzen individueller Preise beim Rendern oder durch Vorab-Speichern von Gruppenpreisen in den Produktdaten.

Dies wird umfassend im eigenen Artikel zu Customer Pricing behandelt.

HTTP-Authentifizierung #

HTTP-Authentifizierung wird oft auf Staging-Seiten genutzt, um ungebetene Besucher fernzuhalten.

Dies blockiert in vielen Fällen auch den Clerk-Importer und zeigt im Sync-Log typischerweise einen 401 Unauthorized-Fehler an.

Sie können dies beheben, indem Sie die Zugangsdaten in der Import-URL angeben.

In my.clerk.io > Data > Configuration, aktualisieren Sie Ihre Import-URL z. B. so:

http://USER:PASS@www.ewoksRus.com/JSONFEED

Keine getrackten Bestellungen #

Eine vollständige Anleitung, wie Sales-Tracking funktioniert, wie man es einrichtet und schrittweise debuggt, finden Sie im Sales Tracking-Artikel.

Kein Clerk-Impact #

Wenn Bestellungen getrackt werden, aber keine als Clerk-beeinflusst in der Analyse erscheinen, lesen Sie den Abschnitt No Clerk Impact im Artikel zum Sales-Tracking.

Slider mit wenigen Produkten ausblenden #

Wenn eine Kategorie sehr wenige Produkte enthält, kann ein Slider leer oder wiederholt aussehen.

Es gibt zwei Möglichkeiten, dies zu lösen:

Clerk Design-Bedingung #

Verwenden Sie eine Bedingung um das Slider-Markup, so dass es nur gerendert wird, wenn ausreichend viele Produkte zurückgegeben wurden.

{% if products.length >= 6 %}
  <div class="clerk-slider">
    {% for product in products %}
      <!-- product card -->
    {% endfor %}
  </div>
{% endif %}

Das ist schnell umgesetzt, aber es beruht trotzdem auf der Antwort von Clerk, ob der Slider sichtbar sein soll – sprich, es kostet trotzdem einen API-Call, auch wenn nichts angezeigt wird.

Serverseitige Bedingung #

Wenn Ihr System schon weiß, wie viele Produkte eine Kategorie hat, entscheiden Sie direkt in Ihrem Template, ob das Clerk-Embed überhaupt ausgegeben wird.

{% if category.product_count >= 6 %}
  <span class="clerk" data-template="@category-page-slider"></span>
{% endif %}

Dies ist der bevorzugte Ansatz, da der Slider nur initialisiert wird, wenn genug Produkte vorhanden sind, und das Verhalten perfekt zur Kategoriezähl-Logik Ihres Shops passt.

Upgrade auf Clerk.js 2 #

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

Sie macht die Installation von Clerk auf jedem Shop einfacher.

Da sich die beiden Versionen aber leicht unterscheiden, müssen Sie für ein erfolgreiches Upgrade folgende Schritte beachten.

Die beiden Hauptunterschiede von Clerk.js 2 sind:

Die Designs in my.clerk.io nutzen das Liquid-Template, können aber auch bequem mit dem Design-Editor erstellt werden.
Das Script muss direkt vor dem </head> Tag in Ihrem Webshop-Template eingefügt werden.

Designs erstellen #

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

Sie können entweder neue Clerk.js 2 Designs im Design Editor erstellen oder Ihren alten Code in Liquid umwandeln – dies erklärt der folgende Guide.

Nachfolgend finden Sie die Anleitung zur Umwandlung Ihrer alten Code-Designs in Liquid.

Design Editor-Option #

Gehen Sie zu my.clerk.io > Recommendations/Search > Designs > New Design.
Wählen Sie einen anderen Design-Typ als Blank und geben Sie einen Namen ein. Wir empfehlen, “V2” hinzuzufügen, damit klar ist, dass Sie ein Clerk.js-2-Design verwenden.
Im Design Editor können Sie bestehende Elemente wie Name, Bild, Button etc. anklicken oder neue hinzufügen.
Klicken Sie auf Publish Design, wenn Sie fertig sind, und fahren Sie mit Schritt 2 im Leitfaden fort.
Gehen Sie zu Recommendations/Search > Elements und ändern Sie Ihr Clerk Element auf Ihr neues Design, dann klicken Sie auf Update Element.
Dies hat vorübergehend zur Folge, dass die Elemente nicht im Shop erscheinen, bis Clerk.js 2 wie weiter unten beschrieben eingefügt wird.

Designs umwandeln #

Da Clerk.js 2 die flexiblere Template-Sprache Liquid nutzt, müssen Sie Ihr Design in diese Sprache übertragen.

Gehen Sie zu my.clerk.io > Recommendations/Search > Designs > New Design.
Wählen Sie Blank > Code und geben Sie einen Namen ein. Wir empfehlen, “V2” hinzuzufügen, um das Design erkennbar als Clerk.js 2 zu markieren.
Klicken Sie auf Create Design.
Sie erhalten nun ein leeres Design mit Produkt-HTML und CSS.
Gehen Sie zurück zur Design-Übersicht und klicken Sie in einem neuen Tab auf Edit Design neben Ihrem Clerk.js-1-Design, damit Sie Inhalt einfach kopieren können.
Kopieren Sie das alte Clerk.js-1-Design in Ihr neues Clerk.js-2-Design.
- Sie werden merken, dass es keinen Container Code mehr gibt.
- Denn Liquid verwendet for-Schleifen zum Rendern aller Produkte.
- Kopieren Sie Ihr altes Product-HTML in die for-Schleife, Ihren alten Container Code herum und das CSS.
Konvertieren Sie das Design in die Liquid-Syntax um. Wichtig: Die alten Designs nutzten die Syntax {{ formatter attribute }}, in v2 ist es {{ product.attribute | formatter }}.
Überprüfen Sie alle Attribute und passen Sie auf das neue Format an.
Wenn Sie {{#if}} oder {{#is}}-Anweisungen nutzen, müssen diese ebenfalls umgesetzt werden: {% if product.attribute %} {% else %} {% endif %}.
Löschen Sie id="{{ $id }}" und die Klasse :target im Container Code in der Clerk.js 2 Version, da sie nicht mehr unterstützt werden.
Nachfolgend ein Beispiel eines Clerk.js-1-Designs und die vollständig umgesetzte Version:

Clerk.js 1 Design #

// Product HTML
<li class="clerk-product">
    <a href="{{ url }}">
        <img src="{{ image }}" />
        <div class="clerk-product-name">{{ name }}</div>
        <div class="clerk-price-wrapper">
            {{#if list_price}}
                <div class="clerk-old-price">
                    <s>Price {{ money_eu list_price }}</s>
                </div>
                <span class="clerk-new-price">Price {{ money_eu price }}</span>
            {{else}}
                <div class="clerk-product-price">Price {{ money_eu price }}</div>
            {{/if}}
        </div>
    </a>
    <div class="clerk-cta-button btn button">Buy Now</div>
</li>

// Container Code
<h2>{{ headline }}</h2>
<ul id="{{ $id }}" class=":target clerk-slider"></ul>

<!-- This code creates the slider by its ID. -->
<script type="text/javascript">
    Clerk.ui.slider("{{ id }}").init();
</script>

Clerk.js 2 Design #

<h2>{{ headline }}</h2>

<ul class="clerk-slider">
    {% for product in products %}
    <li class="clerk-product">
        <a href="{{ product.url }}">
            <img src="{{ product.image }}" />
            <div class="clerk-product-name">{{ product.name }}</div>
            <div class="clerk-price-wrapper">
                {% if product.list_price %}
                    <span class="clerk-old-price"><s>Price {{ product.list_price | money_eu }}</s></span>
                    <span class="clerk-new-price">Price {{ product.price | money_eu }}</span>
                {% else %}
                    <div class="clerk-product-price">Price {{ product.price | money_eu }}</div>
                {% endif %}
            </div>
            <div class="clerk-cta-button btn button">Buy Now</div>
        </a>
    </li>
    {% endfor %}
</ul>

Klicken Sie auf Update Design, um die Änderungen zu speichern.
Gehen Sie zu Recommendations/Search > Elements und wählen Sie Ihr neues Design im Elementblock.
Klicken Sie auf Update Element. Erst nach Abschluss von Schritt 2 erscheinen die Designs wieder auf Ihrer Website.

Script ersetzen #

Suchen Sie die Template-Datei, die für alle Seiten des Shops genutzt wird und in der das ursprüngliche Clerk.js-Script meist unten steht.
Entfernen Sie das alte Clerk.js-Script aus der Datei. Es sieht ungefähr so aus:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
    window.clerkAsyncInit = function() {
        Clerk.config({
            key: 'public_api_key'
        });
    };
    (function(){
        var e = document.createElement('script'); e.type='text/javascript'; e.async = true;
        e.src = document.location.protocol + '//api.clerk.io/static/clerk.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
    })();
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Gehen Sie zu my.clerk.io > Developers > Tracking Code. – hier finden Sie den Clerk.js-2-Code.
Kopieren Sie den Code und fügen Sie ihn direkt vor dem </head>-Tag im Template ein und speichern Sie die Datei.

Herzlichen Glückwunsch! Sie nutzen nun das stark verbesserte Clerk.js-2 Setup!

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

Umgang mit Require.js #

Dieser Abschnitt gilt nur bei Nutzung von Clerk.js 1.

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

Dies zeigt sich durch folgenden Fehler in der Konsole:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Wege, Require.js zu handhaben. Beide erfordern eine Änderung am Tracking-Script, das Sie unten auf jeder Seite eingefügt haben.

Integration in Require.js #

Am besten ist es, Clerk in Require.js bekanntzumachen.

Fügen Sie require(['clerk'], function() {}); am Ende des Tracking-Scripts ein.

Require.js ignorieren #

Falls das nicht funktioniert, lässt sich Require.js ignorieren.

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

Nach Anwendung einer dieser Methoden ist Clerk.js mit Require.js kompatibel.

Diese Seite wurde von einer hilfreichen KI übersetzt, daher kann es zu Sprachfehlern kommen. Vielen Dank für Ihr Verständnis.