Jeder (Webshop)

FAQ

Antworten auf häufig gestellte Fragen zu benutzerdefinierten Integrationen

Haben Sie Probleme mit Ihrer individuellen Integration? Dieses FAQ behandelt die häufigsten Probleme und deren Lösungen, von Single-Page-Apps bis zur Verkaufsnachverfolgung.

Single-Page-Apps #

Diese werden auch als Progressive Web Apps (PWA) bezeichnet und laden die Seite in der Regel als eine einzige Seite, anstatt einzelne Seiten wie gewohnt 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 verwenden, werden Seiten jedoch mit JavaScript gerendert statt mit einem Standardseitenaufruf.

Deswegen muss die Darstellung mit Clerk.js gesteuert werden, damit sie dem Seitenaufruf im App entspricht.

Clerk.js einbinden #

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

Danach ist die Bibliothek während der gesamten Session verfügbar.

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 -->

Darstellung steuern #

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

Sie können das Timing steuern, indem Sie das Element erst einfügen, wenn es gerendert werden soll.

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

Jedes Mal, wenn eine Seite geladen wird, gehen Sie wie folgt vor:

  • Fügen Sie das Clerk-Snippet in das HTML ein mit einem eindeutigen Selektor zum Ansprechen.

  • Führen Sie Clerk("content", "SELECTOR") aus, um es zu rendern.

Wenn der Besucher die Seite verlässt, zerstören Sie das Snippet und rendern Sie es erneut, wenn der Besucher auf die gleiche Seite zurückkehrt.

Dies stellt sicher, dass Clerk.js das Snippet nicht als bereits gerendert ansieht und es dadurch nicht visualisiert wird.

Beispiel:

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

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

Clerk.js kann auch so konfiguriert werden, automatisch Elemente zu initialisieren mit Ihren individuellen Selektoren, nachdem Sie sie zum ersten Mal gerendert haben.

Einfluss auf die Seitenladegeschwindigkeit #

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

Im Folgenden sehen Sie, wie es sich auf die Performance Ihrer Website auswirkt.

Performance #

Die Clerk.js-Bibliothek ist nur 37,5kb groß und lädt daher sehr schnell.

Außerdem lädt sie die Elemente asynchron, das heißt, der restliche Teil der Seite lädt, während Clerk.js die Inhalte rendert.

Eine Erhöhung der Ladezeit einer Seite entsteht meist dadurch, dass mehr Bilder geladen werden als zuvor, da die Suche und Empfehlungen von Clerk am besten funktionieren, wenn sie ansprechend dargestellt werden.

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

Zum Beispiel: Wenn Bilder in Empfehlungen eine Auflösung von 400x400px im Desktop-Ansicht haben, senden Sie Bilder mit maximal 420x420px oder ähnlich.

Google Page Speed #

Wenn Sie Google Page Speed Insights oder ein ähnliches Tool zur Analyse der Leistung Ihrer Website nutzen, kann Clerk.js unter Leverage browser caching. erscheinen.

Leverage browser caching

Der Zweck von Clerk.js ist es, die Einbindung von Ergebnissen aus Clerk in jede Website so einfach wie möglich zu machen.

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

Wenn wir neue UI-Funktionen hinzufügen oder bestehende verbessern, sind sie in Clerk.js enthalten und müssen vom Endnutzer heruntergeladen werden, um genutzt zu werden.

Ein Cache-Ablauf von 60 Minuten bedeutet, dass neue Funktionen spätestens nach 60 Minuten jedem zur Verfügung stehen.

Je länger die Cache-Dauer, desto länger dauert es, bis die neuesten Funktionen verfügbar sind.

Wichtig ist, dass Endanwender Clerk.js nur einmal herunterladen müssen, wenn neue Funktionen zur Verfügung stehen.

Der Cache-Ablauf von 60 Minuten bedeutet lediglich, dass der Browser des Endnutzers alle 60 Minuten bei Clerk anfragt.

Wenn es keine Änderungen an Clerk.js gibt, wird nichts heruntergeladen.

Die Cache-Laufzeit von 60 Minuten ist somit ein Kompromiss zwischen Minimierung der Webanfragen und Sichtbarkeit von neuen Features und Verbesserungen.

Die meisten Sessions dauern weniger als 60 Minuten, daher wird die Anfrage meist nur einmal je Session gestellt.

Wie im Screenshot zu sehen ist, ist das eine übliche Praxis, die (genau wie Clerk) von Google Analytics, Facebook, Trustpilot und vielen anderen genutzt wird.

