Clerk.js

Übersicht #

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

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

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

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

Es lädt die Bibliothek von unserem CDN und ermöglicht Zugriff auf deren Funktionen über das Clerk-Objekt und konfiguriert Clerk.js mit dem API-Key, sodass schon bekannt ist, für welchen Store API-Aufrufe erfolgen.

Snippets #

Beim Laden der Seite scannt Clerk.js diese nach Snippets mit der Klasse „clerk“.

Die Attribute aus dem Snippet werden verwendet, um einen API-Aufruf zu erstellen, wobei der API-Key aus der im Initialisierungsskript hinterlegten Konfiguration übernommen wird.

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

Das Design bestimmt das Aussehen, welches ebenfalls im Snippet referenziert wird.

Clerk.js nutzt Liquid Designs, um HTML mit den von der API zurückgegebenen Daten zu rendern. Diese werden als Skripte formatiert, die über ihre ID im data-template in Ihrem Snippet 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 sie einfach auf einen Element Block per data-template="@element-block-id" verweisen:

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

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

Ihre Snippets müssen nur die Klasse clerk, seitenbezogene Informationen wie Produkt-IDs sowie eine Referenz zur ID eines Element Blocks in data-template enthalten.

Injection #

Injection ist ein Feature, mit dem Sie Content-Snippets automatisch auf Ihrer Website einfügen können, ohne sie manuell hinzuzufügen. Stattdessen wählen Sie einfach einen CSS Selector aus, 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 zur Sitzungsverfolgung genutzt werden.

Wenn Kunden Cookies akzeptieren, kann Clerk.js so konfiguriert werden, dass ein persistenter Cookie mit der Besucher-ID gesetzt wird, was ein langfristiges Tracking ermöglicht.

Wenn Sie Sitzungs-IDs lieber manuell verwalten möchten, können Sie den visitor-Parameter konfigurieren, den Clerk in API-Aufrufen verwendet. Alternativ kann das Session-Tracking komplett deaktiviert werden, indem visitor auf null gesetzt wird.

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

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

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

Seitenkontext #

Konfiguriert Clerk.js mit dem Kontext der Seite, die ein Besucher gerade ansieht. Dies wird zur Anreicherung der Trackingdaten für Personalisierungsfunktionen wie Email Triggers, Audience Segmentierung und Chat Kontext verwendet.

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 Typ auf anderen Seiten setzen, z. B. 'homepage' oder null
});

Der Kontext kann auch die IDs liefern, die von Recommendation-Blocks benötigt werden. Siehe Element-Kontext-Einstellungen für die Verwendung mit Injection.

Sprache #

Konfiguriert Clerk.js mit der verwendeten Sprache der Website. Das wird von Clerk.io genutzt, um Grammatikregeln richtig zu behandeln und für den Abruf der richtigen Übersetzungen, wenn Multi-Language-Feeds genutzt werden.

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

Akzeptierte Werte finden Sie unter Unterstützte Sprachen.

Ersetzen Sie Platzhalter-Werte mit Ihrer Logik, um die IDs dynamisch von Ihrer Plattform zu holen. Jeder Wert sollte je nach Seitentyp gesetzt werden, auf der sich der Besucher befindet:

• product: Die ID des angezeigten Produkts auf Produktseiten. Auf Nicht-Produktseiten auf null setzen.
• category: Die ID der angezeigten Kategorie auf Kategorieseiten. Auf Nicht-Kategorie-Seiten auf null setzen.
• page: Eine Seiten-ID oder Typenbezeichnung auf anderen Seiten wie Startseite, Warenkorb oder Kassenseite. Auf null setzen, wenn nicht zutreffend.

Wenn Ihre Plattform für einen Seitentyp keine spezifische ID bietet, lassen Sie den Wert auf null. Setzen Sie Werte nur für relevante Seitentypen.

Design-Funktionen #

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

Formatter #

