Clerk.js

Übersicht #

Clerk.js ist eine JavaScript-Bibliothek, die die Integration unserer API mit dem Frontend vereinfacht. Mit nur 37,7kb ist sie eine extrem schlanke Lösung.

Es gibt drei Vorteile bei der Verwendung von Clerk.js:

• Sie ist robust, da sie asynchron geladen wird. Das bedeutet, dass der Rest der Seite nicht von einer API-Antwort abhängig ist, bevor er geladen wird.
• Sie ist häufig schneller, da Ihr Server mit dem Rendern der Seite gleichzeitig beginnen kann, während Clerk.js Anfragen stellt und Ergebnisse rendert.
• Besucher- und Klick-Tracking werden automatisch für alle von Clerk angezeigten Ergebnisse durchgeführt. Dies erfordert keine Cookies, da wir einen gehashten Wert aus der IP-Adresse und dem Useragent des Besuchers erzeugen, kombiniert mit einem einzigartigen Store-Salt, das alle 30 Tage rotiert.

Clerk.js wird mit einem Initialisierungsskript im Header der Website geladen:

<!-- 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_api_key'
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Es lädt die Bibliothek von unserem CDN und ermöglicht Ihnen den Zugriff auf ihre Funktionalitäten über das Clerk-Objekt und konfiguriert Clerk.js mit dem API Key, sodass bereits bekannt ist, für welchen Store API-Aufrufe gemacht werden.

Snippets #

Nachdem die Seite geladen ist, durchsucht Clerk.js sie nach Snippets mit der Klasse „clerk“.

Es verwendet dann die Attribute aus dem Snippet, um einen API-Aufruf zu erstellen, wobei der API Key aus der config im Initialisierungsskript entnommen wird.

<span
  class="clerk"
  data-api="recommendations/popular"
  data-limit="10"
  data-template="@clerk-product-template">
</span>

Die Darstellung wird vom Design übernommen, das im Snippet ebenfalls referenziert wird.

Clerk.js verwendet Liquid-Designs, um HTML mit den von der API zurückgegebenen Daten zu rendern. Diese sind als Scripts formatiert und werden innerhalb Ihres Snippets über ihre ID im data-template referenziert.

<span class="clerk"
     data-api="search/search"
     data-query="jedi"
     data-limit="20"
     data-template="#clerk-template">
</span>

