Clerk.js

Überblick #

Clerk.js ist eine JavaScript-Bibliothek, die die Integration unserer API mit dem Frontend vereinfacht. Mit nur 37,7 kb ist sie eine äußerst schlanke Lösung.

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

• Sie ist robust, da sie asynchron geladen wird. Das bedeutet, dass der Rest der Seite nicht von einer API-Antwort abhängig ist, bevor geladen wird.
• Sie ist häufig schneller, da Ihr Server mit dem Rendering der Seite parallel beginnen kann, während Clerk.js Abfragen macht und Ergebnisse rendert.
• Besucher- und Klick-Tracking wird automatisch für alle von Clerk angezeigten Ergebnisse durchgeführt. Dafür sind keine Cookies erforderlich, da wir einen gehashten Wert aus der IP-Adresse und dem Useragent des Besuchers generieren, kombiniert mit einem einzigartigen Store-Salt, das alle 30 Tage rotiert.

Clerk.js wird mit einem Initialisierungsskript im Header der Website geladen:

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

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

Dabei wird die Bibliothek von unserem CDN geladen und Sie können alle Funktionen über das Clerk-Objekt nutzen. Clerk.js wird mit dem API-Key konfiguriert, sodass sie bereits weiß, für welchen Store sie API-Aufrufe macht.

Snippets #

Nach dem Laden der Seite durchsucht Clerk.js diese nach allen Snippets mit der Klasse “clerk”.

Anschließend nutzt sie die Attribute des Snippets, um einen API-Aufruf zu erstellen, wobei der API-Key aus der Konfiguration im Initialisierungsskript entnommen wird.

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

Das Design wird im jeweiligen Snippet referenziert und steuert die Darstellung.

Clerk.js verwendet Liquid-Designs, um HTML mit den von der API gelieferten Daten zu rendern. Diese werden als Skripte formatiert und durch ihre ID in data-template im Snippet referenziert.

<span class="clerk"
     data-api="search/search"
     data-query="jedi"
     data-limit="20"
     data-template="#clerk-template">
</span>

<script type="text/x-template" id="clerk-template">
  <h1>Suchergebnis für {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Jetzt kaufen</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Weitere Ergebnisse laden</a>
</script>

Snippets lassen sich auch vereinfachen, indem Sie nur einen Verweis auf einen Element-Block mittels der Syntax data-template="@element-block-id" angeben:

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

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

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

Injection #

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

Lesen Sie mehr über Injection hier.

Konfiguration #

Clerk.js bietet eine Vielzahl von Konfigurationsmöglichkeiten, die Funktionsweise anpassen.

Besucher-IDs #

Standardmäßig generiert Clerk.js anonyme Besucher-IDs, um Sessions zu tracken.

Wenn Kunden der Verwendung von Cookies zustimmen, kann Clerk.js so konfiguriert werden, dass ein persistentes Cookie mit der Besucher-ID gesetzt wird. Dadurch ist ein Tracking über längere Zeiträume möglich.

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

// Permanente 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 ansieht. Das wird genutzt, um 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, z. B. 'homepage' oder null
});

Sprache #

Konfiguriert Clerk.js mit der verwendeten Sprache der Website. Dadurch kann Clerk.io Grammatikregeln in Search korrekt handhaben und die passenden Übersetzungen laden, wenn Sie mehrsprachige Feeds verwenden.

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

Akzeptierte Werte finden Sie unter Unterstützte Sprachen.

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

• product: Die ID des Produkts auf Produktseiten. Auf anderen Seiten auf null setzen.
• category: Die ID der Kategorie auf Kategorieseiten. Auf anderen Seiten auf null setzen.
• page: Ein Seitenbezeichner oder Typ-String auf Seiten wie Homepage, Warenkorb oder Checkout. Auf null setzen, wenn nicht relevant.

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

Design-Funktionen #

Clerk.js unterstützt das Hinzufügen von Formatters und Globals, um benutzerdefinierte JavaScript-Funktionalitäten in Ihren Design-Scopes zu ermöglichen.

Formatters #

Mit ihnen können Sie Attribute beeinflussen oder verändern. Beispielsweise möchten Sie vielleicht nur die ersten 40 Zeichen einer Beschreibung anzeigen oder müssen einen bestimmten Rabattprozentsatz basierend auf dem eingeloggten Kundentyp berechnen.

Globals #

