Clerk.js

Überblick #

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

Die Verwendung von Clerk.js bietet drei Vorteile:

• Sie ist robust, da sie asynchron geladen wird. Das bedeutet, dass der Rest der Seite nicht auf eine API-Antwort warten muss, bevor er geladen wird.
• Sie ist häufig schneller, da Ihr Server mit dem Rendern der Seite beginnen kann, während Clerk.js Aufrufe macht und Ergebnisse rendert.
• Besucher- und Klick-Tracking wird automatisch für alle durch Clerk angezeigten Ergebnisse übernommen. Dafür sind keine Cookies nötig, da wir einen gehashten Wert aus IP-Adresse und Useragent des Besuchers generieren, kombiniert mit einem einzigartigen Shop-Salt, der 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 stellt die Funktionen über das Clerk Objekt zur Verfügung, und konfiguriert Clerk.js mit dem API-Schlüssel, sodass bekannt ist, für welchen Store API-Aufrufe gemacht werden.

Snippets #

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

Anschließend werden die Attribute aus dem Snippet genutzt, um einen API-Aufruf zu erstellen, wobei der API-Schlüssel aus der Konfiguration im Initialisierungsskript übernommen wird.

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

Die Darstellung wird vom Design übernommen, auf das auch im Snippet verwiesen wird.

Clerk.js verwendet Liquid Designs, um HTML mit den von der API gelieferten Daten zu rendern. Diese sind als Scripts formatiert und werden über ihre ID im data-template Ihres Snippets 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 nur ein Verweis auf einen Element-Block verwendet wird, mit der Syntax data-template="@element-block-id":

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

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

Ihre Snippets müssen lediglich die Klasse clerk, seitenbezogene Infos wie Produkt-IDs und einen Verweis auf die ID eines Element-Blocks in data-template enthalten.

Injection #

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

Lesen Sie mehr über Injection hier.

Konfiguration #

Clerk.js ermöglicht verschiedene Konfigurationen, die die Funktionsweise beeinflussen.

Besucher-IDs #

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

Stimmen Kunden der Verwendung von Cookies zu, kann Clerk.js so konfiguriert werden, dass ein persistentes Cookie mit der Besucher-ID gesetzt wird, wodurch das Tracking über einen längeren Zeitraum möglich ist.

Wenn Sie Sitzungs-IDs lieber selbst verwalten wollen, können Sie den Parameter visitor festlegen, den Clerk in API-Aufrufen verwendet. Alternativ kann die Sitzungsverfolgung komplett deaktiviert werden, indem visitor auf null gesetzt wird.

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

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

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

Seitenkontext #

Konfiguriert Clerk.js mit dem Kontext der Seite, die ein Besucher aktuell ansieht. Dies dient der Anreicherung der Tracking-Daten für Personalisierungs-Features wie Email Triggers, Audience Segmentierung und Chat Kontext.

Clerk('context', {
  product: null,  // Produkt-ID auf Produktseiten setzen, z. B. 12345 oder null
  category: null, // Kategorie-ID auf Kategorieseiten setzen, z. B. 67 oder null
  page: null      // Seiten-ID oder Seitentyp auf anderen Seiten, z. B. 'homepage' oder null
});

Sprache #

Konfiguriert Clerk.js mit der Sprache der Website. Dadurch kann Clerk.io Grammatikregeln in Search korrekt anwenden und die richtigen Übersetzungen abrufen, wenn Sie mehrsprachige Feeds nutzen.

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

Akzeptierte Werte finden Sie unter Unterstützte Sprachen.

Ersetzen Sie die Platzhalterwerte mit der Logik Ihrer Plattform, um die IDs dynamisch zu erhalten. Jeder Wert sollte auf Basis des jeweils angezeigten Seitentyps vergeben werden:

• product: Die ID des auf der Produktseite angezeigten Produkts. Bei allen anderen Seitentypen auf null setzen.
• category: Die ID der auf der Kategorieseite angezeigten Kategorie. Bei allen anderen Seitentypen auf null setzen.
• page: Eine Seitenkennung oder ein Typ als String auf anderen Seiten wie Startseite, Warenkorb oder Kasse. Auf null setzen, sofern nicht relevant.

Wenn Ihre Plattform keine bestimmte ID für einen Seitentyp vorhält, belassen Sie den Wert bei null. Setzen Sie Werte nur für die relevanten Seitentypen.

Design-Funktionen #

Clerk.js unterstützt das Hinzufügen von Formattern und Globals, die zur Erstellung benutzerdefinierter JavaScript-Funktionalitäten für Ihre Design-Bereiche genutzt werden können.

Formatter #

Diese werden verwendet, um Attribute zu beeinflussen oder zu verändern. Sie können etwa nur die ersten 40 Zeichen einer Beschreibung anzeigen oder einen spezifischen Rabatt für eingeloggte Kunden berechnen.

