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 extrem 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 auf eine API-Antwort angewiesen ist, bevor sie geladen wird.
• Sie ist oft schneller, da Ihr Server mit dem Rendern der Seite beginnen kann, während Clerk.js parallel Aufrufe macht und Ergebnisse anzeigt.
• 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 aus der IP-Adresse und Useragent des Besuchers generieren, kombiniert mit einem eindeutigen Store-Salt, das alle 30 Tage rotiert.

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

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

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

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

Snippets #

Beim Laden der Seite scannt Clerk.js sie nach Snippets mit der Klasse “clerk”.

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

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

Das visuelle Design wird durch das Design gesteuert, das ebenfalls durch das 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 sie nur auf einen Element Block referenzieren, indem Sie die Syntax data-template="@element-block-id" verwenden:

<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 auf my.clerk.io bearbeitet.

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

Injection #

Injection ist ein Feature, das ermöglicht, Inhaltsschnipsel in Ihre Website einzufügen, ohne sie manuell zu platzieren. Stattdessen wählen Sie einfach einen CSS-Selektor, in den das Snippet injiziert wird, und Clerk.js fügt es beim Laden automatisch hinzu.

Erfahren Sie mehr über Injection hier.

Konfiguration #

Clerk.js erlaubt verschiedene Konfigurationen, die beeinflussen, wie es funktioniert.

Besucher-IDs #

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

Wenn Kunden Cookies akzeptieren, kann Clerk.js so konfiguriert werden, dass ein persistentes Cookie mit der Besucher-ID gesetzt wird, was Tracking über längere Zeiträume ermöglicht.

Wenn Sie Sitzungs-IDs lieber manuell verwalten möchten, können Sie den visitor-Parameter konfigurieren, der von Clerk in API-Aufrufen genutzt wird. Alternativ können Sie das Sitzungs-Tracking vollständig deaktivieren, indem Sie visitor auf null setzen.

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

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

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

Seiten-Kontext #

Konfiguriert Clerk.js mit dem Seiten-Kontext, den ein Besucher gerade sieht. Dieser 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, z. B. 12345 oder null
  category: null, // Kategorie-ID auf Kategorieseiten, 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 Sprache der Website. Dies wird genutzt, damit Clerk.io Grammatikregeln in Search richtig verarbeitet und die korrekten Übersetzungen abruft, wenn Sie mehrsprachige Feeds verwenden.

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

Akzeptierte Werte sind unter Unterstützte Sprachen gelistet.

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

• product: Die ID des auf der Produktseite angezeigten Produkts. Auf Nicht-Produktseiten auf null setzen.
• category: Die ID der auf Kategorieseiten angezeigten Kategorie. Auf Nicht-Kategorieseiten auf null setzen.
• page: Ein Seiten-Bezeichner oder Typ bei anderen Seiten wie Startseite, Warenkorb oder Checkout. Auf null setzen, falls nicht relevant.

Falls Ihre Plattform für einen Seitentyp keine spezifische ID bereitstellt, lassen Sie den Wert auf null. Setzen Sie ausschließlich Werte für die relevanten Seitentypen.

Design-Funktionen #

Clerk.js unterstützt das Hinzufügen von Formatters (Formatierer) und Globals (Globale Variablen), um benutzerdefinierte JavaScript-Funktionalität für Ihre Designs bereitzustellen.

Formatters #

Diese werden genutzt, um Attribute zu beeinflussen oder zu ändern. Beispielsweise möchten Sie vielleicht nur die ersten 40 Zeichen einer Beschreibung anzeigen, oder einen bestimmten Rabatt anhand des eingeloggten Kundentyps berechnen.

Globals #

Diese dienen dazu, Frontend-Daten, die Sie in Designs verwenden möchten, bereitzustellen. Zum Beispiel der verbleibende Betrag für Gratisversand, der Name des eingeloggten Kunden, ein Währungssymbol oder ein Umrechnungskurs.

Unten ein Beispiel zur Konfiguration von Formatters und Globals.

