Jeder (Webshop)

Clerk.js

Integrieren Sie Clerk.io in jedes Frontend mit einer leichtgewichtigen JS-Bibliothek.
Clerk.js

Übersicht #

Clerk.js ist eine JavaScript-Bibliothek, die die Integration unserer API mit dem Frontend vereinfacht. Mit nur 37,7 kb ist sie eine besonders leichte 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ängt, bevor sie geladen wird.
  • Es ist oft schneller, da Ihr Server mit dem Rendern der Seite parallel zu Clerk.js beginnen kann, während Clerk.js API-Aufrufe macht und Ergebnisse rendert.
  • Besucher- und Klick-Tracking wird für alle von Clerk angezeigten Ergebnisse automatisch durchgeführt. Dafür sind keine Cookies erforderlich, da wir einen gehashten Wert der IP-Adresse des Besuchers und des User-Agents generieren, kombiniert mit einem einzigartigen Store-Salt, der alle 30 Tage rotiert.

Clerk.js lädt mit einem Initialisierungsskript, 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 -->

Das Skript lädt die Bibliothek von unserem CDN und ermöglicht den Zugriff über das Clerk-Objekt. Zudem wird Clerk.js mit dem API Key konfiguriert, sodass es bereits weiß, für welchen Store API-Aufrufe erfolgen.

Snippets #

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

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

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

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

Clerk.js verwendet Liquid-Designs, um HTML mit den von der API zurückgegebenen Daten zu rendern. Diese sind als Skripte formatiert, die im Snippet über ihre ID in data-template 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 lediglich eine Referenz auf einen Element-Block über die Syntax data-template="@element-block-id" gesetzt wird:

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

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

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

Injection #

Injection ist ein Feature, das es ermöglicht, Inhaltssnippets auf Ihrer Website einzufügen, ohne dass Sie dies manuell tun müssen. Sie wählen einfach einen CSS-Selector aus, 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 ermöglicht verschiedene Konfigurationen, die das Verhalten beeinflussen.

Um Clerk.js in my.clerk.io zu konfigurieren, öffnen Sie Ihren Store und gehen zu Developers > Clerk.js Config. Passen Sie die Einstellungen an und klicken Sie auf Save.

Diese Einstellungen werden automatisch angewendet, wenn Clerk.js geladen wird. Sie überschreiben keine Werte, die bereits in Ihrem Tracking-Snippet oder der Browser-Konsole gesetzt sind. Änderungen können bis zu 10 Minuten benötigen, um zu greifen.

Besucher-IDs #

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

Wenn Kunden Cookies zustimmen, kann Clerk.js so konfiguriert werden, dass ein persistentes Cookie mit der Besucher-ID gesetzt wird, wodurch ein längerer Tracking-Zeitraum möglich wird.

Möchten Sie die Sitzungs-IDs manuell verwalten, können Sie den Parameter visitor konfigurieren, den Clerk bei API-Aufrufen verwendet. Alternativ können Sie das Session-Tracking ganz deaktivieren, 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
});

Seitenkontext #

Konfiguriert Clerk.js mit dem Kontext der Seite, die ein Besucher aktuell betrachtet. Dies dient dazu, Tracking-Daten für Personalisierungsfunktionen wie Email Triggers, Audience-Segmentierung und Chat-Kontext anzureichern.

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

Kontext kann auch IDs für Empfehlungsblöcke liefern. Siehe Element context settings für die Nutzung mit Injection.

Sprache #

Konfiguriert Clerk.js mit der verwendeten Sprache der Website. Dies wird genutzt, um korrekte Grammatikregeln in Search zu unterstützen und die passenden Übersetzungen zu holen, wenn Sie mehrsprachige Feeds verwenden.

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

Akzeptierte Werte finden Sie unter Supported languages.

Ersetzen Sie die Platzhalterwerte durch die Logik Ihrer Plattform, um die IDs dynamisch zu beziehen. Jeder Wert sollte abhängig vom Seitentyp gesetzt werden, auf dem sich der Besucher befindet:

  • product: Die ID des Produkts auf Produktseiten. Auf Nicht-Produktseiten auf null setzen.
  • category: Die ID der Kategorie auf Kategorieseiten. Auf Nicht-Kategorieseiten auf null setzen.
  • page: Eine Seitenkennung oder ein Typ-String auf anderen Seiten wie Startseite, Warenkorb oder Kasse. Wenn nicht zutreffend, auf null setzen.