Diese werden verwendet, um Attribute zu beeinflussen oder zu ändern. Zum Beispiel möchten Sie ggf. nur die ersten 40 Zeichen einer Beschreibung anzeigen oder einen bestimmten Rabattprozentsatz basierend auf dem Kundentyp berechnen lassen.

Globals #

Diese sind für Frontend-Daten vorgesehen, auf die Sie in Designs zugreifen möchten. Beispiele sind: der noch benötigte Betrag für kostenlosen Versand, der Name eines eingeloggten Kunden, ein Währungssymbol oder ein Wechselkurs.

Nachfolgend ein Beispiel zum Konfigurieren 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 Emails in der Session des Kunden erfassen, um Email-Empfehlungen zu personalisieren, selbst wenn noch keine Bestellung aufgegeben wurde.

Aktivieren Sie collect_email in Ihrer Clerk.js-Konfiguration:

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

Mit dieser Funktion überwacht Clerk.js Email-Eingaben und sendet automatisch log/email, wenn ein Besucher eine Email-Adresse eingibt.

Wenn Sie eine Email manuell protokollieren möchten, können Sie auch ein Snippet wie dieses einfügen:

<span class="clerk" data-api="log/email" data-email="EMAIL@EXAMPLE.COM"></span>

Eingeloggte Kunden #

Wenn Ihr Webshop Kundenkonten verwendet, rufen Sie log/email immer dann auf, wenn die Email-Adresse eines bekannten Kunden in der Session verfügbar ist — sowohl beim aktiven Einloggen als auch beim Zurückkehren auf die Seite während eines bestehenden Logins.

Am einfachsten prüfen Sie bei jedem Seitenaufruf, ob eine Email verfügbar ist, und führen bei Bedarf den Aufruf durch. Um unnötige API-Aufrufe zu vermeiden, speichern Sie ein Flag in der Browsersession, das nur einmal pro Session ausgelöst wird:

<script type="text/javascript">
  if (!sessionStorage.getItem('clerk_email_logged')) {
    Clerk('call', 'log/email', {
      email: 'CUSTOMER_EMAIL'
    });
    sessionStorage.setItem('clerk_email_logged', '1');
  }
</script>

Ersetzen Sie CUSTOMER_EMAIL durch die tatsächliche Email-Adresse Ihrer Plattform. Rendern Sie dieses Skript nur, wenn tatsächlich eine Email verfügbar ist — überspringen Sie es für Gäste.

Ohne dies kann Clerk.io die Session eines Besuchers nur mit einer Email-Adresse verknüpfen, wenn ein Kauf abgeschlossen wurde. Die Email direkt zu loggen, sorgt für eine sofortige Verknüpfung, was nötig ist, um automatisierte Emails basierend auf dem Surfverhalten auszulösen, personalisierte Empfehlungen in Emails anzuzeigen und Merchandising-Kampagnen auf bestimmte Audience-Segmente anzuwenden.

Wie die Verknüpfung funktioniert #

Wenn eine Email geloggt wird, sendet Clerk sowohl die Besucher-ID als auch die Email-Adresse an die API, um sie zu verknüpfen.

Dadurch kann Clerk nachvollziehen, was dieser Besucher in seiner Sitzungshistorie getan hat (beispielsweise angesehene Produkte, Klicks und Suchen) und dieses Verhalten mit der Email-Adresse assoziieren.

Mit dieser Verknüpfung können dieselben Verhaltensdaten für Email-Zwecke (wie getriggerte und personalisierte Emails) und für Onsite-Personalisierung in Empfehlungen für eingeloggte Kunden verwendet werden.

Context Reloads #

Kontext-Neuladungen halten Empfehlungen relevant, wenn ein Shopper eine Single-Page-App oder ein Headless-Storefront ohne vollständigen Page-Reload nutzt. Beispielsweise kann sich ein Block „Beliebt in dieser Kategorie“ aktualisieren, sobald der Shopper eine andere Kategorie auswählt.