CLS-Auswirkung #

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

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

Mehr über CLS erfahren Sie hier.

Befolgen Sie diese Richtlinie nur, wenn Ihr CLS-Score höher als 0,2 ist und Clerk-Elemente im sichtbaren Bereich (above the fold) stehen.

Um Layoutverschiebungen zu verhindern, muss vor dem Einfügen der Clerk-Empfehlungen ein Platzhalter reserviert werden.

Fügen Sie dazu eine Mindesthöhe basierend auf der erwarteten Content-Höhe ein.

Beispielcode:

.clerk-slider-wrapper {
    min-height: 300px; /* Passen Sie diesen Wert an die erwartete Inhaltsgröße an */
    width: 100%;
}

API-Aufrufe #

Mit Clerk.js können API-Aufrufe durchgeführt werden, indem Sie die eingebaute Funktion Clerk("call") nutzen.

Diese Funktion nimmt 3 Argumente entgegen:

  • Einen API-Endpunkt

  • Ein JSON Dictionary mit Parametern

  • Eine Callback-Funktion zur Verarbeitung der Antwort

Anfragen #

Nachfolgend ein Beispielskript, das die 10 beliebtesten Produkte abfragt und die Antwort in der Konsole protokolliert.

Die Antwort enthält ein JavaScript-Objekt mit dem Status des API-Aufrufs 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-Aufrufe machen, können Sie Callback-Funktionen nutzen, um die Antwort wie gewünscht zu verarbeiten.

Die Funktionen bekommen response als Argument, die alle vom API zurückgelieferten Daten enthält.

Beispiel, um eine Liste von HTML-Elementen zu erstellen, die auf Kategorien zum Query “men” verlinken:

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 plattformabhängig unterschiedlich und das Verhalten kann sich je nach verwendeten Plugins ändern.

Da die Designs von Clerk aus HTML & CSS bestehen, kann die Funktion in der Regel hinzugefügt werden, wenn Sie verstehen, wie sie auf Ihrer Seite funktioniert.

Allgemeines Vorgehen #

Einige Add-to-Cart-Buttons benötigen JavaScript, damit sie funktionieren.

In diesen Fällen können Sie die Funktionalität an Clerks bestehende cart-Methode anbinden.

Wie das funktioniert, erfahren Sie in unseren Developer-Dokumenten hier.

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

Der Code ist meistens ein <div>- oder button-Element.

Kopieren Sie den kompletten Button-HTML.

Fügen Sie diesen Code in Ihr Design ein.

Nun müssen Sie die Variablen im Code identifizieren.

In der Regel müssen Sie herausfinden, wo der Code wie folgt verwendet wird:

  • Produkt-ID

  • Produktmenge

Ersetzen Sie die Werte der Produkt-ID mit den Liquid-Variablen für diese Datenpunkte.

Die ID ist immer {{ product.id }} und die Menge variiert je nach Datenmodell. In diesem Beispiel könnte dies {{ product.qty }} sein.

Fügen Sie Ihren Code ins HTML Ihres Designs ein und testen Sie die Funktion.

Beispiel #

Der folgende Add-to-Cart-Button ist ein <div> mit der Klasse button-container:

Add-To-Cart example

Die Menge befindet sich im Cart-Link nach /cart?add= und die Produkt-ID nach &id_product=.

Die Produkt-ID wird zudem im Attribut data-id-product referenziert und die Produktmenge in .data-minimal_quantity.

Diese Werte sollten im Design mit Liquid-Tags ersetzt werden, damit die jeweiligen Produkt-IDs und Mengen entsprechend im HTML ausgegeben werden.

Mit diesen Änderungen sieht der finale Add-to-Cart-Button so 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 zum Debuggen genutzt werden können.

Console Errors

Durch Klicken auf den Fehlerlink erhalten Sie weitere Informationen zum Fehler, die Sie selbst zum Debuggen oder für unser Support-Team nutzen können.

Nachfolgend eine Liste der häufigsten Fehler:

Unbekannter Inhalt #

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

Stellen Sie sicher, dass der Name im Embed-Code mit dem Element-Block in my.clerk.io übereinstimmt.

Über Edit Element können Sie für jedes Element sehen, wie der Verweis lauten muss.

Element ID

Ungültiger API-Endpunkt #

Dieser Fehler tritt auf, wenn Sie die Klasse clerk irgendwo in Ihrem HTML verwendet haben.