Falls Ihre Plattform für einen Seitentyp keine spezifische ID hat, lassen Sie den Wert als null. Setzen Sie Werte nur für relevante Seitentypen.

Designfunktionen #

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

Formatters #

Diese werden verwendet, um Attribute zu beeinflussen oder zu ändern. Beispielsweise möchten Sie vielleicht nur die ersten 40 Zeichen einer Beschreibung anzeigen oder einen bestimmten Rabatt für eingeloggte Kundentypen berechnen.

Globals #

Diese sind für Frontend-Daten gedacht, auf die Sie im Design zugreifen möchten. Beispiele sind der verbleibende Betrag für kostenlosen Versand, der Name eines eingeloggten Kunden, ein Währungssymbol oder ein Wechselkurs.

Unten sehen Sie ein Beispiel für die 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>
Ergebnis #
<div class="name">GREEN LIGHT SABER</div>
<div class="price">$1999.99</div>

Email Tracking #

Clerk.js kann automatisch E-Mails in der Sitzung des Kunden sammeln, um E-Mail-Empfehlungen zu personalisieren, auch wenn noch keine Bestellung erfolgt ist.

Um die automatische E-Mail-Sammlung in my.clerk.io zu aktivieren, öffnen Sie Ihren Store, gehen Sie zu Developers > Clerk.js Config, aktivieren Sie Collect Emails und klicken Sie auf Save.

Alternativ aktivieren Sie collect_email in Ihrer Clerk.js-Konfiguration im Code:

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

Ist dies aktiviert, überwacht Clerk.js E-Mail-Eingabefelder und sendet automatisch log/email, sobald ein Besucher eine E-Mail-Adresse eingibt.

Dadurch wird der Besucher identifiziert; er wird dadurch nicht zu Marketing-Newslettern angemeldet. Siehe Email setup für die Handhabung von Abonnements.

Wenn Sie eine E-Mail manuell loggen möchten, können Sie auch ein Snippet wie dieses hinzufügen:

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

Eingeloggte Kunden #

Falls Ihr Webshop Kundenkonten hat, rufen Sie log/email immer dann auf, wenn eine bekannte E-Mail-Adresse in der Sitzung verfügbar ist — sowohl beim aktiven Login als auch wenn ein Kunde bereits eingeloggt zurückkehrt.

Am einfachsten ist es, bei jedem Seitenaufruf zu prüfen, ob eine E-Mail verfügbar ist. Ist dies der Fall, führen Sie den Aufruf aus. Damit unnötige Aufrufe vermieden werden, speichern Sie ein Flag in der Browser-Session, sodass der Aufruf nur einmal pro Sitzung erfolgt:

<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 E-Mail-Adresse Ihrer Plattform. Rendern Sie dieses Skript nur, wenn eine E-Mail-Adresse verfügbar ist – für Gäste weglassen.

Ohne diese Maßnahme kann Clerk.io die Sitzung eines Besuchers nur dann einer E-Mail-Adresse zuordnen, wenn ein Kauf abgeschlossen wird. Wird immer dann geloggt, wenn eine E-Mail verfügbar ist, erfolgt die Verbindung sofort, was notwendig ist, um automatisierte E-Mails basierend auf dem Surfverhalten auszulösen, personalisierte Empfehlungen in E-Mails anzuzeigen und Merchandising-Kampagnen auf bestimmte Audience-Segmente anzuwenden.

Wie die Zuordnung funktioniert #

Wird eine E-Mail geloggt, sendet Clerk sowohl die Besucher-ID als auch die E-Mail-Adresse an die API, damit sie verbunden werden können.

So kann Clerk nachvollziehen, was dieser Besucher in seiner Session-Historie gemacht hat (zum Beispiel angesehene Produkte, Klicks, Suchanfragen) und dieses Verhalten mit der E-Mail-Adresse verknüpfen.

Mit dieser Verknüpfung kann das gleiche Verhaltensdatenprofil sowohl für E-Mail-Anwendungsfälle (zum Beispiel Trigger- und personalisierte E-Mails) als auch für Onsite-Personalisierung in Empfehlungen für eingeloggte Kunden genutzt werden.

Kontext-Reloads #