Diese sind dazu gedacht, Frontend-Daten, die Sie im Design benötigen, bereit zu stellen. Beispiele: Restbetrag für kostenlosen Versand, Name eines eingeloggten Kunden, Währungssymbol oder Umrechnungskurs.

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

Ausgabe #

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

Email-Tracking #

Clerk.js kann automatisch Emails innerhalb der Session des Kunden erfassen, um personalisierte Email-Empfehlungen zu ermöglichen, auch wenn der Kunde noch keine Bestellung aufgegeben hat.

Aktivieren Sie collect_email in Ihrer Clerk.js-Konfiguration:

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

Wenn aktiviert, überwacht Clerk.js Email-Eingabefelder und sendet automatisch log/email, sobald ein Besucher eine Email-Adresse eingibt.

Sie können eine Email auch manuell loggen, indem Sie ein Snippet wie dieses verwenden:

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

Eingeloggte Kunden #

Wenn Ihr Webshop Kundenkonten unterstützt, rufen Sie log/email immer dann auf, wenn die Email-Adresse eines bekannten Kunden in der Session zur Verfügung steht — sowohl beim aktiven Login als auch, wenn er bereits eingeloggt zurückkehrt.

Der einfachste Ansatz besteht darin, bei jedem Seitenaufruf zu prüfen, ob eine Email-Adresse verfügbar ist, und in dem Fall den Aufruf zu machen. Um unnötige API-Aufrufe zu vermeiden, speichern Sie ein Flag in der Browsersession, sodass es nur einmal pro Session ausgeführt 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 ausschließlich, wenn wirklich eine Email-Adresse vorhanden ist – überspringen Sie es für Gäste.

Andernfalls kann Clerk.io den Besuch einer Session nur mit einer Email-Adresse verknüpfen, wenn tatsächlich eine Bestellung abgeschlossen wird. Durch das Logging, sobald eine Email verfügbar ist, ist die Verbindung sofort hergestellt – das ist nötig, um automatisierte Emails basierend auf dem Surfverhalten auszulösen, personalisierte Empfehlungen in Emails anzuzeigen und Merchandising-Kampagnen auf bestimmte Audience-Segmente anzuwenden.

So funktioniert die Zuordnung #

Beim Logging einer Email sendet Clerk sowohl die Besucher-ID als auch die Email-Adresse an die API, sodass sie verknüpft werden können.

So kann Clerk erkennen, was dieser Besucher in seiner Session-Historie getan hat (z. B. angesehene Produkte, Klicks, Suchen) und dieses Verhalten der Email-Adresse zuordnen.

Mit dieser Verbindung können dieselben Verhaltensdaten für Email-Fälle (z. B. getriggerte und personalisierte Emails) und für Onsite-Personalisierung in Empfehlungen für eingeloggte Kunden genutzt werden.

Custom Rendering #

Diese Funktion wird primär bei Single Page Apps (SPA), Progressive Web Apps (PWA) und anderen Anwendungen genutzt, die keine klassischen Seitenladevorgänge verwenden.

Clerk.js rendert standardmäßig alle Elemente mit der Klasse clerk, es können aber auch andere Klassen als Custom Selector verwendet werden.

Standardmäßig müssen Sie Clerk("content", "SELECTOR") aufrufen, um Inhalte immer dann zu rendern, sobald Sie angezeigt werden sollen.

Wenn Sie auto_init_custom_selectors: true zur Config hinzufügen, initialisiert Clerk.js automatisch alle Custom Selector-Elemente bei Änderungen im DOM, sobald sie mindestens einmal mit Clerk("content", "SELECTOR") gerendert wurden.

Dieses Verhalten bleibt bestehen, bis ein kompletter Seiten-Reload erfolgt.

Debugging #

Clerk.js besitzt einen integrierten Debug-Modus, der Diagnoseinformationen in der Browserkonsole protokolliert. Die Konfiguration wird in sessionStorage unter dem Schlüssel __clerk_debug gespeichert, wodurch der Debug-Modus über Seitenwechsel hinweg erhalten bleibt, solange alles im selben Tab läuft.

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

Aktivierungsmethoden #

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

Console shorthand

Am einfachsten rufen Sie im Browser-Console Clerk('debug') auf. Akzeptiert diverse Argumentformate:

Clerk('debug');              // Aktivieren mit Standardwerten
Clerk('debug', true);        // Aktivieren
Clerk('debug', false);       // Deaktivieren
Clerk('debug', 'on');        // Aktivieren
Clerk('debug', 'off');       // Deaktivieren
Clerk('debug', 'warn');      // Direktes Log-Level setzen
Clerk('debug', {             // Komplette Config übergeben
  enable: true,
  level: 'log',
  group: true
});