Diese Klasse ist für unsere Snippets reserviert, da Clerk.js sie nutzt, um zu rendernde Elemente zu identifizieren.

Benennen Sie die Klasse um, z.B. in clerk-product.

Ungültiges Produktargument #

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

Beispielsweise benötigen IDs, die Integer sind, auch diesen Typ im Embed-Code.

Denken Sie auch an eckige Klammern, um eine Liste zu bilden.

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

Ungültiges Kategorieargument #

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

Meist geschieht das, wenn im Kategorie-Snippet der Platzhalter nicht durch eine echte ID ersetzt wurde:

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

Der Output muss die ID beinhalten:

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

Wenn Sie das Snippet per Hand kopiert haben, wählen Sie vor dem Kopieren im Choose your platform-Dropdown Ihr Shopsystem, damit die korrekte Auswahl der Kategorie-ID enthalten ist.

Falls Ihr System nicht gelistet ist, müssen Sie selbst die Logik zur Auswahl der richtigen Kategorie-ID einbauen.

Falscher API-Schlüssel #

Dieser Fehler erscheint, wenn der von Ihnen angegebene Public API Key keinem Account bei Clerk zugeordnet werden kann.

Melden Sie sich bei my.clerk.io an und wechseln Sie zu Developers > API Keys.

Hier finden Sie den Public API Key, den Sie dann in Ihr Clerk.js-Tracking-Skript einfügen können – entweder direkt im Code oder in den Integrations-Einstellungen, je nach Plattform.

POS/ERP-Verkaufsdaten #

Für manche Webshops ist es sinnvoll, Verkaufsdaten aus anderen Systemen als dem eigentlichen Webshop hochzuladen.

Beispielsweise wenn Sie die Algorithmen auf Basis von Verkäufen aus einem stationären Geschäft oder B2B-Shop optimieren wollen.

Clerk unterscheidet nicht zwischen Bestellungen aus verschiedenen Quellen – solange Sie eine ID, einen Zeitstempel und eine Produktliste liefern können, können sie hochgeladen werden.

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

Durch Implementierung dieser API-Aufrufe senden Sie Bestelldaten direkt an Ihren Store in Clerk.

Einfach einen POST-Aufruf an den /orders-Endpunkt aus Ihrem ERP oder Webshop anlegen, das Job regelmäßig ausführen (z.B. monatlich), und Sie können Offline-Bestellungen nutzen, um Ihre Empfehlungen und Suchergebnisse zu optimieren.

Alternativ können Sie eine CSV-Datei manuell hochladen, ohne zu programmieren.

Mehr zum Thema CSV-Dateien hier.

Währungsumrechnung #

In Clerk gibt es mehrere Wege, mit Währungsumrechnung zu arbeiten.

Eine einfache Methode wird im Folgenden erklärt.

Währungen übersetzen #

Wenn Besucher Google Translate im Webshop nutzen, kann es vorkommen, dass Preiswerte so übersetzt werden, dass Formatierung oder die Währungsausgabe durcheinander gerät.

Um das zu verhindern, schließen Sie die Preisausgabe in Elemente ein, die nicht übersetzt werden sollen.

Empfohlener Markup #

Verwenden Sie sowohl translate="no" als auch die Klasse notranslate im Price-Element:

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

Wenn Sie Listenpreis und Verkaufspreis anzeigen, wenden Sie dieses Pattern auf beide Werte 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>

Anwendung der Standorte #

  • In Ihrem Clerk Design, wo die Preise gerendert werden.
  • In beliebigen individuellen HTML-Wrappern, die Preise ausgeben.

So bleibt der Rest der Seite übersetzbar und die Preis-/Währungsformatierung erhalten.

Preisobjekte senden #

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

Am einfachsten senden Sie diese als string-enkodiertes JSON-Objekt mit formatierten Preisen, wobei der Währungs-ISO-Code als Schlüssel dient, über Ihren Datenfeed.

"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 #

In Clerk.js können Sie JavaScript-Funktionen definieren, die Sie mit Ihren Designs nutzen.

Hier können Sie eine Funktion definieren, die Ihr price-dict als Argument nimmt und den Preis einer bestimmten Währung entsprechend der Frontend-Logik Ihrer Wahl zurückgibt.

Stellen Sie sicher, dass Sie currency durch die aktuell ausgewählte Währung des Frontends 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 Definition des Formatters kann er im Design wie folgt aufgerufen werden:

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

Kundenspezifische Preise #

Um völlig individuelle Preise je nach eingeloggtem Kunden anzuzeigen, erstellen Sie ein Event in Clerk, das den korrekten Preis einfügt, bevor die Produkte gerendert werden.