<script type="text/x-template" id="clerk-template">
  <h1>Suchergebnis für {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Jetzt kaufen</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Mehr Ergebnisse laden</a>
</script>

Snippets können auch vereinfacht werden, indem einfach auf einen Content-Block verwiesen wird, mit der Syntax data-template="@content-block-id":

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

Designs werden dann mit dem Design Editor oder mit Liquid HTML Code benutzerfreundlich über my.clerk.io bearbeitet.

Ihre Snippets müssen nur die Klasse clerk, etwaige seitenbezogene Informationen wie Produkt-IDs und einen Verweis auf die ID eines Content-Blocks in data-template enthalten.

Injection #

Injection ist eine Funktion, mit der Sie Inhalts-Snippets auf Ihrer Website einfügen können, ohne diese manuell hinzufügen zu müssen. Sie wählen stattdessen einfach einen CSS-Selektor, in den das Snippet eingefügt werden soll, und Clerk.js fügt es beim Laden der Seite automatisch hinzu.

Weitere Informationen zu Injection finden Sie hier.

Konfiguration #

Clerk.js ermöglicht verschiedene Konfigurationen, die das Verhalten beeinflussen.

Besucher-IDs #

Standardmäßig generiert Clerk.js anonyme Besucher-IDs, die zur Nachverfolgung der Sitzungen verwendet werden.

Wenn Kunden Cookies akzeptieren, kann Clerk.js so konfiguriert werden, dass es ein persistentes Cookie mit der Besucher-ID setzt, um ein langfristiges Tracking zu ermöglichen.

Wenn Sie die Sitzungs-IDs lieber manuell verwalten möchten, können Sie den visitor-Parameter konfigurieren, den Clerk für API-Aufrufe verwendet. Alternativ können Sie das Session-Tracking vollständig abschalten, indem Sie visitor auf null setzen.

// Persistente Besucher-ID
Clerk('config', {
  visitor: 'persistent'
});

// Eigene Besucher-ID
Clerk('config', {
  visitor: 'ABC123'
});

// Besucher-Tracking deaktivieren
Clerk('config', {
  visitor: null
});

Sprache #

Konfiguriert Clerk.js mit der verwendeten Sprache der Website. Dies wird von Clerk.io für Grammatikregeln in Search sowie für das Abrufen der passenden Übersetzungen bei mehrsprachigen Feeds benötigt.

Clerk('config', {
  language: 'italian'
});

Zulässige Werte finden Sie unter Unterstützte Sprachen.

Design-Funktionen #

Clerk.js unterstützt das Hinzufügen von Formatters und Globals, die verwendet werden können, um benutzerdefinierte JavaScript-Funktionen für Ihre Design-Bereiche zu erstellen.

Formatters #

Diese werden verwendet, um Attribute zu beeinflussen oder zu verändern. Zum Beispiel möchten Sie vielleicht nur die ersten 40 Zeichen einer Beschreibung anzeigen, oder Sie benötigen einen spezifischen Rabatt-Prozentsatz basierend auf dem Kundentyp.

Globals #

Diese sind für Frontend-Daten gedacht, die Sie in Designs zugänglich machen möchten. Dies könnten z.B. der verbleibende Betrag bis zum kostenlosen Versand, der Name eines angemeldeten Kunden, ein Währungssymbol oder ein Umrechnungskurs sein.

Nachfolgend ein Beispiel zur Konfiguration von Formatters und Globals.

Config #

Clerk('config', {
  formatters: {
    uppercase: function(string) {
        return string.toUpperCase();
    }
  },
  globals: {
    currency_symbol: '$'
  }
});

Design #

<div class="name">{{ product.name | uppercase }}</div>
<div class="price">{{ currency_symbol }}{{ product.price }}</div>

Ausgabe #

<div class="name">GREEN LIGHT SABER</div>
<div class="price">$1999.99</div>

Email Tracking #

Clerk.js kann automatisch Emails sammeln in der Session des Kunden, um E-Mail-Empfehlungen zu personalisieren, auch wenn noch keine Bestellung getätigt wurde.

Dies geschieht durch die Konfiguration von Clerk.js mit collect_email: true wie hier gezeigt:

<script type="text/javascript">
  Clerk('config', {
    key: 'insert_api_key',
    collect_email: true
  });
</script>

Damit überwacht Clerk.js alle Eingabefelder auf der Website und protokolliert beim Schreiben einer Email-Adresse mit log/email:

https://api.clerk.io/v2/log/email?payload={"email":"test@test.com","key":"insert_api_key","visitor":"auto"}

Custom Rendering #

Dies wird hauptsächlich bei Single Page Apps (SPA), Progressive Web Apps (PWA) und anderen Apps verwendet, bei denen kein traditioneller Seitenaufruf erfolgt.

Clerk.js rendert alle Elemente mit der Klasse clerk, aber andere Klassen können genutzt werden, um die Darstellung über eigene Selektoren anzupassen.

Standardmäßig müssen Sie Clerk("content", "SELECTOR") ausführen, sobald der Inhalt angezeigt werden soll.

Wenn Sie auto_init_custom_selectors: true zur Konfiguration hinzufügen, initialisiert Clerk.js automatisch alle benutzerdefinierten Selektor-Elemente, sobald sich der DOM ändert, sofern sie bereits einmal mit Clerk("content", "SELECTOR") gerendert wurden.

Dieses Verhalten bleibt bestehen, bis ein vollständiges Seiten-Reload stattfindet.

Debugging #

Clerk.js verfügt über einen integrierten Debug-Modus, der Diagnoseinformationen an die Konsole ausgibt.

Aktivieren Sie ihn über die Konsole:

Clerk("debug");

Oder aktivieren Sie ihn über URL-Parameter:

https://yourwebsite.com/#clerkjs:debug.level=all&debug.enable=true

Weitere Details zur Struktur der API-Debug-Antworten finden Sie unter Response debugging.

Der Debugger hat 4 Parameter:

UI Kit #

Clerk.js beinhaltet eine Sammlung von UI-Tools für wichtige Elemente, mit denen sich das Nutzererlebnis verbessern lässt. Diese sparen häufig Entwicklungszeit für individuelle Setups.

Instant Search #

Ein wichtiges Element für ein großartiges E-Commerce-Sucherlebnis ist das sofortige Anzeigen von Ergebnissen beim Tippen. Unsere Instant Search UI-Komponente macht dieses Nutzererlebnis schnell und leicht umsetzbar.

Jeder Clerk.io-Inhalt kann theoretisch als Instant Search-Komponente dargestellt werden, am besten eignet es sich jedoch als Dropdown mit Suchergebnissen.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
  data-labels='["Instant Search"]'
      
  data-instant-search="INSERT_CSS_SELECTORS_HERE">
  
  <dl class="product-search-result-list">
    <dt>Produkte passend zu <i>{{ query }}</i></dt>
    
    {% for product in products %}
      <dd class="product clerk-instant-search-key-selectable">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Jetzt kaufen</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Lesen Sie mehr über das Instant Search UI Tool hier.

Search Page #

Ein wichtiger Bestandteil für ein großartiges E-Commerce-Sucherlebnis ist, gute Suchergebnisse zu erhalten. Unsere Search Page macht dieses Nutzererlebnis schnell und einfach umsetzbar.

Die Search Page ermöglicht es, eine vollständige Seite zu erstellen, die die bestmöglichen Treffer für eine bestimmte Suchanfrage anzeigt.

<span 
  class="clerk"
  
  data-api="search/search"
  data-limit="40"
  data-labels='["Search Page"]'
  data-query="INSERT_QUERY_HERE"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">>
  
  <div class="product-search-result-list">
    <div>Produkte passend zu <i>{{ query }}</i></div>
    
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Jetzt kaufen</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mehr Ergebnisse anzeigen
    		</div>
    {% endif %}
  </div>
</span>

Lesen Sie mehr über das Search Page UI Tool hier.

Category Page #

Eine gut strukturierte Kategorieseite ist der Schlüssel zu einem erfolgreichen E-Commerce-Business. Unsere Category Page macht dieses Nutzererlebnis schnell und einfach umzusetzen. Damit können Sie eine vollständige Seite mit den besten möglichen Ergebnissen für eine Kategorie erstellen.

<span 
  class="clerk"
  
  data-api="recommendations/category/popular"
  data-limit="40"
  data-labels='["Category Page Grid"]'
  data-category="INSERT_CATEGORY_ID"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">
  
  <div class="product-category-result-list">
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Jetzt kaufen</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mehr Ergebnisse anzeigen
    		</div>
    {% endif %}
  </div>
</span>

Lesen Sie mehr über das Category Page UI Tool hier.

Facetten #

Clerk.js verfügt über eine integrierte Unterstützung für dynamische, facettierte Navigation bei Suche und Kategorien. Alle Produkteigenschaften, die Sie an uns senden, können als Facetten verwendet werden.

Hier ein Beispiel für die grundlegende Nutzung:

<div id="clerk-search-filters"></div>

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "PREIS-ÜBERSETZUNG", "categories": "KATEGORIEN-ÜBERSETZUNG", "brand": "MARKE-ÜBERSETZUNG"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="Mehr anzeigen"
  data-facets-searchbox-text="Suchen nach "
  data-facets-design="133995">
</span>

Lesen Sie mehr über das Facets UI Tool hier.

Exit Intent #

Das Exit Intent Popup reagiert, wenn ein Besucher versucht, Ihre Seite zu verlassen, indem er den Mauszeiger in den Bereich nahe des oberen Browserfensters bewegt. Es öffnet sich und zeigt interessante Produkte an – möglicherweise wird so ein abwandernder Besucher doch noch zu einem Käufer.

Jeder Content-Block kann beim Exit Intent des Besuchers ausgelöst werden, indem dem Snippet das Attribut data-exit-intent="true" hinzugefügt wird.

<span
  class="clerk"
  
  data-api="recommendations/visitor/complementary"
  data-limit="20"
  data-labels='["Exit Intent / Popup"]'
  
  data-exit-intent="true">
</span>

Lesen Sie mehr über das Exit Intent UI Tool hier.

Popup #

Das UI Kit enthält eine einfache Popup-Bibliothek, um unkompliziert benutzerfreundliche Popups mit beliebigen Inhalten zu erstellen. Jedes HTML-Element auf Ihrer Website mit der Klasse clerk-popup wird als Popup angezeigt.

<div id="my-popup" class="clerk-popup">Hallo, Welt!</div>

<script type="text/javascript">
  var my_popup = Clerk('ui', 'popup', '#my-popup');
  
  // Popup anzeigen
  my_popup.show(); 
  /* oder */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // Popup verbergen
  my_popup.hide(); 
  /* oder */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Lesen Sie mehr über das Popup UI Tool hier.

Produkte ausschließen #

Clerk.js bietet zwei verschiedene Möglichkeiten, Produkte auszuschließen – je nachdem, ob Sie spezifische IDs ausschließen oder doppelte Produkte zwischen verschiedenen Slidern vermeiden möchten.

Bestimmte IDs ausschließen #

Fügen Sie einfach das Attribut data-exclude zum Snippet hinzu. Der Inhalt von data-exclude sollte eine Liste der Produkt-IDs sein, die nicht angezeigt werden sollen – z.B. Produkte im Warenkorb des Kunden oder Produkte, die er nicht sehen darf.

<span class="clerk"
  data-template="@clerk-complementary"
  data-exclude="[45654, 3244, 12352]">
</span>

Duplikate vermeiden #

Dies geschieht durch das Hinzufügen des Attributs data-exclude-from am Clerk Block, in dem Sie das Duplikat entfernen möchten. Der Wert sollte ein CSS-Selektor für das/die andere(n) Snippet(s) sein, von denen Duplikate entfernt werden sollen.

Im folgenden Beispiel schließt .clerk-2 alle Produkte aus, die in .clerk-1 sind, und .clerk-3 alle, die in .clerk-1 oder .clerk-2 sind.

<span class="clerk clerk-1"
  data-template="@clerk-banner-1">
</span>
 
<span class="clerk clerk-2"
  data-exclude-from=".clerk-1"
  data-template="@clerk-banner-2">
</span>
 
<span class="clerk clerk-3"
  data-exclude-from=".clerk-1,.clerk-2"
  data-template="@clerk-banner-3">
</span>

Events #

Beim Erstellen individueller Setups ist es oft nötig, auf Ergebnisse von Clerk zu reagieren oder diese vor dem Rendern zu modifizieren. Hier kommen Events ins Spiel.

Events ermöglichen das Setzen von Event-Listenern, die zu bestimmten Zeitpunkten vor, während oder nach dem Rendern von Clerk.js-Ergebnissen ausgeführt werden.

Ein häufiges Beispiel ist das Laden individueller Preise für eingeloggte Kunden im B2B-Bereich. Ein Event kann direkt nach dem Rendern der Clerk API ausgeführt werden, sodass Sie eigene Preise abrufen und diese den Produktelementen hinzufügen können:

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;
    }
})