Config-Weg

Der Debug-Modus lässt sich auch per Standardkonfiguration festlegen:

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

URL-Hash

Per Hash-Fragment am Ende der URL kann der Debug-Modus ebenso aktiviert werden. Ideal, um Debug-Links mit Kollegen zu teilen:

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

Wird Debug so aktiviert, bleibt die Konfiguration auch per sessionStorage unter __clerk_tmp_config erhalten.

Konfigurationsoptionen #

Session Storage #

Wird der Debug-Modus aktiviert, wird die Konfiguration als __clerk_debug im sessionStorage hinterlegt. So bleibt das Debug-Setting beim Wechseln von Seiten erhalten, wirkt sich aber nicht auf andere Tabs/Browsersessions aus und bleibt nicht länger als die Session erhalten.

Consent-Management-Plattformen (CMPs) wie Cookiebot könnten __clerk_debug als Speicher-Item kennzeichnen, für das Dokumentationspflichten bestehen. Es handelt sich dabei um einen technisch notwendigen Schlüssel, ausschließlich für Entwicklerdebugging. Er enthält keine personenbezogenen Daten oder Tracking-Informationen.

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

UI Kit #

Clerk.js enthält ein Set von UI-Tools für wichtige Elemente, mit denen Sie die Nutzererfahrung verbessern können. Diese sparen häufig Entwicklungszeit bei Custom-Setups.

Instant Search #

Ein zentrales Element einer guten E-Commerce-Sucherfahrung ist es, sofort Ergebnisse zu sehen, sobald man tippt. Unsere Instant Search UI-Komponente ermöglicht diese Experience schnell und einfach aufzubauen.

Jeder Clerk.io-Inhalt kann theoretisch als Instant Search-Komponente genutzt werden, am besten funktioniert es jedoch als Dropdown mit Suchergebnissen.

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

Mehr dazu im Instant Search UI-Tool hier.

Search Page #

Ein zentrales Element einer ausgezeichneten Shopsuche ist das Erhalten relevanter Suchergebnisse. Unsere Search Page ermöglicht dieses Nutzererlebnis schnell und einfach umzusetzen.

Die Search Page erlaubt es, eine komplette Seite mit den bestmöglichen Treffern zu jeder beliebigen Anfrage zu zeigen.

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

Mehr dazu im Search Page UI-Tool hier.

Category Page #

Eine gut strukturierte Kategorienseite ist entscheidend für ein erfolgreiches eCommerce-Geschäft. Unsere Category Page macht diese Nutzererfahrung einfach aufbaubar. Sie erstellt eine vollständige Seite mit den bestmöglichen Ergebnissen zu einer Kategorie.

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

Mehr dazu im Category Page UI-Tool hier.

Facetten #

Clerk.js bietet eingebaute Unterstützung für dynamische Facettennavigation sowohl für Suche als auch Kategorien. Alle Produktattribute, die Sie an uns senden, können als Facette verwendet werden.

Hier ein Anwendungsbeispiel:

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

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "PRICE-TRANSLATION", "categories": "CATEGORIES-TRANSLATION", "brand": "BRAND-TRANSLATION"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="Mehr anzeigen"
  data-facets-searchbox-text="Suchen nach "
  data-facets-design="133995">
</span>

Mehr dazu im Facets UI-Tool hier.

Exit Intent #

Das Exit Intent Popup reagiert, wenn ein Besucher die Seite zu verlassen scheint, indem er seine Maus in Richtung des oberen Browserrandes bewegt. Es öffnet sich und zeigt interessante Produkte an, wodurch ein abwandernder Besucher noch zum Kauf animiert werden kann.

Jeder Elementblock kann als Exit-Intent-Popup getriggert werden, indem Sie dem Snippet das Attribut data-exit-intent="true" geben.

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

Mehr dazu im Exit Intent UI-Tool hier.

Popup #

Das UI Kit beinhaltet eine einfach zu nutzende Popup-Bibliothek, mit der Sie beliebige, benutzerfreundliche Popups mit beliebigem Inhalt erstellen können. Jedes HTML-Element mit der Klasse clerk-popup wird als Popup angezeigt.

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

<script type="text/javascript">
  var my_popup = Clerk('ui', 'popup', '#my-popup');
  
  // Popup anzeigen
  my_popup.show(); 
  /* oder */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // Popup ausblenden
  my_popup.hide(); 
  /* oder */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Mehr dazu im Popup UI-Tool hier.