Kontext-Reloads halten Empfehlungen relevant, wenn ein Shopper eine Single-Page-App oder einen Headless Store ohne vollständigen Reload durchstöbert. Ein „Beliebt in dieser Kategorie“-Block kann so etwa aktualisiert werden, wenn der Nutzer in eine andere Kategorie springt.

Dies ist standardmäßig aktiviert für Blöcke, deren IDs aus dem Clerk.js-Kontext stammen (id_source: 'context'). Wenn sich ein Kontextwert ändert, rendert Clerk.js bereits initialisierte Blöcke neu, die diesen Schlüssel verwenden — mit dem aktualisierten Wert.

Kontext aktualisieren #

Rufen Sie den public context setter auf, wenn der relevante Wert sich ändert. Etwa nach einer Navigation zur Kategorie 276:

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

Ersetzen Sie 276 durch die Kategorie-ID aus Ihrem Storefront. Der Kontext kann vor oder nach Initialisierung eines Blocks gesetzt werden. Das erneute Setzen des gleichen Werts bewirkt nichts und löst keinen weiteren Reload aus.

Die überwachten Schlüssel sind:

SchlüsselVerhalten
productAktualisiert Blöcke ausgehend vom aktuellen Produkt. Liefert auch die Plural-ID products.
categoryAktualisiert Blöcke ausgehend von der aktuellen Kategorie.
pageAktualisiert Blöcke ausgehend vom aktuellen Seitenkontext.
emailFüllt Blöcke aus oder aktualisiert sie, wenn Kontext „email“ verfügbar wird oder sich ändert.

Observer-Vergleich #

Kontext-Reloads funktionieren auch, wenn DOM-Beobachtung deaktiviert ist. Sie aktualisieren vorhandene Blöcke auf der Seite, wenn ein Wert sich ändert, ohne dass sich das HTML der Seite ändern muss.

DOM-Beobachtung erkennt hinzugefügtes Markup, sodass Clerk.js neu hinzugefügte Blöcke initialisieren und Injections retryen kann, deren Ziel nun vorhanden ist. Dies ist separat aktiviert. Kontext-Reloads benötigen weder MutationObserver, Timer noch DOM-Listener.

Kontext-Event #

Das context-Event ermöglicht Ihnen Reaktionen auf Änderungen im eigenen Frontend. Es wird bei jedem tatsächlichen Kontextwechsel ausgelöst, auch wenn automatische Reloads deaktiviert sind. Das Event gehört zum Kontext, keinem einzelnen Block.

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

Reloads deaktivieren #

Wenn Ihr Frontend diese UI-Updates selbst verwaltet, deaktivieren Sie die automatischen Kontext-Reloads mit:

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

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

In Single-Page-Apps wird beim Wechsel durch popstate und hashchange der gemeinsame Content-and-Injection-Lauf erneut ausgeführt. URL-basierte Injections können erstellt werden, wenn ihre Bedingungen zutreffen, und kontextbezogene Blöcke reloaden bei Wertänderung des Kontextes.

Aktualisieren Sie den Clerk.js-Kontext, wenn der Besucher navigiert, damit die Werte der aktuellen Ansicht entsprechen. Siehe Single-Page-App-Guide für Initialisierung und manuelles Rendering.

Limits #

Blöcke, deren ID aus Seitenelementen stammt sowie Popups, werden durch Kontextänderungen nicht neu geladen.

Während der Injection wird ein Block, dem ein erforderlicher Kontextwert fehlt, so lange übersprungen, bis beim nächsten Injection-Durchlauf ein Wert bereitsteht. Ausnahme: E-Mail-Blöcke können auch ohne E-Mail erstellt und später gefüllt werden.

Eine DOM-Beobachtung kann den Injection-Durchlauf triggern, der einen übersprungenen Block erstellt. Dies ist ein Fallback — unabhängig vom Reload bereits gerenderter Blöcke.

Jeder geänderte Schlüssel erzeugt einen zusätzlichen API-Request. Vermeiden Sie Kontext-Updates in engen Schleifen oder bei jedem Routen-Event, sofern nicht explizit gewünscht.

DOM-Beobachtung #

Aktivieren Sie die DOM-Beobachtung, wenn Ihr Webshop Clerk.io-Inhalte nachträglich auf der Seite einfügt. Clerk.js überwacht Änderungen an der Seitenstruktur („DOM“), um alle später erscheinenden Inhalte zu erfassen.