Config #

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

Design #

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

Ausgabe #

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

Email-Tracking #

Clerk.js kann automatisch E-Mails in der Session des Kunden sammeln, um personalisierte Empfehlungen per E-Mail zu versenden, selbst wenn noch kein Bestellung erfolgt ist.

Aktivieren Sie collect_email in Ihrer Clerk.js-Konfiguration:

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

Mit dieser Einstellung ü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 loggen möchten, können Sie auch folgenden Schnipsel verwenden:

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

Eingeloggte Kunden #

Wenn Ihr Webshop Kundenkonten bietet, rufen Sie log/email auf, sobald die E-Mail-Adresse eines bekannten Kunden in der Session verfügbar ist – sowohl beim aktiven Einloggen als auch bei der Rückkehr, wenn der Kunde bereits eingeloggt ist.

Der einfachste Weg ist, bei jedem Seitenladen zu prüfen, ob eine E-Mail vorhanden ist und bei Bedarf den Aufruf zu machen. Um unnötige API-Calls zu vermeiden, speichern Sie ein Flag in der Browser-Session, sodass der Aufruf nur einmal pro Session 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 mit der tatsächlichen E-Mail-Adresse aus Ihrer Plattform. Rendern Sie dieses Skript nur, wenn eine E-Mail wirklich verfügbar ist – bei Gastnutzern kann es ganz entfallen.

Ohne diese Maßnahme kann Clerk.io die Session eines Besuchers nur dann mit einer E-Mail-Adresse verknüpfen, wenn ein Kauf abgeschlossen wird. Wird die E-Mail registriert, sobald sie verfügbar ist, erfolgt die Verbindung sofort. Das ist notwendig, um automatisierte E-Mails basierend auf dem Surfverhalten zu versenden, personalisierte Empfehlungen in E-Mails zu zeigen und Merchandising-Kampagnen für bestimmte Audience-Segmente auszuliefern.

So funktioniert die Zuordnung #

Wenn eine E-Mail geloggt wird, sendet Clerk sowohl die Besucher-ID als auch die E-Mail-Adresse an die API, um die Verbindung herzustellen.

Clerk kann dann das bisherige Verhalten dieses Besuchers (z. B. angesehene Produkte, Klicks und Suchanfragen) mit der E-Mail-Adresse verknüpfen.

Mit dieser Zuordnung können dieselben Verhaltensdaten sowohl für E-Mail-Anwendungsfälle (wie getriggerte und personalisierte E-Mails) als auch zur Onsite-Personalisierung in Empfehlungen für eingeloggte Kunden genutzt werden.

DOM-Überwachung #

Aktivieren Sie die DOM-Überwachung, wenn Ihr Webshop Clerk.io-Inhalte erst nach dem Laden der Seite einfügt. Clerk.js beobachtet Änderungen an der Seitenstruktur (DOM), damit Inhalte erkannt werden, sobald sie erscheinen.

Sie können das Verhalten auf SPA Auto Detect Changes in my.clerk.io aktivieren oder observe_dom: true zu Ihrer Clerk.js-Konfiguration hinzufügen.

Side-Cart-Beispiel #

Angenommen, Ihr Webshop erstellt den Side Cart erst, wenn ein Produkt hinzugefügt wird. Der Warenkorb enthält ein Clerk.io-Empfehlungs-Snippet, das deshalb erst beim Öffnen des Warenkorbs auf die Seite gelangt.

Beim Timer-Ansatz prüft Clerk.js alle Sekunde auf Änderungen. Das Empfehlungssnippet kann erst beim nächsten Check aufgegriffen werden.

Mit aktiviertem observe_dom löst das Einfügen des Carts direkt eine Überprüfung aus. Clerk.js erkennt das Snippet schneller und beginnt bereits mit dem Rendern der Empfehlungen – die Wartezeit sinkt.

Weitere Beispiele #

Dasselbe Verhalten hilft auch bei anderen Setups, bei denen Inhalte ohne vollständiges Neuladen erscheinen:

• Add-to-Cart Popup: Nach dem Hinzufügen eines Produkts erstellt der Webshop ein Popup mit Clerk.io-Empfehlungen. Clerk.js erkennt das neue Element beim Erstellen des Popups.
• Lazy-Loaded Section: Weiter unten auf der Seite wird beim Scrollen dynamisch ein Clerk.io-Block hinzugefügt. Clerk.js erkennt ihn sofort beim Einfügen.
• Single Page App: Eine React- oder Vue-App fügt Clerk.io-Inhalte bei Ansichtwechseln hinzu. Clerk.js erkennt das ergänzte Content ohne kompletten Reload.

DOM-Überwachung gilt auch für Inhaltsblöcke, E-Mail-Signup-Formulare und Live Search.

Überwachung aktivieren #

Nutzen Sie eine dieser Möglichkeiten, um die DOM-Überwachung zu aktiveren:

• Backend: Öffnen Sie in my.clerk.io Ihren Store und gehen Sie zu Settings > Features. Aktivieren Sie SPA Auto Detect Changes.
• Code: Ergänzen Sie observe_dom: true in Ihrer Clerk.js-Konfiguration, wie unten gezeigt.

Beide Optionen aktivieren dieselbe Funktion. Sie müssen nur eine davon nutzen.

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

Behalten Sie Ihren öffentlichen Store-API-Key und alle anderen Optionen in der Konfiguration.

Das passende Clerk.io-Snippet und dessen Element- und Design-Konfiguration müssen weiterhin eingebunden werden. Die Aktivierung der Überwachung bewirkt nur, dass Clerk.js später hinzugefügte Inhalte erkennt; sie platziert keine Empfehlungs-Placements von selbst.

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

Ressourcenverbrauch #

Clerk.js bündelt schnelle Änderungen an der Seite zu einem Durchlauf und limitiert vollständige Durchläufe auf einmal alle 500 ms. Der Observer ist während der Ruhezeiten inaktiv und erzeugt keine zusätzlichen API-Calls oder Netzanfragen.

Die Einstellung ist opt-in. Stores ohne Aktivierung behalten ihr bisheriges Verhalten.

Custom Rendering #

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

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

Standardmäßig müssen Sie Clerk("content", "SELECTOR") jedes Mal aufrufen, wenn Inhalte angezeigt werden sollen.

Mit auto_init_custom_selectors: true in der Konfiguration initialisiert Clerk.js alle benutzerdefinierten Selektoren automatisch, sobald sich das DOM verändert, sofern sie zuvor einmal mit Clerk("content", "SELECTOR") gerendert wurden.

Dieses Verhalten besteht bis zum vollständigen Seiten-Refresh.

Debugging #

Clerk.js verfügt über einen integrierten Debug-Modus, der Diagnoseinformationen in die Browser-Konsole schreibt. Die Konfiguration wird in sessionStorage unter dem Schlüssel __clerk_debug gespeichert und bleibt innerhalb einer Browsersitzung über Seitenwechsel hinweg aktiv.

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

Aktivierungsmethoden #

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

Konsolen-Kurzbefehl

Der einfachste Weg ist der Aufruf von Clerk('debug') in der Browser-Konsole. Mehrere Argument-Formate sind möglich:

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

Config-Pfad

Der Debug-Modus kann auch per Standard-Konfigurationsaufruf gesetzt werden:

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

URL-Hash

Debug-Modus kann aktiviert werden, indem Sie einen Hash-Fragment an die URL anhängen. Das ist nützlich, um Debug-Links mit Kollegen zu teilen:

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

Ist der Modus so aktiviert, wird die Konfiguration ebenfalls in sessionStorage unter dem Schlüssel __clerk_tmp_config gespeichert.

Konfigurationsoptionen #

Session Storage #

Wird der Debug-Modus aktiviert, speichert Clerk die Konfiguration unter __clerk_debug in sessionStorage. Damit bleiben die Einstellungen beim Navigieren zwischen Seiten erhalten, ohne andere Tabs zu betreffen oder nach der Session zu verbleiben.