Dies ist standardmäßig für Blöcke aktiviert, deren IDs aus dem Clerk.js-Kontext stammen (id_source: 'context'). Bei einer Änderung eines Kontextwertes rendert Clerk.js bereits initialisierte Blöcke, die diesen Schlüssel nutzen, mit dem neuen Wert neu.

Kontext aktualisieren #

Rufen Sie den öffentlichen Kontext-Setter auf, wenn sich ein relevanter Wert ändert. Zum Beispiel nach dem Navigieren zu Kategorie 276:

Clerk('context', 'category', '276');

Ersetzen Sie 276 durch die Kategorie-ID Ihres Storefronts. Sie können den Kontext vor oder nach der Initialisierung eines Blocks setzen. Wird derselbe Wert erneut gesetzt, passiert nichts und es wird kein weiteres Reload ausgelöst.

Die beobachteten Schlüssel sind:

Observer-Vergleich #

Kontext-Neuladungen funktionieren sogar, wenn DOM-Beobachtung deaktiviert ist. Sie aktualisieren bereits auf der Seite vorhandene Blöcke, wenn sich ein Wert ändert, ohne dass eine Änderung am HTML der Seite nötig ist.

DOM-Beobachtung erkennt hinzugefügte Markup-Elemente, damit Clerk.js neue Blöcke initialisieren und Injection-Vorgänge wiederholen kann, deren Ziel jetzt aufgetaucht ist. Sie wird separat aktiviert. Kontext-Neuladungen verwenden weder MutationObserver noch Timer oder DOM-Listener.

Kontext-Ereignis #

Verwenden Sie das Ereignis context, um auf Veränderungen im eigenen Frontend zu reagieren. Es wird bei jeder tatsächlichen Kontextänderung ausgelöst, auch wenn automatische Reloads deaktiviert sind. Das Event gehört zum Kontext, nicht zu einem einzelnen Block.

Clerk('on', 'context', ({ key, value, previous, context }) => {
  // Aktualisieren Sie hier Ihre eigene UI bei Bedarf.
});

Reloads deaktivieren #

Wenn Ihr Storefront diese UI-Updates selbst übernimmt, deaktivieren Sie automatische Kontext-Reloads mit:

Clerk('config', 'context_watch', false);

Das context-Event bleibt auch bei deaktivierten Reloads verfügbar.

Navigation #

In Single-Page-Apps führen popstate und hashchange erneut den gemeinsamen Content-und-Injection-Pass aus. URL-basierte Injections können erstellt werden, wenn ihre Bedingungen erfüllt sind, und kontextbasierte Blöcke werden neu geladen, wenn sich ihre Werte geändert haben.

Aktualisieren Sie den Clerk.js-Kontext beim Navigieren des Shoppers, sodass die Werte mit dem aktuellen View übereinstimmen. Siehe Single-Page-App-Guide für Initialisierung und manuelles Rendering.

Einschränkungen #

Blöcke, deren IDs von Seitenelementen stammen, sowie Popups werden durch Kontextänderungen nicht neu geladen.

Während der Injection wird ein Block ohne erforderlichen Kontextwert bis zum nächsten Injection-Durchlauf übersprungen. Ausnahme: Email; Email-Blöcke können erstellt und befüllt werden, sobald eine Email verfügbar wird.

DOM-Beobachtung kann den Injection-Durchlauf anstoßen, der einen übersprungenen Block erstellt. Dieses Fallback ist getrennt vom Neu-Laden eines bereits gerenderten Blocks.

Jeder geänderte Key erzeugt eine zusätzliche API-Anfrage. Vermeiden Sie es, den Kontext in einer engen Schleife oder bei jedem Routen-Event zu aktualisieren, sofern die Wertänderungen nicht beabsichtigt sind.

DOM-Beobachtung #

Aktivieren Sie die DOM-Beobachtung, wenn Ihr Webshop Clerk.io-Content nach dem Laden der Seite einfügt. Clerk.js überwacht Strukturänderungen der Seite (DOM), um Content beim Darstellen zu erkennen.

