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 sehr leichte Lösung.

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

• Sie ist robust, da sie asynchron geladen wird. Das bedeutet, dass der Rest der Seite nicht von einer API-Antwort vor dem Laden abhängig ist.
• Sie ist oft schneller, da Ihr Server mit dem Rendern der Seite beginnen kann, während Clerk.js Anfragen stellt und Ergebnisse rendert.
• Besucher- und Klicktracking werden für alle von Clerk angezeigten Ergebnisse automatisch gehandhabt. Dies erfordert keine Cookies, da wir einen gehashten Wert der IP-Adresse und des Useragents des Besuchers generieren, kombiniert mit einem eindeutigen Store-Salt, der alle 30 Tage erneuert wird.

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

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
  (function(w,d){
    var e=d.createElement('script');e.type='text/javascript';e.async=true;
    e.src='https://cdn.clerk.io/clerk.js';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
    w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){ w.__clerk_q.push(arguments) };
  })(window,document);

  Clerk('config', {
    key: 'insert_api_key'
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Es lädt die Bibliothek von unserem CDN und ermöglicht den Zugriff auf ihre Funktionen über das Clerk-Objekt und konfiguriert Clerk.js mit dem API-Key, sodass sie bereits weiß, für welchen Store sie API-Anfragen stellt.

Snippets #

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

Dann nutzt es die Attribute aus dem Snippet, um einen API-Aufruf zu erstellen, wobei es den API-Key aus der Konfiguration im Initialisierungsskript erhält.

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

Die Darstellung erfolgt durch das Design, auf das auch im Snippet verwiesen wird.

Clerk.js verwendet Liquid-Designs, um HTML mit den von der API zurückgegebenen Daten zu rendern. Diese sind als Skripte formatiert, auf die in Ihrem Snippet mit ihrer ID in data-template verwiesen wird.

<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 nur einen Verweis auf einen Element-Block mit der Syntax data-template="@element-block-id" enthalten:

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

Designs werden dann mit dem Design Editor oder mit Liquid HTML Code benutzerfreundlich aus my.clerk.io heraus verwaltet.

Ihre Snippets müssen lediglich die Klasse clerk, seiten-spezifische 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 Inhalts-Snippets in Ihre Website einfügen können, ohne sie manuell hinzuzufügen. Stattdessen wählen Sie einfach einen CSS-Selektor 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 seine Funktionsweise ändern.

Besucher-IDs #

Standardmäßig generiert Clerk.js anonyme Besucher-IDs, mit denen die Sitzungen verfolgt werden.

Wenn Kunden Cookies zustimmen, kann Clerk.js so konfiguriert werden, dass ein permanenter Cookie mit der Besucher-ID gesetzt wird, was eine längerfristige Nachverfolgung ermöglicht.

Wenn Sie die Sitzungs-IDs lieber selbst verwalten möchten, können Sie den Parameter visitor konfigurieren, den Clerk in API-Aufrufen verwendet. Alternativ können Sie das Session-Tracking komplett deaktivieren, indem Sie visitor auf null setzen.

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

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

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

Page Context #

Konfiguriert Clerk.js mit dem Kontext der Seite, die ein Besucher gerade ansieht. Dies wird genutzt, um Trackingdaten 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
});

Sprache #

Konfiguriert Clerk.js mit der verwendeten Sprache der Website. Dies wird benötigt, damit Clerk.io die Grammatikregeln in Search richtig handhabt und um die korrekten Übersetzungen abzurufen, wenn Sie mehrsprachige Feeds nutzen.

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

Akzeptierte Werte sind unter den Unterstützten Sprachen gelistet.

Ersetzen Sie die Platzhalter mit der Logik Ihrer Plattform, um die IDs dynamisch zu erhalten. Jeder Wert sollte je nach Seitentyp des Besuchers gesetzt werden:

• product: Die ID des Produkts, das auf Produktseiten angezeigt wird. Auf Nicht-Produktseiten auf null setzen.
• category: Die ID der Kategorie, die auf Kategorieseiten angezeigt wird. Auf Nicht-Kategorieseiten auf null setzen.
• page: Eine Seitenkennung oder Typzeichenkette auf anderen Seiten wie der Startseite, im Warenkorb oder im Checkout. Auf null setzen, falls nicht anwendbar.

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