Consent Management Plattformen (CMPs) wie Cookiebot können __clerk_debug als Storage-Item aufführen, das dokumentiert werden muss. Dies ist ein funktionaler Key ausschließlich für Entwickler-Debugging. Er enthält keine personenbezogenen Daten oder Tracking-Informationen.

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

UI Kit #

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

Instant Search #

Ein wesentliches Merkmal einer großartigen E-Commerce-Suche ist das sofortige Anzeigen von Ergebnissen beim Tippen. Unsere Instant Search UI-Komponente macht dieses Erlebnis schnell und einfach umsetzbar.

Jeder Clerk.io-Inhalt kann theoretisch als Instant Search-Komponente genutzt werden, optimal ist jedoch als Dropdown mit Suchergebnissen.

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

Mehr zum Instant Search UI Tool hier.

Suchseite #

Ein wesentliches Merkmal einer großartigen E-Commerce-Suchfunktion ist die Anzeige relevanter Suchergebnisse. Unsere Suchseiten-Komponente macht dieses Erlebnis schnell und einfach umsetzbar.

Die Suchseite ermöglicht es, eine komplette Seite mit den bestmöglichen Treffern für jede beliebige Suchanfrage anzuzeigen.

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

Mehr zum Search Page UI Tool hier.

Kategorieseite #

Eine gut strukturierte Kategorieseite ist der Schlüssel zu erfolgreichem E-Commerce. Unsere Kategorieseiten-Komponente ermöglicht dieses Erlebnis schnell und einfach. Sie können damit eine vollständige Seite mit den bestmöglichen Treffern für eine beliebige Kategorie 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);">
          		Mehr Ergebnisse anzeigen
    		</div>
    {% endif %}
  </div>
</span>

Mehr zum Category Page UI Tool hier.

Facetten #

Clerk.js hat eingebaute Unterstützung für facettenbasierte Navigation sowohl bei Suchen als auch bei Kategorien. Jedes Produktattribut, das Sie an uns senden, kann als Facette verwendet werden.

Hier ein Beispiel einer grundlegenden Verwendung:

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

Mehr zum Facets UI Tool hier.

Exit Intent #

Das Exit-Intent-Popup reagiert, wenn ein Besucher Ihre Seite verlassen möchte, indem er die Maus zum oberen Rand des Browserfensters bewegt. Es erscheint und zeigt interessante Produkte an, um abwandernde Besucher noch zu einem Kauf zu bewegen.

Jeder Element-Block kann beim Exit Intent durch das Hinzufügen von data-exit-intent="true" zum 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>

Mehr zum Exit Intent UI Tool hier.

Pop-up #

Das UI Kit enthält eine einfache Pop-up-Bibliothek, um schnell benutzerfreundliche Pop-ups mit beliebigem Inhalt zu erstellen. Jedes HTML-Element mit der Klasse clerk-popup wird als Pop-up angezeigt.

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

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

Mehr zum Popup UI Tool hier.

Chat #

Clerk.js stellt eine JavaScript-Schnittstelle zur Steuerung des Chat Widgets und zur Reaktion auf Unterhaltungsevents zur Verfügung. Das ist nützlich, wenn Sie den Chat aus Ihrer eigenen UI heraus öffnen, der KI kontextuelle Daten senden oder Gesprächsereignisse in Ihr Frontend integrieren möchten.

Die vollständige Referenz zu Methoden und Events finden Sie in den Chat JS docs.

Chat aus einem eigenen Button öffnen #

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

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

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

Chat nur auf bestimmten Seiten anzeigen #

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

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

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

Cart- und Seiten-Kontext an die KI senden #

Die metadata-Methode sendet strukturierten Kontext an Chat, damit die KI relevantere Antworten geben kann. Rufen Sie sie auf, sobald sich der Kontext (z. B. Seitenwechsel, Hinzufügen zum Warenkorb, Präferenzen) ändert.

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