Sie können dieses Verhalten auch über SPA Auto Detect Changes in my.clerk.io oder durch Hinzufügen von observe_dom: true zur Clerk.js-Konfiguration aktivieren.

Side-Cart-Beispiel #

Angenommen, Ihr Shop erstellt den Side-Cart erst, wenn ein Besucher ein Produkt hinzufügt. Der Cart enthält ein Clerk.io-Empfehlungs-Snippet, welches mit dem Öffnen in die Seite eingefügt wird.

Mit dem timerbasierten Ansatz prüft Clerk.js alle Sekunde auf Änderungen. Die Empfehlung könnte warten, bis der nächste Check ansteht.

Mit observe_dom löst das Hinzufügen des Side-Cart direkt eine Prüfung aus. Clerk.js erkennt das Snippet früher und beginnt zeitnah mit dem Rendern der Empfehlungen, wodurch die Wartezeit nach dem Öffnen des Carts sinkt.

Weitere Beispiele #

Dieses Verhalten ist hilfreich in anderen Szenarien, in denen Inhalte ohne vollständigen Seiten-Reload erscheinen:

  • Add-to-cart-Popup: Der Webshop erstellt nach dem Hinzufügen eines Produkts ein Popup mit Clerk.io-Empfehlungen. Clerk.js erkennt das Popup beim Erstellen.
  • Lazy-loaded-Bereich: Weiter unten auf der Seite wird beim Scrollen ein Clerk.io-Block nachgeladen. Clerk.js erkennt ihn beim Hinzufügen.
  • Single-Page-App: Eine React- oder Vue-App fügt Clerk.io-Inhalte hinzu, wenn der Besucher navigiert. Clerk.js erkennt diese Inhalte sofort, ohne auf einen vollständigen Reload zu warten.

DOM-Beobachtung gilt auch für Content-Blöcke, E-Mail-Formulare und die Live-Suche.

Beobachtung aktivieren #

Wählen Sie eine dieser Möglichkeiten zur Aktivierung der DOM-Beobachtung:

  • Backend: In my.clerk.io Store öffnen, Settings > Features anwählen. SPA Auto Detect Changes aktivieren.
  • Code: Fügen Sie observe_dom: true in Ihre bestehende Clerk.js-Konfiguration ein, siehe Beispiel:
Clerk('config', {
  key: 'INSERT_PUBLIC_API_KEY',
  observe_dom: true
});

Behalten Sie den API-Key und alle weiteren Optionen in Ihrer Konfiguration bei.

Sie müssen trotzdem das passende Clerk.io-Snippet sowie das zugehörige Element und Design konfigurieren. Die Beobachtung hilft Clerk.js lediglich dabei, nachträglich hinzugefügte Inhalte zu erkennen; sie fügt keine Empfehlungssnippets automatisch hinzu.

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

Ressourcenverbrauch #

Clerk.js fasst schnelle Seitenänderungen zu einem Ausführungslauf zusammen und begrenzt vollständige Läufe auf maximal alle 500 ms. Während die Seite inaktiv ist, arbeitet der Observer nicht und verursacht keine zusätzlichen API-Requests oder Netzwerkverkehr.

Die Einstellung ist optional. Stores, die sie nicht aktivieren, behalten das bisherige Verhalten.

Custom Rendering #

Dies wird vor allem in Single-Page-Apps (SPA), Progressive Web Apps (PWA) und anderen Anwendungen verwendet, die ohne klassische Seitenreloads auskommen.

Clerk.js rendert alle Elemente mit der Klasse clerk, jedoch können zur weiteren Individualisierung auch andere Klassen als benutzerdefinierte Selektoren verwendet werden.

Standardmäßig müssen Sie Clerk("content", "SELECTOR") ausführen, um Inhalte jedes Mal auszugeben, wenn sie erscheinen sollen.

Fügen Sie Ihrer Konfiguration auto_init_custom_selectors: true hinzu, damit Clerk.js alle Custom-Selector-Elemente automatisch initialisiert, sobald der DOM sich verändert – solange sie bereits mindestens einmal mit Clerk("content", "SELECTOR") gerendert wurden.

Dieses Verhalten bleibt bis zum nächsten vollständigen Seiten-Reload erhalten.

Debugging #

Clerk.js bietet einen eingebauten Debug-Modus, der Diagnoseinfos in die Browser-Konsole schreibt. Die Konfiguration bleibt in sessionStorage unter dem Schlüssel __clerk_debug erhalten, sodass der Modus auch über mehrere Seitenaufrufe innerhalb derselben Session hinweg aktiv ist.

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

