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 super leichte 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ängt, bevor sie geladen wird.
• Sie ist oft schneller, da Ihr Server mit dem Rendern der Seite parallel beginnen kann, während Clerk.js Aufrufe tätigt und Ergebnisse rendert.
• Besucher- und Klick-Tracking werden automatisch für alle von Clerk angezeigten Ergebnisse gehandhabt. Dafür sind keine Cookies erforderlich, da wir einen gehashten Wert aus der IP-Adresse und dem Useragent des Besuchers generieren, kombiniert mit einem einzigartigen Shop-Salz, das alle 30 Tage erneuert wird.

Clerk.js wird mit einem Initialisierungsskript geladen, das im Header der Website hinzugefügt wird:

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

Damit wird die Bibliothek von unserem CDN geladen und Sie können auf deren Funktionen über das Clerk-Objekt zugreifen. Außerdem wird Clerk.js mit dem API-Schlüssel konfiguriert, sodass bereits bekannt ist, für welchen Shop API-Aufrufe getätigt werden.

Snippets #

Wenn die Seite geladen wird, durchsucht Clerk.js sie nach Snippets mit der Klasse “clerk”.

Anschließend werden die Attribute aus dem Snippet verwendet, um einen API-Aufruf zu erstellen, wobei der API-Key aus der Konfiguration im Initialisierungsskript entnommen wird.

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

Das Aussehen wird vom Design gesteuert, das ebenfalls durch das Snippet referenziert wird.

Clerk.js verwendet Liquid-Designs, um HTML mit den von der API zurückgegebenen Daten zu rendern. Diese werden als Skripte formatiert, die per ID im data-template Ihres Snippets referenziert werden.

<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);">Weitere Ergebnisse laden</a>
</script>

Snippets können auch vereinfacht werden, indem nur eine Referenz zu einem Element-Block per Syntax data-template="@element-block-id" eingebunden wird:

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

Ihre Snippets müssen nur die Klasse clerk, seitenbezogene Infos wie Produkt-IDs und eine Referenz zur ID eines Elementblocks im data-template enthalten.

Injection #

Injection ist eine Funktion, mit der Sie Inhalt-Snippets automatisch in Ihre Website einfügen können, ohne sie manuell hinzuzufügen. Sie wählen einfach einen CSS-Selektor, in den das Snippet eingefügt werden soll, und Clerk.js fügt es beim Laden der Seite automatisch ein.

Lesen Sie mehr über Injection hier.

Konfiguration #

Clerk.js erlaubt verschiedene Konfigurationen, die sein Verhalten beeinflussen.

Besucher-IDs #

Standardmäßig generiert Clerk.js anonyme Besucher-IDs, um die Sitzungen zu verfolgen.

Wenn Kunden der Verwendung von Cookies zustimmen, kann Clerk.js so konfiguriert werden, dass ein persistentes Cookie mit der Besucher-ID gesetzt wird, das ein Tracking über einen längeren Zeitraum ermöglicht.

Wenn Sie die Sitzungs-IDs selbst verwalten möchten, können Sie den visitor-Parameter konfigurieren, den Clerk für API-Aufrufe nutzt. Alternativ können Sie das Session-Tracking ganz abschalten, indem Sie visitor auf null setzen.

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

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

// Deaktivieren des Besucher-Trackings
Clerk('config', {
  visitor: null
});

Sprache #

Konfiguriert Clerk.js mit der geschriebenen Sprache der Website. Dies wird von Clerk.io verwendet, um Grammatikregeln korrekt zu handhaben und die richtigen Übersetzungen abzurufen, wenn Sie mehrsprachige Feeds verwenden.

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

Zulässige Werte sind unter Unterstützte Sprachen gelistet.

Designfunktionen #

Clerk.js unterstützt das Hinzufügen von Formattern und Globals, mit denen Sie benutzerdefinierte JavaScript-Funktionalität für Ihre Design-Bereiche erstellen können.

Formatter #

Diese werden zur Beeinflussung oder Änderung von Attributen verwendet. Zum Beispiel möchten Sie vielleicht nur die ersten 40 Zeichen einer Beschreibung anzeigen lassen oder einen bestimmten prozentualen Rabatt berechnen, abhängig vom angemeldeten Kundentyp.

Globals #

Diese sind dafür gedacht, Frontend-Daten zur Verfügung zu stellen, auf die Sie im Design zugreifen wollen. Zum Beispiel den noch benötigten Warenwert für gratis Versand, den Namen des angemeldeten Kunden, das Währungssymbol oder einen Umrechnungskurs.