Chat #

Clerk.js bietet ein JavaScript-Interface zur Steuerung des Chat-Widgets und zur Reaktion auf Konversationsereignisse. Dies ist nützlich, wenn Sie Chat aus Ihrer eigenen UI heraus triggern, der KI Kontextdaten zum Nutzer-Verhalten geben oder Konversations-Events ins Frontend einbinden möchten.

Die vollständige Methoden- und Eventreferenz finden Sie in den Chat JS-Dokumenten.

Chat über einen eigenen Button öffnen #

Wenn Sie Chat aus einem eigenen Button oder UI-Element anstelle des Standard-Launchers öffnen möchten, nutzen Sie toggle:

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

Sie können auch open und close separat einsetzen, um den Zustand explizit zu steuern.

Chat nur auf bestimmten Seiten anzeigen #

Standardmäßig ist Chat auf der gesamten Seite sichtbar. Um es nur auf bestimmten Seiten zu zeigen, deaktivieren Sie es in der globalen Config und aktivieren Sie es selektiv:

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

// Dann auf den gewünschten Seiten aktivieren
Clerk('chat', 'enable');

Warenkorb- und Seitenkontext an die KI übergeben #

Die Methode metadata übermittelt strukturierten Kontext an Chat, damit die KI relevantere Antworten geben kann. Rufen Sie sie immer dann auf, wenn sich der Kontext des Besuchers ändert – etwa bei Seitenwechsel, Warenkorbaktionen, Präferenzen-Update.

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

// Nachdem ein Besucher ein Produkt in den Warenkorb gelegt 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 Struktur des Payloads ist flexibel – übergeben Sie, was für die aktuellen Konversationen am hilfreichsten ist.

AI-Verhalten basierend auf Nutzeraktionen anpassen #

Die Methode prompt_message sendet eine systemische Anweisung an die KI. Der Kunde sieht sie nie, aber sie verändert die Reaktionsweise der KI in der aktuellen Unterhaltung.

// Nach dem Hinzufügen zum Warenkorb – KI auf Cross-Selling hinweisen
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 aufs Abschließen der Bestellung
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 Konversation ausgelöst. Öffnen Sie damit z.B. Ihren Helpdesk-Chat und geben Sie den Kontext mit – so ist der Support-Mitarbeiter direkt im Thema und der Besucher muss nichts doppelt eintippen.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onSupport: (e) => {
      // e.summary enthält die Zusammenfassung der Konversation
      const summary = e.summary || 'No conversation summary available.';

      // Beispiel: Intercom öffnen und Kontext vorausfüllen
      if (window.Intercom) {
        Intercom('showNewMessage', 'Weiterleitung vom KI-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 nach der Übergabe ausblenden
      Clerk('chat', 'disable');
    }
  }
});

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

Auf Chat-Events reagieren #

Nutzen Sie Event-Hooks, um Chat-Interaktionen mit dem restlichen Frontend zu verknüpfen – z. B. für Logging, State-Sync oder Übergabe an Agenten.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onMessage: (e) => {
      // Wird bei jeder Nachricht ausgelöst – Rolle: 'user', 'ai' oder 'results'
      console.log(e.message.role, e.message.text);
    },
    onOpen: (e) => {
      // Wird ausgelöst, wenn das Chat-Fenster geöffnet/geschlossen wird
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Bei Anforderung eines Menschen
      // e enthält die Zusammenfassung der Konversation
      openLiveChatWithSummary(e);
    }
  }
});

Hooks können Sie auch nachträglich registrieren:

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

Mehr dazu in den Chat JS-Dokumenten.

Produkte ausschließen #

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

Bestimmte IDs ausschließen #

Fügen Sie einfach dem Snippet das Attribut data-exclude hinzu. Der Inhalt von data-exclude sollte eine Liste von Produkt-IDs sein, die nicht angezeigt werden sollen – z. B. Produkte aus dem Warenkorb oder Produkte, die für den Nutzer nicht verfügbar sein sollen.

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

Duplikate vermeiden #

Hierzu setzen Sie das Attribut data-exclude-from beim jeweiligen Clerk Block, bei dem die Duplikate entfernt werden sollen. Der Wert ist ein CSS-Selektor der anderen Snippets, von denen keine Duplikate übernommen werden sollen.