Events sind JavaScript-Funktionen, die vor oder nach der Produktanzeige durch Clerk laufen.

Diese Methode ist möglich, wenn Sie Preise anhand der Produkt-ID und Kunden-ID direkt vom Server im Frontend per JavaScript abfragen können.

Um individuelle Kundenpreise anzuzeigen, sollte der Code direkt nach der Antwort ausgeführt werden.

Nachfolgend ein Beispiel für ein einfaches Event:

<span class="clerk" data-template="@home-page-popular"></span>

<script>
  Clerk('on', 'response', function(content, data) {
     console.log(data.result);
  });
</script>

Die Funktion erhält als Argument data, d.h. die komplette Antwort, die Clerk von der API sendet.

Individuelle Kundenpreise #

Wenn Sie komplett individuelle Preise je nach eingeloggtem Kunden anzeigen wollen, müssen Sie ein Event einrichten, das nach der Produktanzeige den richtigen Preis einfügt.

Events sind JavaScript-Funktionen, die vor oder nach der Clerk-Produktanzeige ablaufen.

Diese Methode setzt voraus, dass Sie Preise vom Server anhand Produkt-ID und Kunden-ID per AJAX im Frontend abfragen können.

Am besten erstellen Sie einen Platzhalter für den Preis im Design und ersetzen diesen dann mit dem Rückgabewert Ihres AJAX-Aufrufs.

Ein Beispiel:

<div class="clerk-price-container">
   <span class="clerk-price">
      Loading price...
   </span>
</div>

Nutzen Sie ein Clerk-Event, um auf das Rendern der Produkte zu warten, fragen Sie den Preis-Server nach Preis für die jeweilige Produkt- und Kunden-ID, und fügen Sie den Wert ins HTML ein.

Zum Beispiel:

<script>
  var customer_id = INSERT_CUSTOMER_ID;
  Clerk("on", "rendered", function(content, data){
    for (i = 0; i < data.product_data.length; i++) {
        var product = data.product_data[i];
          var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
          let price_container = document.querySelector(`[data-clerk-product-id='${product.id}'] .clerk-price`);
          price_container.innerText = custom_price;
      }
  })
  </script>

Der obige Code setzt voraus, dass Sie einen eingeloggten Kunden per INSERT_CUSTOMER_ID identifizieren können und eine Funktion wie FETCH_PRICE_FROM_SERVER existiert, die einen Preis basierend auf Produkt und Kunde liefert.

Das price_container-Element wird genutzt, um das passende Produkt per ID (data-clerk-product-id) zu finden, welches von Clerk.js hinzugefügt wird.

Abschließend wird der Text, in diesem Beispiel “Loading price…”, durch den Rückgabewert ersetzt.

Kundengruppenpreise #

Die Einrichtung von Kundengruppenpreisen umfasst 4 Schritte:

  1. Einbindung der verschiedenen Preise im Datenfeed.

  2. Einfügen einer globalen Variable, die die aktuelle Kundengruppen-ID holt.

  3. Erstellen einer Funktion zum Abruf des jeweiligen Preises.

  4. Darstellung des Preises im Design.

Preisobjekte einbinden #

Starten Sie mit einem Attribut für alle Produkte, das alle Preise für die verschiedenen Gruppen enthält, wobei jeder Preis einer bestimmten Kundengruppe zugeordnet sein muss.

Dies sollte als JSON-Objekt gesendet werden, z.B.:

"customer_group_prices": {
  "GROUP1": 100,
  "GROUP2": 202,
  "GROUP3": 309
}

Kundengruppen-ID-Variable #

Fügen Sie eine dynamische globale Variable zu Clerk.js hinzu, die die Kundengruppen-ID des aktuellen Kunden setzt.

Die Kundengruppen-ID muss dem Schlüssel des entsprechenden Preises im Datenfeed entsprechen.

Beispiel: Ein Nutzer, der den Preis von Gruppe 2 sehen soll, erhält die ID “GROUP2”.

Clerk('config', {
  globals: {
    customer_group: "GROUP2"
  }
});

Preis holen #

Jetzt können Sie einen Formatter erstellen, der customer_group als Argument nimmt und den jeweiligen Preis zurückgibt.

Schreiben Sie eine Funktion, die den Preis aus dem preis-dict anhand der Kundengruppen-ID als Schlüssel holt.

Fügen Sie dies in die Clerk.js-Konfiguration ein. Beispiel für getPrice:

Clerk('config', {
  globals: {
    customer_group: "GROUP2"
  },
  formatters: {
    getPrice: function (prices, customer_group) {
      return prices[customer_group];
    }
  }
});

Preis im Design anzeigen #

Wenn ein getPrice-Formatter erstellt wurde, kann dieser direkt im Design verwendet werden – zusammen mit der Preisliste customer_group_prices, die Sie in Schritt 1 angelegt haben:

<li style="text-align: center; width: 180px;">
	<a href="{{ product.url }}">
		<img src="{{ product.image }}" />
		{{ product.name }}
	</a>
	<div class="price">
		{{ product.customer_group_prices | getPrice customer_group }}
	</div>
</li>

HTTP-Authentifizierung #

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

Oft blockiert dies auch den Clerk-Importer und verursacht in der Sync-Log häufig einen 401 Unauthorized-Fehler.

Sie können das Problem lösen, indem Sie die Authentifizierungsdaten in die Import-URL einfügen.

In my.clerk.io > Data > Configuration passen Sie Ihre Import-URL so an:

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

Keine getrackten Bestellungen #

In my.clerk.io wurden Getrackte Bestellungen und Bestelldetails auf einer einzigen Bestellseite zusammengeführt.

Clerk muss kontinuierlich Verkäufe aus dem Webshop tracken, um die Ergebnisse aktuell zu halten und dem Verhalten der Kunden anzupassen.

In einigen Fällen können Einstellungen im Webshop das Sales-Tracking verhindern.

Im Folgenden finden Sie Hinweise zur Fehlerbehebung beim Sales-Tracking in einer Clerk.js-Implementierung und die häufigsten Fehlerursachen und -lösungen.

Vorab-Checkliste #

Stellen Sie sicher, dass Sie installiert haben:

Diese sind generell erforderlich, um Verkäufe bei einer Clerk.js-Integration zu tracken.

Logs prüfen #

Meist schlägt das Sales-Tracking wegen Fehlern bei den Besucher-IDs oder Produkt-IDs im Verkaufsaufruf fehl, der nach Abschluss eines Kaufs an Clerk gesendet wird.

Um das zu debuggen, müssen Sie eine Testbestellung durchführen.

In manchen Fällen liegt das Problem am Sales-Tracking-Skript selbst und kann über die Logs in my.clerk.io > Developers > Logs. geprüft werden.

Falls das Tracking-Skript einen Fehler verursacht, ist dieser häufig auf dieser Seite zu sehen.

Klicken Sie auf Details, um weitere Informationen zu erhalten.

Error Details

Wenn Sie keine Fehler in den Logs sehen, identifizieren Sie weitere Sales-Tracking-Probleme am einfachsten mit einer Testbestellung.

Debugging der Testbestellung #

Im folgenden Beispiel wird Chrome verwendet, um zu zeigen, wie das Sales-Tracking mit einer Testbestellung debuggt wird. Andere Browser bieten ähnliche Funktionen.

  1. Legen Sie Produkte in Ihren Warenkorb.

  2. Gehen Sie zur Kasse.

  3. Öffnen Sie vor dem Abschluss der Bestellung die Konsole Ihres Browsers.

  4. Wechseln Sie zu Network und suchen Sie nach “clerk”.

  5. Schließen Sie die Bestellung ab, sodass Sie auf der Bestellbestätigungsseite landen.

  6. Klicken Sie auf den Aufruf, der mit sale beginnt (meist sale?key=…).

Dort sehen Sie die Daten, die an die Sales-Tracking-API gesendet und von dieser empfangen werden.

Unter Preview können Sie erkennen, ob Fehler enthalten sind und was das Tracking verhindert.

Nachfolgend die häufigsten Fehler beim Sales-Tracking.

Ungültige Produktsyntax #

Dieser Fehler tritt auf, wenn die übergebenen Produkt-IDs eine falsche Syntax haben.

Die häufigsten Fehler sind:

  • Die Produkt-IDs werden beim Sales-Tracking als Strings gesendet, aber in Clerk als Integer oder umgekehrt.

  • Die Liste der Produkt-IDs enthält Textformatierungszeichen statt reinem JSON: "products":\[\\"id"\\:\\"123-m"\\\].

Fehlendes Argument #

Das bedeutet, dass nicht alle Daten, die Clerk zum Tracken eines Kaufs benötigt, gesendet werden.

Achten Sie auf alle erforderlichen Datenattribute im Sales-Tracking.