Lesen Sie mehr über Events hier.

SEO und Performance #

Clerk.js ermöglicht personalisierte Einkaufserlebnisse, ohne Ihre Seite zu verlangsamen oder das SEO zu beeinträchtigen. Durch clientseitiges Rendering und optimiertes Laden wird die Balance zwischen Geschwindigkeit, Leistung und Sichtbarkeit in Suchmaschinen gehalten.

SEO und Geschwindigkeit #

Es ist ein Irrglaube, dass JavaScript-Features wie Clerk.js die Performance oder das SEO verschlechtern. Automatisierte Tools übersehen häufig Optimierungen wie Caching, paralleles Laden und serverseitige Behandlung.

Vorteile der Clerk.js-Integration #

• Das Clerk.js Script (≈ 37 - 38 KB) lädt asynchron, sodass Ihre Seite rendern kann, während Clerk initialisiert.
• Clerk-Elemente werden clientseitig gerendert, sodass Ihr Basis-HTML cachebar bleibt und dynamische Komponenten erst nach dem Laden eingefügt werden.
• Dadurch sind effizientes serverseitiges Caching und nicht-blockierendes Laden der Clerk.js-Assets möglich.

Performanz-Auswirkung #

• Die schlanke und asynchrone Arbeitsweise von Clerk.js hat in der Regel nur geringen Einfluss auf die Ladezeiten.
• Der Leistungseinbruch in der Praxis entsteht meist durch zusätzliche Bilder in Empfehlungen, nicht durch das Skript selbst. Um die Auswirkung zu minimieren:
  • Verwenden Sie möglichst kleine, effiziente Formate wie WebP.
  • Passen Sie die Bildgröße an die Anzeige-Dimensionen an (z. B. 400×400 px → maximal 420×420 px).