Design-Funktionen #

Clerk.js unterstützt das Hinzufügen von Formatters und Globals, die genutzt werden können, um eigene JavaScript-Funktionalität für Ihre Designbereiche zu erstellen.

Formatters #

Diese werden eingesetzt, um Attribute zu beeinflussen oder zu verändern. Zum Beispiel könnten Sie nur die ersten 40 Zeichen einer Beschreibung anzeigen lassen oder einen bestimmten Rabattprozentsatz basierend auf dem eingeloggten Kundentyp berechnen.

Globals #

Diese sind dafür gedacht, Frontend-Daten, auf die Sie in Designs zugreifen möchten, bereitzustellen. Beispiele wären der noch verfügbare Betrag bis zum kostenlosen Versand, der Name eines eingeloggten Kunden, ein Währungssymbol oder ein Umrechnungskurs.

Nachfolgend ein Beispiel für die Konfiguration von Formatters und Globals.

Konfiguration #

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

Design #

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

Ausgabe #

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

Email-Tracking #

Clerk.js kann automatisch E-Mails in der Sitzung des Kunden erfassen, um personalisierte E-Mail-Empfehlungen zu ermöglichen, auch 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>

Damit überwacht Clerk.js E-Mail-Eingabefelder und sendet automatisch log/email, wenn ein Besucher eine E-Mail-Adresse eingibt.

Wenn Sie eine E-Mail manuell erfassen 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>

So funktioniert die Zuordnung #

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

Dadurch kann Clerk erkennen, was dieser Besucher in seiner Sitzungshistorie getan hat (z.B. Produkte angesehen, Klicks und Suchanfragen) und dieses Verhalten mit der E-Mail-Adresse verknüpfen.

Mit dieser Zuordnung können dieselben Verhaltensdaten für E-Mail-Anwendungsfälle (wie ausgelöste und personalisierte E-Mails) und für die Onsite-Personalisierung bei Empfehlungen für eingeloggte Kunden genutzt werden.

Custom Rendering #

Dies wird vor allem mit Single Page Apps (SPA), Progressive Web Apps (PWA) und anderen Anwendungen genutzt, bei denen keine klassischen Seitenladevorgänge stattfinden.

Clerk.js rendert alle Elemente mit der Klasse clerk, aber es können auch andere Klassen zum Anpassen des Renderings als Custom Selector verwendet werden.

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

Wenn Sie auto_init_custom_selectors: true zur Konfiguration hinzufügen, initialisiert Clerk.js automatisch alle Custom Selector-Elemente, wenn sich das DOM verändert, solange sie bereits einmal mit Clerk("content", "SELECTOR") gerendert wurden.

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

Debugging #

Clerk.js verfügt über einen eingebauten Debug-Modus, der Diagnoseinformationen in der Browser-Konsole protokolliert. Die Konfiguration wird in sessionStorage unter dem Schlüssel __clerk_debug gespeichert, damit der Debug-Modus während der Navigation innerhalb der Browsersitzung aktiv bleibt.

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

Aktivierungsmethoden #

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

Konsole Kurzschreibweise

Die einfachste Methode ist ein Aufruf von Clerk('debug') in der Browserkonsole. Es werden verschiedene Argument-Formate akzeptiert:

Clerk('debug');              // Aktivieren mit Standardwerten
Clerk('debug', true);        // Aktivieren
Clerk('debug', false);       // Deaktivieren
Clerk('debug', 'on');        // Aktivieren
Clerk('debug', 'off');       // Deaktivieren
Clerk('debug', 'warn');      // Protokolllevel direkt setzen
Clerk('debug', {             // Komplettes Konfigurationsobjekt übergeben
  enable: true,
  level: 'log',
  group: true
});

Config-Pfad

Der Debug-Modus kann auch über den Standard-Konfigurationsaufruf eingestellt werden:

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

URL-Hash