Kein Request gesendet #

Wenn Sie den sale-Request trotz beider Skripte nicht sehen, wurde das Clerk.js-Skript nicht korrekt geladen.

Testen Sie dies so:

  1. Öffnen Sie die Konsole in Ihrem Browser.

  2. Tippen Sie “Clerk” ein.

  3. Wenn Clerk.js nicht korrekt geladen wurde, erscheint ein ReferenceError:

Uncaught ReferenceError: Clerk is not defined

In diesem Fall prüfen Sie Ihr Clerk.js-Setup:

  • Stellen Sie sicher, dass Clerk.js auf allen Seiten installiert ist.

  • Prüfen Sie, ob die Einbindung durch anderes JavaScript blockiert wird.

Iubenda-Blockierung #

Wenn Sie iubenda für den Cookie-Consent nutzen (insbesondere mit Automatischer Blockierung) und ein Besucher Cookies ablehnt, kann iubenda die Clerk-Skripte oder Requests blockieren.

Das bedeutet in der Praxis:

  • Die sale-Anfrage wird nie gesendet, sodass die Bestellung nicht getrackt oder nicht zugeschrieben wird.
  • Clerk-Elemente werden gar nicht angezeigt oder Clerk.js protokolliert einen Fehler, dass mehrfach geladen wurde (da iubenda Skripte umschreibt oder verzögert).

Lösung: Clerk.io auf Allowlist in iubenda setzen #

Stellen Sie in iubenda sicher, dass Clerk nicht blockiert wird, wenn der Besucher Cookies ablehnt.

Mindestens sollten diese Domains auf der Allowlist stehen:

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

Die genauen UI-Bezeichnungen variieren in iubenda, zu finden meist unter Cookie Solution im Bereich Automatische Blockierung (Allowlist/Whitelist/Ignorierliste).

Offizielle Hinweise von iubenda finden Sie hier: https://www.iubenda.com/en/help/153445-what-to-do-when-the-automatic-blocking-mode-is-blocking-too-much/.

Lösung überprüfen #

Nach Aktualisierung der iubenda-Einstellungen:

  1. Webshop laden, Cookies ablehnen, Konsole öffnen.
  2. Prüfen, ob Clerk.js verfügbar ist (z.B. sollte typeof Clerk nicht "undefined" sein).
  3. Clerk("debug") ausführen, Testbestellung platzieren und sicherstellen, dass eine sale-Anfrage geschickt wird und mit status: "ok" quittiert wird.

Kein Clerk Impact #

Wenn Verkäufe in my.clerk.io erfolgreich getrackt werden, aber keine davon als von Clerk beeinflusst angezeigt werden, liegt das Problem meist im Visitor-Tracking / Click-Tracking.

Gehen Sie wie folgt vor, um zu prüfen, ob das Visitor-Tracking funktioniert:

  1. Klicken Sie ein beliebiges Produkt über Clerks Search oder Recommendations an.

  2. Schließen Sie die Bestellung ab (Produkt vorher in den Warenkorb legen).

  3. Melden Sie sich bei my.clerk.io an und wechseln Sie zu Orders.

  4. Warten Sie, bis die Bestellung erscheint.

Wenn Visitor-Tracking aktiv ist, sehen Sie in den Bestelldetails auf der Orders-Seite den von Clerk gelieferten Wert:

Orders overview

Wenn kein Wert angezeigt wird, lesen Sie die folgenden Abschnitte mit häufigen Ursachen.

API-Setups #

Wenn Clerk in Ihrer individuellen Integration direkt über die API eingesetzt wird, muss Visitor-Tracking explizit aktiviert werden.

Wie dies geht, erfahren Sie im API-Artikel.

Falsche Produkt-IDs #

Damit Visitor-Tracking funktioniert, müssen sowohl das Click-Tracking als auch das Sales-Tracking dieselben Produkt-IDs verwenden wie im Import.

Meist liegt das Problem darin, dass Sie Varianten-IDs statt Parent-IDs oder die SKU statt der ID tracken.

Wrong Product IDs

So prüfen Sie, ob das die Ursache ist:

  1. In my.clerk.io unter Data > Orders die ID einer getätigten Bestellung anklicken.

  2. Wenn Clerk das Produkt nicht erkennt, sehen Sie Platzhalter für ID und Bild.

  3. Gehe zu Data > Products und suche nach dem Namen des hinzugefügten Produkts. Hier kannst du die erwartete ID für das Produkt sehen.