Aktivierungsmöglichkeiten #

Es gibt drei Wege, den Debug-Modus zu aktivieren.

Konsolen-Kurzaufruf

Der einfachste Weg ist der Aufruf von Clerk('debug') in der Browser-Konsole. Es werden mehrere Argumentformen unterstützt:

Clerk('debug');              // Aktiviert mit Standardwerten
Clerk('debug', true);        // Aktiviert
Clerk('debug', false);       // Deaktiviert
Clerk('debug', 'on');        // Aktiviert
Clerk('debug', 'off');       // Deaktiviert
Clerk('debug', 'warn');      // Setzt das Log-Level direkt
Clerk('debug', {             // Komplettes Config-Objekt übergeben
  enable: true,
  level: 'log',
  group: true
});

Config-Pfad

Debug kann auch per Konfigurationsaufruf gesetzt werden:

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

URL-Hash

Debug kann durch Anhängen eines Hashs an die URL aktiviert werden. Das ist praktisch, um Debug-Links mit Kollegen zu teilen:

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

Wird der Modus per Hash aktiviert, wird die Konfiguration ebenfalls in sessionStorage unter dem Schlüssel __clerk_tmp_config gespeichert.

Konfigurationsoptionen #

OptionBeschreibungTypStandardwert
enableAktiviert oder deaktiviert Debug-Nachrichten in der Browser-Konsole.booltrue
levelSetzt das Log-Level. Akzeptierte Werte: log, warn, oder error.stringwarn
collectWird bei true aktiviert, werden Logs im Browser gespeichert. Bei false wird temporär gespeichert.booltrue
groupGruppiert verwandte Log-Nachrichten für bessere Lesbarkeit.bool—
collapsedBei true werden gruppierte Logs standardmäßig zugeklappt (nur bei aktiviertem group).bool—
clearLöscht alle gespeicherten Logs.bool—

SessionStorage #

Wird der Debug-Modus aktiviert, speichert Clerk die Konfiguration unter __clerk_debug in sessionStorage. Dadurch bleiben die Einstellungen beim Navigieren zwischen Seiten erhalten, wirken sich aber nicht auf andere Tabs aus und sind nur auf die aktuelle Session beschränkt.

Consent Management Platforms (CMPs) wie Cookiebot können __clerk_debug als dokumentationspflichtiges Storage-Objekt einstufen. Es handelt sich um einen funktionalen Schlüssel, der ausschließlich Entwicklern beim Debugging dient und keine personenbezogenen Daten oder Tracking-Informationen enthält.

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

UI Kit #

Clerk.js enthält eine Sammlung von UI-Tools für wichtige Elemente, um die Nutzererfahrung zu verbessern. Diese sparen oft Entwicklungszeit bei individuellen Lösungen.

Ein Schlüsselelement für ein starkes E-Commerce-Sucherlebnis ist die sofortige Anzeige von Ergebnissen beim Tippen. Unsere Instant Search UI-Komponente macht diese Nutzererfahrung schnell und einfach umsetzbar.

Jeder Clerk.io-Inhalt kann zum Instant-Search-Component gemacht werden, optimal funktioniert sie als Dropdown für Suchergebnisse.

<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 weiteres zentrales Element für ein positives Sucherlebnis ist das Finden treffender Ergebnisse. Unsere Search Page macht dies einfach umsetzbar.

Die Search Page ermöglicht es, eine vollständige Seite mit den bestmöglichen Treffern für eine beliebige Suchanfrage darzustellen.

<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 zentral für ein erfolgreiches E-Commerce-Business. Unsere Category Page macht dies einfach und schnell umsetzbar. So kann eine komplette Seite mit optimalen Ergebnissen für jede Kategorie gebaut werden.

<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 besitzt eingebaute Unterstützung für dynamische facettierte Navigation sowohl für Suche als auch Kategorien. Alle Produktattribute, die Sie an uns senden, können als Facetten verwendet werden.

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="Suche 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 Website zu verlassen, indem er die Maus zum oberen Rand des Browserfensters bewegt. Es wird eingeblendet und zeigt interessante Produkte – das kann einen abwandernden Besucher noch zum Kauf bewegen.