Der Debug-Modus kann durch Anhängen eines Hash-Fragments an die URL aktiviert werden. Dies ist nützlich, um Debug-Links mit Kollegen zu teilen:

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

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

Konfigurations-Optionen #

Session Storage #

Wird der Debug-Modus aktiviert, wird die Konfiguration unter dem Schlüssel __clerk_debug in sessionStorage gespeichert. So bleiben die Debug-Einstellungen beim Navigieren zwischen Seiten erhalten, ohne andere Browser-Tabs zu beeinflussen oder über die jeweilige Sitzung hinaus zu bestehen.

Consent Management Plattformen (CMPs) wie Cookiebot könnten __clerk_debug als erforderlichen Storage-Eintrag markieren. Es handelt sich um einen funktionalen Schlüssel, der ausschließlich für Entwickler-Debugging-Zwecke verwendet wird. Er enthält keine personenbezogenen Daten oder Trackinginformationen.

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

UI Kit #

Clerk.js enthält eine Sammlung von UI-Tools für wichtige Elemente, die das Nutzererlebnis verbessern können. Diese sparen oft Entwicklungszeit für individuelle Setups.

Instant Search #

Ein zentrales Element einer großartigen E-Commerce-Sucherfahrung ist das Erhalten von Ergebnissen, sobald Sie zu tippen beginnen. Unsere Instant Search UI-Komponente macht dieses Nutzererlebnis schnell und einfach.

Jeder Clerk.io-Inhalt kann theoretisch als Instant Search-Komponente verwendet werden, am besten funktioniert es allerdings als Dropdown zur Anzeige von Suchergebnissen.

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

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

Search Page #

Ein zentrales Element einer guten E-Commerce-Sucherfahrung ist das Erhalten relevanter Suchergebnisse. Unsere Search Page macht dieses Nutzererlebnis schnell und einfach.

Die Search Page ermöglicht es Ihnen, eine vollständige Seite anzuzeigen, auf der die besten Treffer für jede beliebige Suchanfrage erscheinen.

<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);">
          		Weitere Ergebnisse anzeigen
    		</div>
    {% endif %}
  </div>
</span>

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

Category Page #

Eine gut strukturierte Kategorieseite ist entscheidend für den E-Commerce-Erfolg. Unsere Category Page macht dieses Nutzererlebnis schnell und einfach. Damit können Sie eine vollständige Seite für das beste Kategorie-Ergebnis erstellen.

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

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

Facetten #

Clerk.js bietet integrierte Unterstützung für dynamische, facettierte Navigation bei Suche und Kategorien. Alle Produkteigenschaften, die Sie übergeben, können als Facetten verwendet werden.

Hier ein Beispiel für eine grundlegende Nutzung:

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

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "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 Ihre Website verlassen möchte, indem er mit der Maus in den oberen Bereich des Browserfensters fährt. Es wird ein Popup angezeigt, das interessante Produkte zeigt und so eventuell einen abspringenden Besucher zum Käufer macht.

Jeder Element-Block kann beim Exit Intent eines Besuchers ausgelöst werden, indem Sie dem Snippet das Attribut data-exit-intent="true" hinzufügen.

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

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

Popup #

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

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

<script type="text/javascript">
  var my_popup = Clerk('ui', 'popup', '#my-popup');
  
  // Popup anzeigen
  my_popup.show(); 
  /* oder */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // Popup ausblenden
  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 bereit und kann auf Konversationsereignisse reagieren. Das ist nützlich, wenn Sie Chat aus Ihrer eigenen UI heraus auslösen, der KI Kontextdaten zum Besucherverhalten übergeben oder in Ereignisse vom Rest Ihres Frontends einhaken möchten.

Die vollständige Methoden- und Ereignisreferenz finden Sie in der Chat JS Dokumentation.

Chat über einen eigenen Button öffnen #

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

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

Sie können auch open und close unabhängig nutzen, um den Status explizit zu steuern.

Chat nur auf bestimmten Seiten anzeigen #

Standardmäßig ist Chat auf der gesamten Website sichtbar. Um ihn nur auf bestimmten Seiten anzuzeigen, deaktivieren Sie ihn in Ihrer globalen Konfiguration und aktivieren ihn selektiv:

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