Nutze diese, um dein Sales-Tracking so zu konfigurieren, dass die korrekten Produkt-IDs verwendet werden.

Besucher-ID Änderungen #

Clerk verwendet eine Besucher-ID, um jede einzelne Sitzung zu identifizieren, einschließlich der Produkte, die angeklickt und gekauft werden.

Deshalb sollten die IDs während mindestens der gesamten Sitzung, und idealerweise auch über mehrere Sitzungen hinweg, gleich bleiben.

Diese Besucher-ID wird automatisch erstellt, wenn Clerk.js für das Setup verwendet wird. Wenn du jedoch ein API-Setup nutzt oder deine Besucher-IDs anpasst, könnte sie versehentlich geändert werden.

Dieser Fehler ist selten, aber du kannst die Besucher-ID mit folgenden Schritten überprüfen:

  1. Öffne die Netzwerk-Einstellungen in deinem Browser und filtere die Ergebnisse auf “clerk”.

  2. Überprüfe zunächst alle undefined-Aufrufe, die mit Search oder Recommendations zusammenhängen.

  3. Im payload kannst du die aktuelle Besucher-ID sehen. Das kannst du für alle Aufrufe, die mit Clerk verbunden sind, überprüfen.

  4. Klicke danach auf das Produkt und tätige eine Bestellung mit diesem Produkt.

  5. Überprüfe auf der Order Success-Seite erneut dein Netzwerk und finde den Aufruf zu sale?.

  6. Stelle sicher, dass visitor im payload mit der Besucher-ID aus Schritt 3 übereinstimmt.

Wenn die visitor-IDs nicht übereinstimmen, musst du herausfinden, warum sie sich ändern.

Ein häufiger Grund für wechselnde Besucher-IDs kann sein, dass die IDs für jede neue geladene Seite neu generiert werden.

Aktualisiere deinen Code so, dass für jede Seite dieselbe Besucher-ID verwendet wird.

Schieberegler mit wenigen Produkten ausblenden #

Wenn eine Kategorie sehr wenige Produkte hat, kann ein Schieberegler leer oder wiederholend wirken.

Es gibt zwei Möglichkeiten, dies zu handhaben:

Clerk Design-Bedingung #

Verwende eine Bedingung um das Slider-Markup, sodass es nur gerendert wird, wenn genügend Produkte zurückgegeben werden.

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

Das ist schnell umzusetzen, setzt aber immer noch auf die Clerk-Antwort, um zu entscheiden, ob der Slider sichtbar sein soll. Das heißt, es bleibt ein API-Aufruf nötig, selbst wenn der Schieberegler nicht angezeigt wird.

Serverseitige Bedingung #

Wenn deine Plattform bereits die Produktanzahl einer Kategorie kennt, entscheide in deinem Template, ob der Clerk-Einbettungscode überhaupt ausgegeben werden soll.

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

Das ist die bevorzugte Herangehensweise, da der Slider nur dann initialisiert wird, wenn genug Produkte vorhanden sind und das Verhalten vollständig mit der Kategorieanzahl-Logik deines Webshops übereinstimmt.

Upgrade auf Clerk.js 2 #

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

Dadurch wird die Integration von Clerk in jedem Webshop einfacher.

Da sich jedoch die beiden Versionen leicht unterscheiden, solltest du folgende Schritte befolgen, um erfolgreich upzugraden.

Die beiden Hauptunterschiede in Clerk.js 2 sind:

  • Die Designs in my.clerk.io verwenden die Liquid, können aber auch einfach mit dem Design-Editor erstellt werden.
  • Das Skript muss direkt vor dem </head>-Tag in das Template deines Webshops eingefügt werden.

Designs erstellen #

Da Clerk.js 2 einen anderen Ansatz für Designs verwendet, musst du neue Designs erstellen.

Du kannst deine Clerk.js 2 Designs entweder neu im Design Editor erstellen oder deine alten Code-Designs in Liquid konvertieren – dazu gibt der folgende Leitfaden Hilfestellung.

Nachfolgend findest du eine Beschreibung, wie du deine alten Code-Designs in Liquid konvertierst.