Im Folgenden ein Beispiel für die Konfiguration von Formattern 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 E-Mails sammeln in der Session des Kunden, um personalisierte E-Mail-Empfehlungen zu bieten, selbst wenn noch keine Bestellung getätigt wurde.

Dies geschieht, indem Clerk.js mit collect_email: true konfiguriert wird, wie hier gezeigt:

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

Damit überwacht Clerk.js alle Eingabefelder der Website und protokolliert diese mit log/email, wenn ein Besucher dort eine E-Mail-Adresse einträgt:

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 Anwendungen ohne klassische Seitenladevorgänge verwendet.

Clerk.js rendert standardmäßig alle Elemente mit der Klasse clerk, aber Sie können für individuelles Rendering auch andere Klassen als Selektoren verwenden.

Standardmäßig müssen Sie Clerk("content", "SELECTOR") aufrufen, um den Inhalt bei jeder gewünschten Anzeige zu rendern.

Durch Hinzufügen von auto_init_custom_selectors: true in der Konfiguration initialisiert Clerk.js automatisch alle Custom Selector-Elemente, sobald sie einmalig mit Clerk("content", "SELECTOR") gerendert wurden, solange sich das DOM verändert.

Dieses Verhalten bleibt bis zu einem vollständigen Seiten-Reload aktiv.

Debugging #

Clerk.js hat einen integrierten Debug-Modus, der Diagnoseinformationen in die Konsole schreibt und für die gesamte Session auch über Seitenaufrufe hinweg erhalten bleibt.

Aktivieren Sie ihn über die Konsole:

Clerk("debug");

Oder per URL-Parameter:

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

Details zum Aufbau der Debug-Antworten finden Sie unter Response debugging.

Der Debugger hat 4 Parameter:

UI Kit #

Clerk.js enthält eine Reihe von UI-Werkzeugen für wichtige Elemente, mit denen Sie das Nutzererlebnis verbessern können. Diese sparen oft Entwicklungszeit bei individuellen Setups.

Instant Search #

Ein zentraler Bestandteil einer großartigen E-Commerce-Such-Erfahrung ist das sofortige Anzeigen der Ergebnisse, sobald der Nutzer zu tippen beginnt. Unsere Instant Search UI-Komponente ermöglicht genau dieses schnelle und einfach zu realisierende Nutzererlebnis.

Jeder Clerk.io-Inhalt kann theoretisch in eine Instant-Search-Komponente umgewandelt werden, aber am besten funktioniert sie als Dropdown, das Suchergebnisse anzeigt.

<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 zentrales Element einer erfolgreichen E-Commerce-Sucherfahrung ist es, gute Suchergebnisse zu erzielen. Unsere Search Page macht dieses Nutzererlebnis schnell und leicht umsetzbar.

Die Search Page ermöglicht eine komplette Seite, die die besten Ergebnisse zu einer bestimmten Suche 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 entscheidend für erfolgreiche Online-Shops. Unsere Category Page macht dieses Nutzererlebnis schnell und einfach umsetzbar. Sie bietet eine ganze Seite, die die besten Ergebnisse für eine beliebige Kategorie zeigt.

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

Facets #

Clerk.js kommt mit integrierter Unterstützung für dynamische, facettierte Navigation für sowohl Suche als auch Kategorien. Alle Produktattribute, die Sie bereitstellen, können als Facetten genutzt werden.

Hier ein Beispiel für die Grundnutzung:

<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": "PRICE-TRANSLATION", "categories": "CATEGORIES-TRANSLATION", "brand": "BRAND-TRANSLATION"}'
  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 die Seite verlassen möchte, indem er den Mauszeiger zum oberen Rand des Browserfensters bewegt. Es öffnet sich und zeigt interessante Produkte an, was die Chance erhöht, dass der Besucher noch etwas kauft.

Jeder Elementblock kann bei Exit Intent mit dem Attribut data-exit-intent="true" im Snippet ausgelöst werden.

<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, mit der Sie benutzerfreundliche Popups mit beliebigem Inhalt erstellen können. Jedes HTML-Element 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 ausblenden
  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 bestimmte IDs ausnehmen oder doppelte Produkte in verschiedenen Slidern vermeiden möchten.

Spezifische 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. die 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>

Doppelte Produkte vermeiden #