Im Beispiel schließt .clerk-2 alle Produkte aus .clerk-1 aus und .clerk-3 alle Produkte aus .clerk-1 und .clerk-2.

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

Für individuellere Setups möchten Sie häufig auf die Ergebnisse von Clerk reagieren oder diese vor dem Rendern anpassen. Dafür sind Events nützlich.

Events ermöglichen es Ihnen, Event-Listener zu setzen, die zu bestimmten Zeitpunkten vor, während oder nach dem Rendern durch Clerk.js Code ausführen.

Ein typisches Beispiel ist das Laden individueller Preise für eingeloggte B2B-Kunden. Ein Event kann direkt nach dem Rendern der API aktiviert werden, um individuelle Preise zu laden und an die Produktelemente zu übergeben:

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

Mehr dazu im Events-Handbuch.

SEO und Performance #

Clerk.js bietet personalisierte Einkaufserlebnisse, ohne dass Ihre Website langsamer wird oder das SEO leidet. Durch Client-Side-Rendering und optimiertes Laden wird das Gleichgewicht zwischen Geschwindigkeit, Performance und Sichtbarkeit gewahrt.

SEO und Geschwindigkeit #

Es ist ein Irrglaube, dass JavaScript-Funktionen wie Clerk.js Performance oder SEO verschlechtern. Automatisierte Tools übersehen oft Optimierungsmöglichkeiten wie Caching, paralleles Laden und serverseitige Verarbeitung.

Vorteile der Clerk.js-Integration #

• Das Clerk.js Script (≈ 37 - 38 KB) wird asynchron geladen, sodass Ihre Seite bereits gerendert wird, während Clerk initialisiert.
• Clerk-Elemente werden clientseitig gerendert, was das Basis-HTML cachebar macht. Dynamische Komponenten werden nur nach dem Laden injiziert.
• So ist effizientes serverseitiges Caching und blockierungsfreies Laden der Clerk.js-Assets möglich.

Performance-Auswirkung #

• Die leichte und asynchrone Architektur von Clerk.js hat typischerweise nur geringe Auswirkungen auf die Ladezeiten.
• In der Praxis entsteht Performance-Verlust eher durch zusätzliche Bilder in Empfehlungen, nicht durch das Skript selbst. Minimieren Sie den Einfluss wie folgt:
  • Verwenden Sie ausreichend kleine, effiziente Formate wie WebP.
  • Passen Sie die Bildgröße an die Display-Dimensionen an (z. B. 400×400 px → 420×420 px max).
• Um Layout-Shifts (CLS) zu vermeiden, reservieren Sie Platz für injizierte Clerk-Inhalte.

Beispiel:

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

SEO-Aspekte #

Verstehen Sie, wie Clerk.js mit Suchmaschinen interagiert, damit Ihre Implementierung sowohl Nutzererlebnis als auch Sichtbarkeit gewährleistet.

Verlinkung und Crawlability #

• Clerk.js injiziert Empfehlungs-Links dynamisch auf Clientseite.
• Diese Links können das interne Linknetzwerk stärken, indem sie relevante Seiten miteinander verbinden (sofern Suchmaschinen sie rendern und folgen).
• Da sie per JavaScript injiziert werden, sollten Sie prüfen, wie Suchmaschinen sie interpretieren.
• Richtig gecrawlte Links verbessern die Crawlability und ermöglichen Suchmaschinen, mehr Seiten zu finden und zu indexieren.

PageRank-Verteilung #

• Können Suchmaschinen die Clerk.js-Links crawlen, helfen sie, Link-Einfluss (PageRank) auf wichtige Seiten zu verteilen.
• Dies unterstützt die bessere Sichtbarkeit und das Ranking wichtiger Produkt- und Kategorienseiten.

Beobachtete Vorteile #

• Eine korrekte Clerk.js-Integration kann mit einem stärkeren internen Linknetz verbunden sein, was die Sichtbarkeit in Suchergebnissen unterstützen kann.
• Clerk.io-Dashboards liefern Analytics zu Bestellbeeinflussung, Umsatzsteigerung und Beiträgen aus Search, Recommendations, Email und Audience.

Empfohlene Best Practices #

1. Bilder optimieren (WebP-Format, korrekte Auflösung).
2. Platz fürs Layout reservieren für dynamische Elemente zur Vermeidung von Layout-Shifts.
3. Real-User-Metriken überwachen, statt nur automatischen Scores zu vertrauen. Nutzen Sie die Clerk-Dashboards, um kanalübergreifende Effekte nachzuvollziehen.