Dasselbe Verhalten lässt sich auch über SPA Auto Detect Changes in my.clerk.io oder per observe_dom: true in Ihrer Clerk.js-Konfiguration einschalten.

Side Cart Beispiel #

Stellen Sie sich vor, Ihr Webshop erstellt den Warenkorb erst, wenn ein Besucher ein Produkt hinzufügt. Der Warenkorb enthält ein Clerk.io-Empfehlungs-Snippet, sodass das Snippet zur Seite hinzugefügt wird, wenn der Warenkorb geöffnet wird.

Mit dem timerbasierten Ansatz prüft Clerk.js einmal pro Sekunde auf Änderungen. Das Empfehlungssnippet kann bis zum nächsten Check warten, bevor es erkannt wird.

Mit aktiviertem observe_dom löst das Hinzufügen des Side Carts einen Check aus. Clerk.js erkennt das Snippet sofort und beginnt direkt mit dem Rendern der Empfehlungen, wodurch die Wartezeit nach dem Öffnen verkürzt wird.

Weitere Beispiele #

Das gleiche Verhalten hilft auch in anderen Setups, bei denen Content ohne kompletten Reload erscheint:

• Add-to-cart-Popup: Der Webshop erstellt nach dem Hinzufügen eines Produkts ein Popup mit Clerk.io-Empfehlungen. Clerk.js erkennt den neuen Content beim Erstellen des Popups.
• Lazy-loaded Section: Der Webshop fügt weiter unten auf der Seite einen Clerk.io-Block hinzu, während der Besucher scrollt. Clerk.js erkennt und rendert das Snippet, sobald es eingefügt wird.
• Single-Page-App: Eine React- oder Vue-App fügt Clerk.io-Content beim Navigieren zu einer anderen Ansicht hinzu. Clerk.js erkennt neuen Content ohne vollständiges Neuladen.

DOM-Beobachtung gilt auch für Content-Blöcke, Email-Signup-Formulare und Live Search.

Beobachtung aktivieren #

Wählen Sie eine dieser Optionen, um DOM-Beobachtung zu aktivieren:

• Backend: In my.clerk.io, öffnen Sie Ihren Store unter Settings > Features. Aktivieren Sie SPA Auto Detect Changes.
• Code: Fügen Sie observe_dom: true zur bestehenden Clerk.js-Konfiguration hinzu, wie unten gezeigt.

Beide Optionen aktivieren dasselbe Feature – Sie brauchen nur eine davon zu nutzen.

Clerk('config', {
  key: 'INSERT_PUBLIC_API_KEY',
  observe_dom: true
});

Behalten Sie den öffentlichen API-Key Ihres Shops und alle weiteren Konfigurationsoptionen bei.

Sie müssen dennoch das passende Clerk.io-Snippet hinzufügen und dessen Element sowie Design konfigurieren. Die Beobachtung hilft Clerk.js lediglich, später hinzugefügten Content zu erkennen; sie fügt keine Empfehlungselemente auf Ihre Seite ein.

Für manuelles Rendering und eigene Selector siehe Custom Rendering.

Ressourcenverbrauch #

Clerk.js fasst schnelle DOM-Änderungen in einem Durchlauf zusammen und limitiert komplette Durchläufe auf maximal einen alle 500 ms. Die Beobachtung arbeitet nur bei tatsächlichen DOM-Änderungen und verursacht keine zusätzlichen API-Aufrufe oder Netzwerk-Traffic.

Die Einstellung ist opt-in. Shops, die sie nicht aktivieren, behalten ihr bisheriges Verhalten.

Custom Rendering #

Dies wird vor allem mit Single Page Apps (SPA), Progressive Web Apps (PWA) und ähnlichen Anwendungen genutzt, die keine klassischen Seitenaufrufe nutzen.

Clerk.js rendert jedes Element mit der Klasse clerk, aber andere Klassen können als Custom Selector für das Rendering genutzt werden.