Globals #

Diese sollen mit Frontend-Daten verwendet werden, auf die Sie im Design zugreifen möchten. Beispiele sind: der noch fehlende Betrag für kostenlosen Versand, der Name eines eingeloggten Kunden, ein Währungssymbol oder ein Umrechnungskurs.

Nachfolgend sehen Sie 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 in der Session des Kunden erfassen, um Personalisierungen für Email-Empfehlungen zu ermöglichen, auch wenn noch keine Bestellung erfolgt ist.

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 auf der Website und protokolliert dies mit log/email, wenn ein Besucher eine Email-Adresse in eines der Felder eingibt:

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

Custom Rendering #

Dies wird vor allem mit Single Page Apps (SPA), Progressive Web Apps (PWA) oder anderen Anwendungen genutzt, die keine klassischen Seitenladungen verwenden.

Clerk.js rendert alle Elemente mit der Klasse clerk, aber andere Klassen können als benutzerdefinierte Selektoren für das Rendering verwendet werden.

Standardmäßig müssen Sie Clerk("content", "SELECTOR") ausführen, um Inhalte jedes Mal zu rendern, wenn diese angezeigt werden sollen.

Wenn Sie auto_init_custom_selectors: true in der Konfiguration setzen, initialisiert Clerk.js automatisch alle benutzerdefinierten Selektor-Elemente, sobald sich der DOM ändert – vorausgesetzt, sie wurden zuvor mit Clerk("content", "SELECTOR") mindestens einmal gerendert.

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

Debugging #

Clerk.js verfügt über einen eingebauten Debug-Modus, der Diagnosedaten in der Konsole protokolliert und für die gesamte Session über Seitenwechsel hinweg aktiv bleibt.

Sie aktivieren ihn in der Konsole:

Clerk("debug");

Oder aktivieren ihn via 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 beinhaltet eine Reihe von UI-Werkzeugen für wichtige Elemente, mit denen Sie die Benutzererfahrung verbessern können. Diese sparen oft Entwicklungszeit bei individuellen Setups.

Instant Search #

Ein zentraler Bestandteil einer guten E-Commerce-Suche ist, dass Ergebnisse sofort während der Eingabe angezeigt werden. Unsere Instant Search UI-Komponente ermöglicht genau dieses schnelle und einfach umsetzbare Nutzererlebnis.

Jeder Clerk.io-Content kann theoretisch als Instant-Search-Komponente genutzt werden, am besten funktioniert es 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>

Mehr zur Instant Search UI finden Sie hier.

Search Page #

Ein zentraler Bestandteil einer guten E-Commerce-Suche ist, relevante Suchergebnisse zu liefern. Unsere Search Page ermöglicht genau dieses schnelle Nutzererlebnis durch die Anzeige der bestmöglichen Treffer.

Die Search Page ermöglicht Ihnen, eine ganze Seite zu erstellen, die alle relevanten Treffer zu einer Suchanfrage zeigt.

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

Mehr zur Search Page UI finden Sie hier.

Category Page #

Eine gut strukturierte Kategorieseite ist essentiell für erfolgreiche Online-Shops. Unsere Category Page ermöglicht genau dieses schnelle Nutzererlebnis für eine ganze Seite mit den besten Treffern für eine Kategorie.

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

Mehr zur Category Page UI finden Sie hier.

Facetten #

Clerk.js unterstützt dynamische facettierte Navigation sowohl für Suche als auch für Kategorien. Alle Produktattribute, die Sie uns senden, können als Facetten verwendet werden.

Hier ein einfaches Anwendungsbeispiel:

<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="View More"
  data-facets-searchbox-text="Search for "
  data-facets-design="133995">
</span>

Mehr zur Facetten UI finden Sie hier.

Exit Intent #

Das Exit-Intent-Popup reagiert, wenn ein Besucher versucht, Ihre Seite zu verlassen, indem er den Mauszeiger in Richtung Browserleiste bewegt. Es wird eingeblendet und zeigt interessante Produkte – so kann ein abwandernder Besucher doch noch zum Käufer werden.

Jeder Element-Block kann bei Exit-Intent angezeigt werden, wenn Sie das Attribut data-exit-intent="true" im Snippet hinzufügen.

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

Mehr zum Exit Intent UI-Tool finden Sie hier.

Popup #

Das UI Kit enthält eine simple Popup-Library, mit der Sie unkompliziert nutzerfreundliche 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">Hello, world!</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>

Mehr zum Popup UI-Tool finden Sie hier.

Produkte ausschließen #

Clerk.js bietet zwei unterschiedliche Möglichkeiten, Produkte auszuschließen – je nachdem, ob Sie bestimmte IDs ausklammern wollen oder doppelte Produkte in mehreren Slidern vermeiden möchten.