// Nach Hinzufügen eines Produkts zum Warenkorb
Clerk('chat', 'metadata', {
  cart: {
    items: [
      { id: 101, name: 'Lightsaber', price: 99.95 },
      { id: 204, name: 'Force Gloves', price: 29.95 }
    ],
    total: 129.90
  }
});

Die Datenstruktur ist flexibel — fügen Sie alles bei, was für den jeweiligen Chat-Kontext hilfreich ist.

KI-Verhalten basierend auf Nutzeraktionen anpassen #

Mit prompt_message senden Sie der KI eine systemseitige Anweisung, die das Antwortverhalten in der aktuellen Unterhaltung steuert. Der Kunde sieht diese Information nicht.

// Nach Hinzufügen zum Warenkorb — der KI Cross-Selling anweisen
Clerk('chat', 'prompt_message', 'Der Nutzer hat gerade ein Lichtschwert in den Warenkorb gelegt. Schlagen Sie ergänzende Produkte wie Zubehör oder Schutzausrüstung vor.');

// Auf der Checkout-Seite — Fokus auf Bestellabschluss legen
Clerk('chat', 'prompt_message', 'Der Nutzer ist auf der Checkout-Seite. Helfen Sie beim Abschluss des Kaufs und beantworten Sie eventuelle letzte Fragen.');

Übergabe an einen Menschen #

Wenn ein Besucher menschliche Unterstützung benötigt, wird das onSupport-Event mit einer Zusammenfassung der bisherigen Unterhaltung ausgelöst. Damit kann z.B. Ihr Helpdesk-Chat geöffnet und der Kontext übergeben werden, sodass ein Agent direkt informiert ist – der Besucher muss sich nicht wiederholen.

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

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

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

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

Das onSupport-Event wird nur ausgelöst, wenn in den Chat-Einstellungen Support kontaktieren aktiviert ist und der Besucher explizit nach einem Menschen fragt.

Auf Chat-Events reagieren #

Verwenden Sie Event-Hooks, um Chat-Verhalten in Ihr Frontend zu integrieren – etwa zum Protokollieren von Nachrichten, Synchronisieren von Zuständen oder Übergabe an einen Support-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/Schließen des Chatfensters ausgelöst
      analytics.track('Chat umgeschaltet', { open: e.open });
    },
    onSupport: (e) => {
      // Wird ausgelöst, wenn der Besucher nach menschlichem Support fragt
      // e enthält die Zusammenfassung des Gesprächs
      openLiveChatWithSummary(e);
    }
  }
});

Sie können Event-Hooks auch dynamisch nach der Initialisierung registrieren:

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

Mehr dazu in den Chat JS docs.

Produkte ausschließen #

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

Ausschluss bestimmter IDs #

Fügen Sie dem Snippet einfach das Attribut data-exclude hinzu. Der Inhalt von data-exclude sollte eine Liste von Produkt-IDs sein, die nicht angezeigt werden dürfen, z. B. Produkte im Warenkorb des Kunden oder Produkte, die er nicht sehen darf.

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

Doppelte Produkte vermeiden #

Dies wird gelöst, indem Sie das Attribut data-exclude-from an dem Clerk-Block setzen, bei dem das Duplikat ausgeschlossen werden soll. Der Wert ist ein CSS-Selektor auf das/die Snippet(s), deren Produkte ausgeschlossen werden sollen.

Im Beispiel schließt .clerk-2 alle Produkte aus, die in .clerk-1 enthalten sind – und .clerk-3 schließt alle Produkte aus, die in .clerk-1 oder .clerk-2 sind.

<span class="clerk clerk-1"
  data-template="@clerk-banner-1">
</span>
 
<span class="clerk clerk-2"
  data-exclude-from=".clerk-1"
  data-template="@clerk-banner-2">
</span>
 
<span class="clerk clerk-3"
  data-exclude-from=".clerk-1,.clerk-2"
  data-template="@clerk-banner-3">
</span>

Events #