Standardmäßig ist erforderlich, Clerk("content", "SELECTOR") aufzurufen, um Content jedes Mal anzuzeigen.

Mit auto_init_custom_selectors: true in der Config initialisiert Clerk.js Custom Selector Elemente automatisch, sobald sich der DOM verändert — vorausgesetzt, sie wurden bereits mit Clerk("content", "SELECTOR") einmal gerendert.

Das Verhalten bleibt bis zu einem kompletten Seiten-Reload bestehen.

Debugging #

Clerk.js verfügt über einen eingebauten Debug-Modus, der Diagnosedaten in der Browser-Konsole ausgibt. Die Konfiguration wird in sessionStorage unter dem Schlüssel __clerk_debug gespeichert, sodass der Debug-Modus über mehrere Seitenaufrufe innerhalb einer Sitzung hinweg aktiv bleibt.

Standardmäßig ist Debug-Modus mit level auf warn und collect auf true aktiv.

Aktivierungsmethoden #

Es gibt drei Möglichkeiten, den Debug-Modus zu aktivieren.

Konsole

Am einfachsten rufen Sie Clerk('debug') in der Browser-Konsole auf. Verschiedene Argumente sind möglich:

Clerk('debug');              // Mit Standardwerten aktivieren
Clerk('debug', true);        // Aktivieren
Clerk('debug', false);       // Deaktivieren
Clerk('debug', 'on');        // Aktivieren
Clerk('debug', 'off');       // Deaktivieren
Clerk('debug', 'warn');      // Log-Level direkt setzen
Clerk('debug', {             // Komplettes Config-Objekt übergeben
  enable: true,
  level: 'log',
  group: true
});

Config-Aufruf

Der Debug-Modus kann auch über den normalen Config-Call gesetzt werden:

Clerk('config', 'debug', {
  enable: true,
  level: 'log',
  collect: true,
  group: true,
  collapsed: false
});

URL-Hash

Sie können den Debug-Modus auch aktivieren, indem Sie einen Hash an die URL anhängen. Praktisch, um Debug-Links mit Kollegen zu teilen:

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

Wird dies über den URL-Hash aktiviert, wird die Konfiguration ebenfalls in sessionStorage unter dem Schlüssel __clerk_tmp_config gespeichert.

Konfigurationsoptionen #

Session Storage #

Beim Aktivieren des Debug-Modus wird die Konfiguration unter dem Schlüssel __clerk_debug in sessionStorage gespeichert. Damit bleibt der Debug-Modus über die ganze Sitzung hinweg erhalten, ohne andere Browser-Tabs oder folgende Sitzungen zu beeinflussen.

Consent Management Plattformen wie Cookiebot können __clerk_debug als dokumentationspflichtigen Speicher identifizieren. Es handelt sich dabei um einen funktionalen Schlüssel ausschließlich für Entwickler-Debugging. Es werden keine personenbezogenen Daten oder Tracking-Informationen gespeichert.

Details zum Aufbau von API-Debug-Responses finden Sie unter Antwort-Debugging.

UI Kit #

Clerk.js enthält eine Reihe von UI-Tools für wichtige Elemente, die das Benutzererlebnis verbessern. Diese sparen häufig Entwicklungszeit bei individuellen Setups.

Instant Search #

Ein wichtiger Bestandteil eines großartigen E-Commerce-Such-Erlebnisses ist es, sofort Ergebnisse zu erhalten, sobald Sie zu tippen beginnen. Unsere Instant Search UI-Komponente macht dieses Benutzererlebnis schnell und leicht umsetzbar.

Jeder Clerk.io-Content kann theoretisch in einen Instant Search-Bereich verwandelt werden, am sinnvollsten ist dies 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 zum Instant Search UI Tool hier.

Search Page #

Ein wichtiger Teil einer guten E-Commerce-Suche ist es, relevante Suchergebnisse zu erhalten. Unsere Search Page ermöglicht so ein Erlebnis auf einfache Weise.