Bestimmte IDs ausschließen #

Fügen Sie dem Snippet einfach das Attribut data-exclude hinzu. Der Inhalt von data-exclude ist eine Liste der Produkt-IDs, die nicht angezeigt werden sollen, z. B. Produkte im Warenkorb oder Produkte, die dem Kunden nicht angezeigt werden dürfen.

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

Duplikate vermeiden #

Das geschieht durch das Attribut data-exclude-from am betreffenden Clerk-Block. Der Wert ist ein CSS-Selektor für die anderen Snippets, von denen die Duplikate ausgeschlossen werden sollen.

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

Bei individuelleren Setups müssen Sie möglicherweise auf Ergebnisse von Clerk reagieren oder diese vor dem Rendern modifizieren. Genau dafür sind Events hilfreich.

Events erlauben das Einrichten von Event-Listenern, die Code zu bestimmten Zeitpunkten vor, während oder nach dem Rendern von Clerk.js-Ergebnissen ausführen.

Ein klassisches Beispiel: Sie möchten individuelle Preise für eingeloggte B2B-Kunden laden. Ein Event kann direkt nach dem API-Render von Clerk ausgeführt werden, um kundenspezifische Preise zu holen und zu 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;
    }
})

Mehr zu Events hier.

SEO und Performance #

Clerk.js ermöglicht personalisierte Einkaufserlebnisse, ohne Ihre Website zu verlangsamen oder das SEO zu beeinträchtigen. Durch Client-Side-Rendering und optimiertes Laden werden Geschwindigkeit, Performance und Sichtbarkeit in Suchmaschinen ausbalanciert.

SEO und Geschwindigkeit #

Es ist ein Irrglaube, dass JavaScript-Features wie Clerk.js die Performance oder das SEO beeinträchtigen. Automatisierte Tools übersehen oft 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 Site gerendert werden kann, während Clerk initialisiert.
• Clerk-Elemente werden clientseitig gerendert, Ihr Basis-HTML bleibt also cachefähig und dynamische Komponenten werden erst nach dem Laden injiziert.
• Das ermöglicht effizientes serverseitiges Caching und nicht-blockierendes Laden der Clerk.js-Assets.

Performance-Auswirkung #

• Das geringe Gewicht und asynchrone Laden von Clerk.js führen in der Regel zu minimalen Auswirkungen auf Ihre Ladezeiten.
• In der Praxis stammt ein möglicher Geschwindigkeitseinbruch meist von zusätzlichen Bildern in Empfehlungen, nicht vom Script selbst. Um die Auswirkungen minimal zu halten:
  • Nutzen Sie geeignete, effiziente Formate wie WebP.
  • Passen Sie die Größe an die Anzeige an (z. B. 400×400 px → max. 420×420 px).
• Um Layout-Verschiebungen (CLS) zu vermeiden, reservieren Sie Platz für den injizierten Clerk-Content.

Beispiel:

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

SEO-Aspekte #

Das Verständnis, wie Clerk.js mit Suchmaschinen interagiert, hilft, eine Umsetzung zu wählen, die Nutzererlebnis und Sichtbarkeit vereint.

Verlinkung und Crawlability #

• Clerk.js injiziert Empfehlungslinks dynamisch clientseitig.
• Diese Links können das interne Linking verbessern, indem sie relevante Seiten verbinden – sofern Suchmaschinen sie korrekt darstellen und folgen.
• Da sie per JavaScript injiziert werden, sollten Sie überprüfen, wie Suchmaschinen-Crawler diese rendern und interpretieren.
• Richtig gecrawlte Links verbessern die Crawlability und ermöglichen Suchmaschinen, mehr Seiten zu entdecken und zu indexieren.

PageRank-Vererbung #

• Wenn Suchmaschinen sie crawlen können, helfen Clerk.js-Links, die Link-Equity (PageRank) auf wichtige Seiten zu verteilen.
• Dies trägt zu besserer Sichtbarkeit und Ranking Ihrer Produkt- und Kategorieseiten bei.

Beobachtete Vorteile #

• Eine korrekte Clerk.js-Integration kann mit einer stärkeren internen Verlinkung korrelieren, was die Sichtbarkeit in Suchergebnissen verbessern kann.
• Clerk.io Dashboards liefern Analytics zu Order-Influence, Conversion-Lift und Umsatzbeitrag von Search, Recommendations, Email und Audience-Features.

Empfohlene Best Practices #

1. Bilder optimieren (WebP-Format, richtige Auflösung).
2. Layout-Platz reservieren für dynamische Elemente, um Layout-Verschiebungen zu verhindern.
3. Echte Nutzermetriken überwachen und nicht auf reine Audit-Scores verlassen. Verwenden Sie Clerk-Dashboards, um den kanalübergreifenden Einfluss zu messen.