Bei stark angepassten Setups müssen Sie oft noch vor oder nach dem Rendern von Clerk eingreifen. Hier kommen Events ins Spiel.

Events erlauben es, Event Listener zu setzen, die zu bestimmten Zeitpunkten vor, während oder nach dem Rendern von Clerk.js-Code ausgeführt werden.

Ein typisches Beispiel ist das Nachladen individueller Preise für eingeloggte B2B-Kunden. Ein Event kann direkt nach der API-Antwort ausgelöst werden, sodass Sie eigens Preise für Kunden abfragen und an Produktelemente anhängen:

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

Mehr zu Events hier.

SEO und Performance #

Clerk.js sorgt für personalisierte Einkaufserlebnisse, ohne Ihre Seite zu verlangsamen oder die SEO zu beeinträchtigen. Durch clientseitiges Rendering und optimiertes Laden werden Geschwindigkeit, Performance und Suchmaschinen-Sichtbarkeit ausbalanciert.

SEO und Geschwindigkeit #

Es ist ein Missverständnis, dass JavaScript-Features wie Clerk.js die Performance oder SEO beeinträchtigen. 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 Ihre Website gerendert werden kann, während Clerk initialisiert wird.
• Clerk-Elemente werden clientseitig gerendert, d. h. Ihr Basis-HTML bleibt cachefähig und dynamische Komponenten werden erst nach dem Laden eingefügt.
• Dies ermöglicht effizientes serverseitiges Caching und ein nicht blockierendes Laden der Clerk.js-Assets.

Auswirkungen auf die Performance #

• Die schlanke und asynchrone Natur von Clerk.js führt in der Regel zu geringen Auswirkungen auf die Ladezeiten der Seite.
• Leistungseinbußen in der Praxis stammen häufig von zusätzlichen Bildern, die in Recommendations gerendert werden, nicht vom Skript selbst. Um die Auswirkungen zu minimieren:
  • Verwenden Sie angemessen große, effiziente Formate wie WebP.
  • Skalieren Sie Bilder auf die Anzeigegröße (z. B. 400×400 px → 420×420 px max.).
• Um Layoutverschiebungen (CLS) zu vermeiden, sollte Platz für eingefügte Clerk-Inhalte reserviert werden.

Z. B.:

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

SEO-Überlegungen #

Das Verständnis darüber, wie Clerk.js mit Suchmaschinen interagiert, hilft sicherzustellen, dass Ihre Implementierung sowohl die Nutzererfahrung als auch die Sichtbarkeit in der Suche unterstützt.

Verlinkung und Crawlability #

• Clerk.js fügt Recommendation-Links dynamisch auf der Client-Seite ein.
• Diese Links können das interne Verlinken verbessern, indem sie verwandte Seiten verbinden, wenn die Suchmaschinen diese korrekt rendern und ihnen folgen.
• Da sie durch JavaScript eingefügt werden, sollten Sie überprüfen, wie Suchmaschinen-Crawler sie rendern und interpretieren.
• Richtig gecrawlte Links können die Crawlability verbessern und es Suchmaschinen erlauben, mehr Seiten zu entdecken und zu indexieren.

PageRank-Verteilung #

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

Beobachtete Vorteile #

• Eine korrekte Clerk.js-Integration kann mit einer stärkeren internen Verlinkungsstruktur korrelieren, was die Sichtbarkeit in den Suchergebnissen unterstützen kann.
• Clerk.io-Dashboards bieten Analysen zum Zusammenhang von Bestellungen, Conversion-Steigerungen und Umsatzerträgen durch Search-, Recommendations-, Email- und Audience-Features.

Empfohlene Best Practices #

1. Bilder optimieren (WebP-Format, korrekte Auflösung).
2. Layout-Fläche reservieren für dynamische Elemente, um Layoutverschiebungen zu verhindern.
3. Reale Metriken überwachen statt sich nur auf automatische Werte zu verlassen. Nutzen Sie Clerks Dashboards, um Auswirkungen über verschiedene Kanäle hinweg zu beurteilen.