Die Search Page ermöglicht Ihnen, eine ganze Seite zu erstellen, die die bestmöglichen Treffer zu jeder 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>

Mehr zum Search Page UI Tool hier.

Category Page #

Eine gut strukturierte Kategorieseite ist entscheidend für ein erfolgreiches eCommerce-Business. Unsere Category Page macht ein benutzerfreundliches Erlebnis einfach umsetzbar. Damit können Sie eine ganze Seite erstellen, die die besten Ergebnisse einer Kategorie anzeigt.

<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 zum Category Page UI Tool hier.

Facetten #

Clerk.js unterstützt von Haus aus dynamische, facettierte Navigation für Suche und Kategorien. Jedes Produktattribut, das Sie uns senden, kann als Facette verwendet werden.

Hier ein Beispiel einer einfachen 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": "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>

Mehr zum Facetten UI Tool hier.

Exit Intent #

Das Exit-Intent-Popup reagiert, wenn ein Besucher Ihre Seite verlassen will (z. B. indem die Maus zum oberen Rand des Browserfensters bewegt wird). Es öffnet sich und zeigt interessante Produkte an, wodurch ein abspringender Besucher doch noch zum Käufer werden könnte.

Jeder Element-Block kann durch das Hinzufügen von data-exit-intent="true" im Snippet auf Besucher-Exit-Intent reagieren.

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

Popup #

Das UI Kit enthält eine einfache Popup-Bibliothek, um mit beliebigem Inhalt einfach nutzerfreundliche Popups zu erstellen. Jedes HTML-Element mit der Klasse clerk-popup auf Ihrer Website wird als Popup dargestellt.

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

Mehr zum Popup UI Tool hier.

Chat #

Clerk.js stellt eine JavaScript-Schnittstelle für die Steuerung des Chat-Widgets sowie zur Reaktion auf Konversationsereignisse bereit. Das ist nützlich, wenn Sie Chat aus Ihrem eigenen UI aus auslösen, der KI kontextuelle Daten übergeben oder andere Integrationen im Frontend umsetzen möchten.

Die vollständige Methoden- und Event-Referenz finden Sie in den Chat JS Docs.

Chat über eigenen Button öffnen #

Wenn Sie Chat nicht über den Standard-Launcher, sondern über einen eigenen Button oder ein UI-Element öffnen möchten, nutzen Sie toggle:

<button onclick="Clerk('chat', 'toggle')">
  Brauchen Sie Hilfe?
</button>

Sie können open und close zudem unabhängig voneinander steuern.

Chat gezielt auf bestimmten Seiten anzeigen #

Standardmäßig ist Chat auf der gesamten Seite sichtbar. Um ihn nur auf bestimmten Seiten einzublenden, deaktivieren Sie ihn global und aktivieren ihn gezielt:

// In der globalen Clerk.js-Konfiguration — Chat überall verstecken
Clerk('config', { key: 'your-public-api-key' });
Clerk('chat', 'disable');

// Auf ausgewählten Seiten wieder aktivieren
Clerk('chat', 'enable');

Cart- und Seitenkontext an die KI übergeben #

Die Methode metadata überträgt strukturierten Kontext an Chat, sodass die KI individuellere Antworten geben kann. Rufen Sie sie auf, immer wenn sich der Besucher-Kontext ändert — z. B. Seitenwechsel, Warenkorb-Aktualisierung oder Präferenzenänderung.

// Auf einer Produktseite
Clerk('chat', 'metadata', {
  current_page: {
    page_type: 'product',
    page_id: '12345'
  }
});

// Nachdem ein Produkt zum Warenkorb hinzugefügt wurde
Clerk('chat', 'metadata', {
  cart: {
    items: [
      { id: 101, name: 'Lightsaber', price: 99.95 },
      { id: 204, name: 'Force Gloves', price: 29.95 }
    ],
    total: 129.90
  }
});