• Um Layoutverschiebungen (CLS) zu vermeiden, reservieren Sie Platz für injizierte Clerk-Inhalte.

Beispiel:

.clerk-slider-wrapper {
  min-height: 300px; /* ggf. anpassen */
  width: 100%;
}

SEO-Überlegungen #

Das Verständnis, wie Clerk.js mit Suchmaschinen interagiert, hilft bei der Sicherstellung sowohl eines guten Nutzererlebnisses als auch der Sichtbarkeit in Suchergebnissen.

Verlinkung und Crawlbarkeit #

• Clerk.js fügt Empfehlungs-Links dynamisch auf der Client-Seite ein.
• Diese Links können die interne Verlinkung verbessern, wenn Suchmaschinen diese korrekt rendern und folgen.
• Da sie per JavaScript eingefügt werden, sollten Sie prüfen, wie Suchmaschinen-Bots deren Rendering und Interpretation vornehmen.
• Korrekt gecrawlte Links können die Crawlbarkeit steigern und Suchmaschinen ermöglichen, mehr Seiten zu entdecken und zu indexieren.

PageRank-Verteilung #

• Wenn Suchmaschinen die Links crawlen können, helfen Clerk.js-Links, den Linkjuice (PageRank) auf wichtige Seiten zu verteilen.
• Dies unterstützt die bessere Auffindbarkeit und das Ranking von Produkt- und Kategorieseiten.

Beobachtete Vorteile #

• Eine korrekte Clerk.js-Integration kann mit einer stärkeren internen Verlinkungsstruktur korrelieren, was die Sichtbarkeit in Suchergebnissen unterstützt.
• Clerk.io Dashboards bieten Analysen zum Bestell-Einfluss, Conversion-Uplifts und Umsatzbeiträgen aus Search, Recommendations, Email und Audience Features.

Empfohlene Best Practices #

1. Optimieren Sie Bilder (WebP-Format, passende Auflösung).
2. Reservieren Sie Platz im Layout für dynamische Elemente, um Layoutverschiebungen zu vermeiden.
3. Überwachen Sie reale Metriken anstatt nur automatisierter Scores. Nutzen Sie die Clerk-Dashboards zur Bewertung der Wirkung über verschiedene Kanäle hinweg.