// Dann auf den Seiten, auf denen Chat sichtbar sein soll
Clerk('chat', 'enable');

Warenkorb- und Seitenkontext an die KI übergeben #

Mit der Methode metadata übergeben Sie strukturierten Kontext an Chat, damit die KI relevantere Antworten geben kann. Rufen Sie sie immer dann auf, wenn sich der Kontext des Besuchers ändert – z.B. beim Navigieren, Hinzufügen zum Warenkorb, Präferenzen aktualisieren.

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

// Nachdem ein Besucher ein Produkt zum Warenkorb hinzugefügt hat
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 – übergeben Sie, was für Konversationen auf der Seite am sinnvollsten ist.

KI-Verhalten auf Basis des Besucherverhaltens anpassen #

Mit der Methode prompt_message senden Sie dem KI-System eine systemweite Anweisung. Der Kunde sieht diese nie, aber sie steuert, wie die KI in der aktuellen Unterhaltung antwortet.

// Nach Hinzufügen zum Warenkorb – Anstoß für KI, Zubehör vorzuschlagen
Clerk('chat', 'prompt_message', 'Der Nutzer hat gerade ein Lightsaber zum Warenkorb hinzugefügt. Schlage passende Zubehörprodukte oder Schutzausrüstung vor.');

// Auf der Checkout-Seite – Fokus auf Abschluss des Kaufs
Clerk('chat', 'prompt_message', 'Der Nutzer ist auf der Checkout-Seite. Helfen Sie, die Bestellung abzuschließen und beantworten Sie letzte Fragen.');

Übergabe an einen menschlichen Support-Agenten #

Wenn ein Besucher menschliche Unterstützung benötigt, wird das Ereignis onSupport mit einer Zusammenfassung der Konversation ausgelöst. Nutzen Sie dies, um Ihren Helpdesk-Chat zu öffnen und den Kontext zu übergeben, damit der Agent sofort Bescheid weiß – der Besucher muss sich nicht wiederholen.

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

      // Beispiel: Intercom öffnen und Kontext vorbelegen
      if (window.Intercom) {
        Intercom('showNewMessage', 'Fortsetzung aus AI Chat:\n\n' + summary);
      }

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

      // Optional Clerk Chat nach Übergabe ausblenden
      Clerk('chat', 'disable');
    }
  }
});

Das Ereignis onSupport wird nur ausgelöst, wenn die Option Kontakt zum Support in den Chat-Einstellungen konfiguriert ist und der Besucher explizit einen Menschen anfordert.

Auf Chat-Ereignisse reagieren #

Nutzen Sie Event-Hooks, um Chat-Verhalten in den Rest Ihres Frontends zu integrieren – z.B. für Logging, Status-Sync oder Weitergabe an einen menschlichen Agenten.

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 beim Öffnen oder Schließen des Chatfensters ausgelöst
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Wird ausgelöst, wenn der Besucher einen menschlichen Agenten wünscht
      // e enthält eine Gesprächszusammenfassung
      openLiveChatWithSummary(e);
    }
  }
});

Sie können Event-Hooks auch nachträglich nach der Initial-Konfiguration registrieren:

Clerk('chat', 'on', 'message', function(e) {
  console.log('Neue Nachricht:', 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 spezifische IDs ausgeschlossen werden sollen oder doppelte Produkte in verschiedenen Slidern vermieden werden sollen.

Bestimmte IDs ausschließen #

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

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

Duplikate vermeiden #

Dies geschieht durch das Hinzufügen des Attributs data-exclude-from im Clerk-Block überall dort, wo Sie das Duplikat entfernen möchten. Der Wert des Attributs sollte ein CSS-Selektor für das/die andere(n) Snippet(s) sein, von denen Sie Duplikate verhindern möchten.

Im folgenden Beispiel schließt .clerk-2 jedes Produkt aus, das in .clerk-1 enthalten ist und .clerk-3 schließt alle Produkte aus, die 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 #

Wenn Sie individuelle Setups bauen, müssen Sie häufig auf die Ergebnisse von Clerk reagieren oder sie vor dem Rendering anpassen. Hierfür sind Events hilfreich.

Events ermöglichen es Ihnen, Event-Listener einzurichten, die zu bestimmten Zeitpunkten vor, während oder nach dem Rendern der Clerk.js-Ergebnisse ausgeführt werden.

Ein häufiges Beispiel ist das Nachladen individueller Preise für eingeloggte Kunden in einem B2B-Setup. Ein Event kann direkt nach dem Rendering der API ausgeführt werden, sodass Sie benutzerdefinierte Preise für einen Kunden abrufen und den Produktelementen anhängen können:

var customer_id = INSERT_CUSTOMER_ID;
Clerk("on", "rendered", function(content, data){
  for (i = 0; i < data.product_data.length; i++) {
      var product = data.product_data[i];
        var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
        let price_container = document.querySelector(`[data-clerk-product-id='${product.id}'] .clerk-price`);
        price_container.innerText = custom_price;
    }
})

Lesen Sie mehr über Events hier.

SEO und Performance #

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

SEO und Geschwindigkeit #

Es ist ein Irrglaube, dass JavaScript-Funktionalitäten wie Clerk.js die Performance oder das SEO negativ beeinflussen. Automatisierte Tools übersehen oft Optimierungen wie Caching, paralleles Laden und serverseitige Verarbeitung.

Vorteile der Clerk.js-Integration #

• Das Clerk.js-Skript (ca. 37–38 KB) wird asynchron geladen, sodass Ihre Seite bereits gerendert wird, während Clerk initialisiert.
• Clerk-Elemente werden clientseitig gerendert, d.h. Ihr Basis-HTML bleibt cachebar und dynamische Komponenten werden erst nach dem Laden eingefügt.
• Das ermöglicht effizientes serverseitiges Caching und nicht-blockierendes Laden der Clerk.js-Ressourcen.

Auswirkungen auf die Performance #

• Durch das geringe Gewicht und die asynchrone Natur von Clerk.js ist der Einfluss auf Ladezeiten meist sehr gering.
• In der Praxis entsteht die größte Performance-Belastung typischerweise durch zusätzliche Produktbilder in Empfehlungen – nicht durch das Skript selbst. Folgende Maßnahmen können helfen:
  • Nutzen Sie Bilder in passender Größe und im effizienten Format wie WebP.
  • Skalieren Sie Bilder auf die Anzeigegröße (z.B. 400×400 px → 420×420 px max.).
• Um Layoutverschiebungen (CLS) zu vermeiden, reservieren Sie Platz für Clerk-Inhalte.

Beispiel:

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

SEO-Aspekte #

Zu verstehen, wie Clerk.js mit Suchmaschinen interagiert, hilft, die Umsetzung sowohl für die Nutzererfahrung als auch für die Sichtbarkeit zu optimieren.

Verlinkung und Crawlability #

• Clerk.js fügt Empfehlungslinks dynamisch clientseitig ein.
• Diese Links können das interne Linking stärken, indem sie relevante Seiten miteinander verbinden – sofern Suchmaschinen diese korrekt rendern und verfolgen.
• Da sie mit JavaScript eingefügt werden, sollten Sie prüfen, wie Search Engine Crawler sie rendern und interpretieren.
• Richtig gecrawlte Links verbessern die Crawlability und ermöglichen Suchmaschinen, mehr Seiten zu entdecken und zu indexieren.

PageRank-Verteilung #

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

Beobachtete Vorteile #

• Eine korrekte Clerk.js-Integration kann mit einer stärkeren internen Linkstruktur korrelieren, was die Sichtbarkeit in den Suchergebnissen unterstützt.
• Clerk.io Dashboards liefern Analysen zu Order-Influence, Conversion-Lift und Umsatzbeitrag durch 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 vermeiden.
3. Echte Nutzungsmetriken überwachen statt sich nur auf automatisierte Scores zu verlassen. Nutzen Sie die Clerk-Dashboards zur Messung der Wirkung über alle Kanäle hinweg.