Jeder Element-Block kann beim Exit-Intent des Besuchers durch das 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.

Das UI Kit enthält eine einfache Popup-Bibliothek, mit der Sie schnell benutzerfreundliche Popups mit beliebigen Inhalten erstellen können. 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 verstecken
  my_popup.hide(); 
  /* oder */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Lesen Sie mehr über das Popup UI-Tool hier.

Chat #

Clerk.js stellt eine JavaScript-Schnittstelle zur Steuerung des Chat-Widgets und zum Reagieren auf Konversations-Events bereit. Das ist nützlich, wenn Sie Chat aus Ihrer eigenen UI heraus triggern, der KI Kontextinformationen zum Nutzerverhalten geben oder Events aus der restlichen Oberfläche abfangen möchten.

Die komplette Methoden- und Event-Referenz finden Sie in den Chat JS Docs.

Chat per Custom Button öffnen #

Wenn Sie Chat aus Ihrem eigenen Button/UI-Element statt dem Standard-Launcher öffnen möchten, verwenden Sie toggle:

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

Sie können auch open und close zur expliziten Steuerung des Status nutzen.

Chat nur auf bestimmten Seiten anzeigen #

Standardmäßig ist Chat seitenweit sichtbar. Um ihn nur auf bestimmten Seiten anzuzeigen, deaktivieren Sie ihn global und aktivieren ihn gezielt:

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

// Dann auf den Seiten, auf denen Sie ihn anzeigen möchten
Clerk('chat', 'enable');

Warenkorb- und Seitenkontext an die KI übergeben #

Die Methode metadata sendet strukturierten Kontext an Chat, damit die KI relevantere Antworten liefert. Rufen Sie es jedes Mal auf, wenn sich der Besucherkontext ändert — etwa bei Navigation, Warenkorbänderungen oder veränderten Präferenzen.

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

// Nachdem ein Produkt in den Warenkorb gelegt 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 Payload-Struktur ist flexibel – fügen Sie den Kontext ein, der für die jeweilige Konversation besonders sinnvoll ist.

KI-Verhalten dynamisch steuern #

Die Methode prompt_message sendet dem KI-System eine Anweisung, die die Antworten für das aktuelle Gespräch steuert. Der Nutzer sieht diese Nachricht nicht, das Verhalten der KI ändert sich aber daraufhin.

// Nach Warenkorb-Update — Cross-Selling anstoßen
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 — Fokus auf Abschluss
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 Agenten #

Wenn ein Besucher menschlichen Support benötigt, wird das Event onSupport mit einer Zusammenfassung der bisherigen Konversation ausgelöst. Nutzen Sie dies, um z.B. einen Helpdesk-Chat zu öffnen und den Kontext zu übergeben – so ist der Agent direkt informiert und der Nutzer 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 || 'No conversation summary available.';

      // Beispiel: Intercom öffnen & Kontext übergeben
      if (window.Intercom) {

Intercom('showNewMessage', 'Fortsetzung vom AI Chat:\n\n' + summary);
      }

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

      // Optional Clerk Chat ausblenden, sobald die Übergabe abgeschlossen 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 anfordert.

Auf Chat-Ereignisse reagieren #

Nutze Event Hooks, um Chat-Verhalten mit dem Rest deines Frontends zu integrieren — zum Beispiel, um Nachrichten zu protokollieren, Zustände zu synchronisieren oder an einen menschlichen Agenten zu übergeben.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onMessage: (e) => {
      // Wird bei jeder Nachricht ausgelöst — role ist 'user', 'ai' oder 'results'
      console.log(e.message.role, e.message.text);
    },
    onOpen: (e) => {
      // Wird ausgelöst, wenn das Chatfenster geöffnet oder geschlossen wird
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Wird ausgelöst, wenn der Besucher einen menschlichen Agenten anfordert
      // e enthält eine Zusammenfassung der Konversation
      openLiveChatWithSummary(e);
    }
  }
});

Du kannst Event Hooks auch nach der initialen Konfiguration dynamisch registrieren:

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

Weitere Informationen findest du in der Chat JS-Dokumentation.

Produkte ausschließen #

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

Bestimmte IDs ausschließen #