Design-Editor-Option #

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

  2. Wähle einen anderen Design-Typ als Blank aus und gib ihm einen Namen. Wir empfehlen, “V2” hinzuzufügen, damit ersichtlich ist, dass du Clerk.js 2 Designs verwendest.

  3. Klicke im Design Editor auf eines der vorhandenen Elemente wie Name, Bild, Button usw., um es zu bearbeiten, oder füge dem Design neue Elemente hinzu.

  4. Klicke auf Publish Design, wenn du fertig bist, und gehe auf Schritt 2 im Leitfaden.

  5. Gehe zu Recommendations/Search > Elements und ändere dein Clerk Element so, dass es dein neues Design verwendet, und klicke dann auf Update Element.

  6. Dadurch werden sie vorübergehend in deinem Webshop nicht angezeigt, bis du Clerk.js 2 wie im weiteren Verlauf dieses Leitfadens beschrieben eingefügt hast.

Designs konvertieren #

Da Clerk.js 2 die flexiblere Template-Sprache Liquid verwendet, musst du die Designs in diese Sprache umwandeln.

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

  2. Wähle Blank > Code und gib ihm einen Namen. Wir empfehlen, “V2” hinzuzufügen, damit ersichtlich ist, dass du Clerk.js 2 Designs verwendest.

  3. Klicke auf Create Design.

  4. Jetzt bekommst du ein leeres Design mit Produkt-HTML und CSS, das du verwenden kannst.

  5. Gehe zurück zur Design-Übersicht und klicke auf Edit Design für dein Clerk.js 1 Design. Wir empfehlen, dies in einem neuen Tab zu machen, damit du den Code einfach kopieren kannst.

  6. Kopiere dein altes Clerk.js 1 Design in dein neues Clerk.js 2 Design.

    • Du wirst feststellen, dass es keinen Container Code mehr gibt.

    • Das liegt daran, dass Liquid for-loops verwendet, um alle Produkte anzuzeigen.

    • Kopiere deine alte Product-HTML in die for-Schleife, deinen alten Container Code drumherum und kopiere auch das CSS.

  7. Konvertiere das Design in die Syntax von Liquid. Der Hauptunterschied ist, dass die alten Designs die Syntax {{ formatter attribute }} verwendeten, während das v2-Format {{ product.attribute | formatter }} ist.

  8. Gehe alle deine Attribute durch und ändere sie in das neue Format.

  9. Wenn du {{#if}} oder {{#is}} Anweisungen verwendest, müssen diese ebenfalls umgeschrieben werden. Verwende die Syntax {% if product.attribute %} {% else %} {% endif %}.

  10. Lösche id="{{ $id }}" und die Klasse :target aus dem Container-Code in der Clerk.js 2 Version, da diese nicht mehr unterstützt werden.

  11. Nachfolgend ein Beispiel für ein Clerk.js 1 Design und die vollständig konvertierte 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>

  1. Klicke auf Update Design, um die Änderungen zu speichern.

  2. Gehe zu Recommendations/Search > Elements und stelle deinen Element-Block auf das neue Design um.

  3. Klicke auf Update Element. Dadurch werden sie vorübergehend in deinem Webshop nicht angezeigt, bis du mit Schritt 2 fertig bist. Wähle das neue Design für alle relevanten Elemente aus.

Script austauschen #

  1. Finde die Template-Datei, die für alle Seiten des Webshops verwendet wird und in der das ursprüngliche Clerk.js Script sich meist am unteren Ende befindet.

  2. Entferne das alte Clerk.js Script aus der Datei. Es sieht etwa 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 -->

  1. Gehe zu my.clerk.io > Developers > Tracking Code. Dort findest du den Clerk.js 2 Code.

  2. Kopiere diesen Code, füge ihn direkt vor dem </head>-Tag im Template ein und speichere die Datei.

Herzlichen Glückwunsch! Du nutzt jetzt das stark verbesserte Clerk.js 2 Setup!

Die vollständige Dokumentation findest du für Clerk.js 2 hier.

Umgang mit require.js #

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

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

In diesem Fall erscheint im Konsolenfenster folgender Fehler:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Möglichkeiten, Require.js zu handhaben. Für beide musst du den tracking-script anpassen, den du am unteren Ende aller Seiten eingebunden hast.

Einbinden in Require.js #

Der beste Ansatz ist, Require.js dazu zu bringen, Clerk zu erkennen.

Du kannst das erreichen, indem du require(['clerk'], function() {}); ganz am Ende deines Tracking-Skripts einfügst:

Insert Require Clerk.js 1

Require.js ignorieren #

Wenn die obige Lösung nicht funktioniert, kannst du Require.js ignorieren.

Füge dazu window.__clerk_ignore_requirejs = true; ganz oben in das Tracking-Skript ein:

Ignore Require.js

Nachdem du eine dieser Herangehensweisen genutzt hast, ist Require.js nun mit Clerk kompatibel.

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