Dies geschieht durch das Hinzufügen des Attributs data-exclude-from im jeweiligen Clerk-Block, dessen Duplikate vermieden werden sollen. Der Wert des Attributs sollte ein CSS-Selektor für die anderen Snippets sein, die ausgeschlossen werden sollen.

Im Beispiel unten schließt .clerk-2 alle Produkte aus, die in .clerk-1 sind, und .clerk-3 schließt alle Produkte aus, 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 #

Wenn Sie individuellere Setups erstellen, müssen Sie häufig auf die Ergebnisse von Clerk reagieren oder diese vor dem Rendern anpassen. Hier kommen Events ins Spiel.

Mit Events können Sie Event-Listener einrichten, die zu bestimmten Zeitpunkten vor, während oder nach dem Rendern von Clerk.js-Inhalten ihren Code ausführen.

Ein häufiges Beispiel ist das Laden individueller Preise für eingeloggte Kunden in einer B2B-Umgebung. Ein Event kann sofort nach dem Rendering der Clerk-API ausgeführt werden, um eigene Preise zu laden und diese den Produktelementen hinzuzufügen:

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 die SEO zu beeinträchtigen. Durch Client-Side-Rendering und optimiertes Laden wird ein Gleichgewicht aus Geschwindigkeit, Leistung und Sichtbarkeit erreicht.

SEO und Geschwindigkeit #

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

Vorteile der Clerk.js-Integration #

• Das Clerk.js-Skript (≈ 37–38 KB) wird asynchron geladen, sodass Ihre Seite anzeigen kann, während Clerk initialisiert.
• Clerk-Elemente werden clientseitig gerendert, das Basis-HTML bleibt cachebar, und dynamische Komponenten werden erst nach dem Laden injiziert.
• Dies ermöglicht effizientes serverseitiges Caching und nicht-blockierendes Laden der Clerk.js-Assets.

Performance-Auswirkung #

• Das leichte und asynchrone Clerk.js führt typischerweise nur zu geringen Beeinträchtigungen der Ladezeit.
• In der Praxis rührt Performance-Einbußen meist von zusätzlichen Bildern in Empfehlungen und nicht vom Skript selbst. Um die Auswirkungen zu minimieren:
  • Verwenden Sie effizient formatierte Bilder wie WebP.
  • Passen Sie die Bildgröße exakt an die Anzeige an (z. B. 400×400 px → max. 420×420 px).
• Um Layout-Verschiebungen (CLS) zu vermeiden, reservieren Sie Platz für geinjektete Clerk-Inhalte.

Beispiel:

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

SEO-Aspekte #

Wenn Sie verstehen, wie Clerk.js mit Suchmaschinen interagiert, können Sie sicherstellen, dass Ihre Implementierung sowohl Nutzer als auch Sichtbarkeit unterstützt.

Verlinkung und Crawlability #

• Clerk.js injiziert Empfehlungslinks dynamisch clientseitig.
• Diese Links können das interne Linking verbessern, indem verwandte Seiten miteinander verbunden werden, sofern Suchmaschinen sie erkennen und folgen.
• Da diese JavaScript-injiziert sind, sollten Sie prüfen, wie Suchmaschinen diese rendern und interpretieren.
• Korrekt gecrawlte Links verbessern die Crawlability und ermöglichen Suchmaschinen, weitere Seiten zu entdecken und zu indexieren.

PageRank-Verteilung #

• Wenn Suchmaschinen sie crawlen können, helfen Clerk.js-Links dabei, Link Equity (PageRank) auf wichtige Seiten zu verteilen.
• Dies unterstützt eine verbesserte Sichtbarkeit und das Ranking von Produkt- und Kategorieseiten.

Beobachtete Vorteile #

• Eine korrekte Clerk.js-Integration kann mit stärkeren internen Verlinkungsstrukturen korrelieren, die die Sichtbarkeit in den Suchergebnissen fördern können.
• Clerk.io-Dashboards bieten Analysen über den Bestell-Einfluss, Conversion-Lifts und Umsatzbeiträge von Search, Recommendations, Email und Audience.

Empfohlene Best Practices #

1. Optimieren Sie Bilder (WebP-Format, korrekte Auflösung).
2. Reservieren Sie Platz im Layout für dynamische Inhalte zur Vermeidung von Layout-Verschiebungen.
3. Beobachten Sie reale Messwerte statt sich ausschließlich auf automatisierte Scores zu verlassen. Verwenden Sie die Clerk-Dashboards, um Effekte über alle Kanäle hinweg zu bewerten.