Die Nutzlast ist flexibel — geben Sie alles mit, was für die aktuelle Konversation hilfreich ist.

KI-Verhalten beeinflussen je nach Besucher-Aktion #

Mit der Methode prompt_message schicken Sie eine Systemanweisung an die KI. Für den Kunden ist das nicht sichtbar, beeinflusst aber die Antworten der KI in der aktuellen Konversation.

// Nach dem Hinzufügen zum Warenkorb – KI zu Cross-Selling anregen
Clerk('chat', 'prompt_message', 'The user just added a Lightsaber to their cart. Suggest complementary products like accessories or protective gear.');

// Auf der Checkout-Seite – auf den Kaufabschluss fokussieren
Clerk('chat', 'prompt_message', 'The user is on the checkout page. Help them complete their order and answer any last-minute questions.');

Übergabe an einen menschlichen Support-Agenten #

Wenn ein Besucher menschlichen Support benötigt, wird das onSupport-Event mit einer Zusammenfassung der Konversation ausgelöst. Damit können Sie Ihren Helpdesk-Chat öffnen und den Kontext übergeben — der Agent ist dadurch sofort informiert und der Besucher muss sich nicht wiederholen.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onSupport: (e) => {
      // e.summary enthält eine Klartext-Zusammenfassung der bisherigen Konversation
      const summary = e.summary || 'Keine Konversationszusammenfassung verfügbar.';

      // Beispiel: Intercom öffnen und Kontext vorbefüllen
      if (window.Intercom) {
        Intercom('showNewMessage', 'Weiter von KI-Chat:\n\n' + summary);
      }

      // Beispiel: Zendesk öffnen und Kontext vorbelegen
      if (window.zE) {
        zE('messenger', 'open');
        zE('messenger:set', 'conversationFields', [
          { id: 'clerk_chat_summary', value: summary }
        ]);
      }

      // Optional Clerk Chat ausblenden, sobald die Übergabe erfolgt ist
      Clerk('chat', 'disable');
    }
  }
});

Das onSupport-Event wird nur ausgelöst, wenn Contact Support in den Chat-Einstellungen konfiguriert ist und der Besucher explizit einen Menschen verlangt.

Auf Chat-Ereignisse reagieren #

Verwenden Sie Event-Hooks, um Chatverhalten mit dem Rest Ihres Frontends zu verknüpfen — zum Beispiel zum Protokollieren von Nachrichten, zum Synchronisieren von Status oder für die Übergabe an einen menschlichen Agenten.

Sie können Ereignishooks auch nach der anfänglichen Konfiguration dynamisch registrieren:

Clerk('chat', 'on', 'message', function(e) {
  console.log('New message:', e.message.text);
});

Lesen Sie mehr in der Chat JS Dokumentation.

Produkte ausschließen #

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

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 enthalten, die nicht angezeigt werden sollen, z.B. Produkte im Warenkorb des Kunden oder eine Liste von Produkten, die sie nicht sehen dürfen.

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

Duplikate vermeiden #

Dies geschieht durch Hinzufügen des Attributs data-exclude-from am jeweiligen Clerk-Block, von dem Sie das Duplikat entfernen möchten. Der Wert des Attributs sollte ein CSS-Selektor für das andere/n Snippet(s) sein, um Duplikate daraus zu verhindern.

Im folgenden Beispiel schließt .clerk-2 jedes Produkt aus, das in .clerk-1 ist, und .clerk-3 schließt Produkte aus, die entweder 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 individuellerer Setups müssen Sie häufig auf Ergebnisse von Clerk reagieren oder diese vor der Ausgabe modifizieren. Hier kommen Events ins Spiel.

Events ermöglichen das Einrichten von Event-Listenern, die Code zu bestimmten Zeiten vor, während oder nach dem Rendern der Ergebnisse von Clerk.js ausführen.