Füge einfach das Attribut data-exclude dem Snippet hinzu. Der Inhalt von data-exclude sollte eine Liste der Produkt-IDs sein, die nicht angezeigt werden sollen, also z.B. die 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 wird erreicht, indem das Attribut data-exclude-from am Clerk-Block hinzugefügt wird, wo du das Duplikat entfernen möchtest. Der Wert des Attributs sollte ein CSS-Selektor für das/die 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 enthalten 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 Aufbau maßgeschneiderter Setups musst du häufig auf Ergebnisse von Clerk reagieren oder diese modifizieren, bevor sie gerendert werden. Hierfür sind Events nützlich.

Events ermöglichen es dir, Event-Listener einzurichten, die Code zu bestimmten Zeiten ausführen — vor, während oder nach dem Rendern der Clerk.js-Ergebnisse.

Ein häufiges Beispiel ist das Laden von individuellen Preisen für eingeloggte Kunden in einem B2B-Setup. Ein Event kann direkt nach dem Rendern durch Clerk’s API ausgeführt werden, sodass du individuelle Preise für einen Kunden abrufen und den Produktelementen hinzufügen kannst:

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

Hier erfährst du mehr über die Events.

SEO und Performance #

Clerk.js ermöglicht personalisierte Einkaufserlebnisse, ohne deine Website zu verlangsamen oder SEO zu beeinträchtigen. Durch clientseitiges Rendering und optimiertes Laden werden Geschwindigkeit, Performance und die Sichtbarkeit in Suchmaschinen ausgewogen.

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 deine Seite gerendert wird, während Clerk initialisiert wird.
  • Clerk-Elemente werden clientseitig gerendert, d. h. dein Basis-HTML bleibt cachebar und dynamische Komponenten werden erst nach dem Laden eingefügt.
  • Dies ermöglicht effizientes serverseitiges Caching und nicht-blockierendes Laden der Clerk.js-Assets.

Performance-Auswirkungen #

  • Die schlanke und asynchrone Architektur von Clerk.js führt in der Regel zu minimalen Auswirkungen auf die Seitenladezeiten.
  • In der Praxis resultiert der Performanceverlust meist durch zusätzliche Bilder in Empfehlungen, nicht durch das Skript selbst. Um Auswirkungen zu minimieren:
    • Verwende passende Größen und effiziente Formate wie WebP.
    • Passe die Bildgröße an die Anzeigedimensionen an (z. B. 400×400 px → 420×420 px max).
  • Um Layoutverschiebungen (CLS) zu vermeiden, solltest du Platz für injizierte Clerk-Inhalte reservieren.

Beispiel:

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

SEO-Aspekte #

Zu verstehen, wie Clerk.js mit Suchmaschinen interagiert, hilft sicherzustellen, dass deine Implementierung sowohl die Nutzererfahrung als auch die Sichtbarkeit unterstützt.

Verlinkung und Crawlability #

  • Clerk.js fügt Empfehlungslinks dynamisch auf der Clientseite ein.
  • Diese Links können das interne Verlinken verbessern, indem verwandte Seiten miteinander verbunden werden, sofern Suchmaschinen sie rendern und folgen.
  • Da sie per JavaScript eingefügt werden, solltest du prüfen, wie Suchmaschinen-Crawler sie rendern und interpretieren.
  • Richtig gecrawlte Links können die Crawlability verbessern und Suchmaschinen ermöglichen, mehr Seiten zu entdecken und zu indexieren.

PageRank-Verteilung #

  • Können Suchmaschinen die Links crawlen, helfen Clerk.js-Links, Link-Einfluss (PageRank) auf wichtige Seiten zu verteilen.
  • Dies unterstützt eine bessere Sichtbarkeit und Bewertung von Produkt- und Kategorieseiten.

Beobachtete Vorteile #

  • Die korrekte Clerk.js-Integration kann mit einer stärkeren internen Verlinkungsstruktur korrelieren, was zu einer besseren Sichtbarkeit in Suchergebnissen beitragen kann.
  • Clerk.io Dashboards liefern Analytics zu Bestelleinfluss, Conversion-Steigerung und Umsatzbeitrag von Search, Recommendations, Email und Audience Features.

Empfohlene Best Practices #

  1. Bilder optimieren (WebP-Format, korrekte Auflösung).
  2. Layoutplatz reservieren für dynamische Elemente, um Layoutverschiebungen zu verhindern.
  3. Echte Metriken überwachen statt nur automatisierte Scores zu verwenden. Nutze die Clerk-Dashboards, um Auswirkungen kanalübergreifend zu bewerten.

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