Ein häufiges Beispiel ist das Laden individueller Preise für einen eingeloggten Kunden in einem B2B Setup. Ein Event kann unmittelbar nach Beendigung des API-Renderns von Clerk ausgelöst werden und ermöglicht es, die individuellen Preise für einen Kunden abzurufen 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;
    }
})

Lesen Sie mehr über die Events hier.

SEO und Performance #

Clerk.js ermöglicht personalisierte Einkaufserlebnisse, ohne Ihre Website zu verlangsamen oder das SEO zu beeinträchtigen. Durch die Verwendung von Client-seitigem Rendering und optimiertem Laden wird die Balance aus Geschwindigkeit, Performance und Sichtbarkeit in Suchmaschinen gewährleistet.

SEO und Geschwindigkeit #

Es ist ein Irrglaube, dass JavaScript-Features wie Clerk.js die Performance oder das SEO negativ beeinflussen. Automatisierte Tools übersehen häufig 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 gerendert werden kann, während Clerk initialisiert wird.
• Clerk-Elemente werden clientseitig gerendert, d.h. Ihr grundlegendes HTML bleibt cachebar und die dynamischen Komponenten werden erst nach dem Laden eingebunden.
• Dies ermöglicht effizientes serverseitiges Caching und nicht-blockierendes Laden der Clerk.js-Assets.

Performance-Auswirkungen #

• Die schlanke und asynchrone Natur von Clerk.js führt in der Regel zu minimalen Auswirkungen auf die Ladezeit.
• In der Praxis stammt der meiste Performanceverlust oft von zusätzlichen Bildern, die in Recommendations gerendert werden, nicht vom Skript selbst. Um Auswirkungen zu minimieren:
  • Verwenden Sie angemessene, effiziente Formate wie WebP.
  • Skalieren Sie Bilder auf Darstellungsgröße (z.B. 400×400 px → max. 420×420 px).
• Um Layout-Verschiebungen (CLS) zu vermeiden, reservieren Sie Platz für eingebetteten Clerk-Content.

Beispiel:

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

SEO-Aspekte #

Das Verständnis, wie Clerk.js mit Suchmaschinen interagiert, hilft bei der Sicherstellung, dass Ihre Implementierung sowohl Nutzererfahrung als auch Sichtbarkeit in Suchmaschinen unterstützt.

Verlinkung und Crawlability #

• Clerk.js fügt Recommendation-Links clientseitig dynamisch ein.
• Diese Links können das interne Verlinken verbessern, indem sie verwandte Seiten verbinden, sofern Suchmaschinen diese korrekt rendern und darüber folgen.
• Da sie per JavaScript eingefügt werden, sollten Sie prüfen, wie Suchmaschinen-Crawler diese Links rendern und interpretieren.
• Korrekt gecrawlte Links können die Crawlability erhöhen und gewährleisten, dass Suchmaschinen mehr Seiten entdecken und indexieren.

PageRank-Verteilung #

• Können Suchmaschinen darauf zugreifen, können Clerk.js-Links helfen, Link-Equity (PageRank) auf wichtige Seiten zu verteilen.
• Dadurch werden Sichtbarkeit und Ranking von Produkt- und Kategorieseiten unterstützt.

Beobachtete Vorteile #

• Eine korrekte Clerk.js-Integration kann mit einer besseren internen Verlinkungsstruktur korrelieren, was die Sichtbarkeit in den Suchergebnissen unterstützen kann.
• Clerk.io Dashboards bieten Analysen zu Bestell-Einfluss, Conversion-Lifts und Umsatzbeiträgen von Search, Recommendations, Email und Audience.

Empfohlene Best Practices #

1. Bilder optimieren (WebP-Format, korrekte Auflösung).
2. Platz reservieren für dynamische Elemente, um Layout-Verschiebungen zu verhindern.
3. Echte Leistungsmetriken überwachen und sich nicht allein auf automatische Scores verlassen. Nutzen Sie die Clerk Dashboards, um Auswirkungen in allen Kanälen zu bewerten.