Clerk.js

Übersicht #

Clerk.js ist eine JavaScript-Bibliothek, die die Integration unserer API mit dem Frontend vereinfacht. Mit nur 37,7 kb ist es eine super 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 die Seite parallel mit Clerk.js rendern kann, während Aufrufe gemacht und Ergebnisse gerendert werden.
• Besucher- und Klickverfolgung wird automatisch für alle von Clerk angezeigten Ergebnisse behandelt. Dies erfordert keine Cookies, da wir einen gehashten Wert der IP und des Useragents des Besuchers generieren, kombiniert mit einem einzigartigen Store-Salz, das alle 30 Tage rotiert.

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

<!-- Start des Clerk.io E-Commerce Personalisierungstools - 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>
<!-- Ende des Clerk.io E-Commerce Personalisierungstools - www.clerk.io -->

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

Snippets #

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

Es verwendet dann die Attribute des Snippets, um einen API-Aufruf zu erstellen, während es den API-Schlüssel aus der Konfiguration im Initialisierungsskript abruft.

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

Die visuellen Elemente werden vom Design behandelt, das auch im Snippet referenziert wird.

Clerk.js verwendet Liquid-Designs, um HTML mit den vom API zurückgegebenen Daten zu rendern. Diese sind als Skripte formatiert, die über ihre ID im data-template in Ihrem Snippet referenziert werden.

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

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

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

Snippets können auch vereinfacht werden, um nur eine Referenz zu einem Content-Block einzuschließen, indem die Syntax data-template="@content-block-id" verwendet wird:

<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 von my.clerk.io behandelt.

Ihre Snippets müssen nur die Klasse clerk, spezifische Seiteninformationen wie Produkt-IDs und eine Referenz zur ID eines Content-Blocks im data-template enthalten.

Injection #

Injection ist eine Funktion, die es Ihnen ermöglicht, Inhalts-Snippets in Ihre Website einzufügen, ohne sie manuell hinzufügen zu müssen. Stattdessen wählen Sie einfach einen CSS-Selektor aus, in den das Snippet eingefügt werden soll, und Clerk.js fügt es automatisch beim Laden der Seite hinzu.

Erfahren Sie mehr über Injection hier.

Konfiguration #

Clerk.js ermöglicht eine Vielzahl von Konfigurationen, die ändern, wie es funktioniert.

Besucher-IDs #

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

Wenn Kunden Cookies zustimmen, kann Clerk.js so konfiguriert werden, dass ein persistenter Cookie mit der Besucher-ID gesetzt wird, was eine Verfolgung über einen längeren Zeitraum ermöglicht.

Wenn Sie die Sitzungs-IDs manuell verwalten möchten, können Sie den visitor-Parameter konfigurieren, den Clerk in API-Aufrufen verwendet. Alternativ können Sie die Sitzungsverfolgung vollständig deaktivieren, indem Sie den Besucher auf null setzen.

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

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

// Deaktivierung der Besucher-Verfolgung
Clerk('config', {
  visitor: null
});

Sprache #

Konfiguriert Clerk.js mit der geschriebenen Sprache der Website. Dies wird verwendet, damit Clerk.io Grammatikregeln in der Suche richtig behandelt und die richtigen Übersetzungen abruft, wenn Sie mehrsprachige Feeds verwenden.

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

Designfunktionen #

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

Formatierer #

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

Globals #

Diese sind dazu gedacht, mit Frontend-Daten verwendet zu werden, auf die Sie in Designs zugreifen möchten. Dies könnten Beispiele wie der verbleibende Betrag sein, der benötigt wird, um kostenlosen Versand zu erreichen, der Name eines angemeldeten Kunden, ein Währungssymbol oder ein Wechselkurs.

Unten ist ein Beispiel für die Konfiguration von Formatierern 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">GRÜNES LICHTSCHWERT</div>
<div class="price">$1999.99</div>

E-Mail-Verfolgung #

Clerk.js kann automatisch E-Mails in der Sitzung des Kunden sammeln, um personalisierte E-Mail-Empfehlungen zu erstellen, selbst wenn sie noch keine Bestellung aufgegeben haben.

Dies geschieht, indem Clerk.js mit collect_email: true konfiguriert wird, wie hier gezeigt:

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

Damit überwacht Clerk.js alle Eingabefelder auf der Website und protokolliert es mit log/email, wenn ein Besucher eine E-Mail-Adresse in eines von ihnen eingibt:

https://api.clerk.io/v2/log/email?payload={"email":"test@test.com","key":"insert_api_key","visitor":"auto"}

Benutzerdefinierte Darstellung #

Dies wird hauptsächlich mit Single Page Apps (SPA), Progressive Web Apps (PWA) und anderen Anwendungen verwendet, die keine traditionellen Seitenladevorgänge verwenden.

Clerk.js rendert alle Elemente mit der Klasse clerk, aber andere Klassen können verwendet werden, um die Darstellung als benutzerdefinierte Selektoren anzupassen.

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

Das Hinzufügen von auto_init_custom_selectors: true zur Konfiguration lässt Clerk.js automatisch alle benutzerdefinierten Selektorelemente initialisieren, während sich der DOM ändert, solange sie bereits einmal mit Clerk("content", "SELECTOR") gerendert wurden.

Dieses Verhalten setzt sich fort, bis eine vollständige Seitenaktualisierung erfolgt.

Debugging #

Clerk.js hat einen integrierten Debug-Modus, der verschiedene Informationen in die Konsole protokolliert, abhängig von dem von Ihnen gewählten Level. Es wird direkt in der URL konfiguriert:

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

Der Debugger hat 4 Parameter:

UI Kit #

Clerk.js enthält eine Reihe von UI-Tools für wichtige Elemente, die verwendet werden können, um die Benutzererfahrung zu verbessern. Diese sparen oft Entwicklungszeit für benutzerdefinierte Setups.

Sofortige Suche #

Ein wichtiger Teil einer großartigen E-Commerce-Sucherfahrung besteht darin, sofort Ergebnisse zu erhalten, sobald Sie mit dem Tippen beginnen. Unser Sofort-Such-UI-Komponente macht diese Benutzererfahrung schnell und einfach zu erstellen.

Jeder Clerk.io-Inhalt kann theoretisch in eine Sofort-Suchkomponente umgewandelt werden, aber es funktioniert am besten als Dropdown, das Suchergebnisse anzeigt.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
  data-labels='["Sofortige Suche"]'
      
  data-instant-search="INSERT_CSS_SELECTORS_HERE">
  
  <dl class="product-search-result-list">
    <dt>Produkte, die <i>{{ query }}</i> entsprechen</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>

Erfahren Sie mehr über das Sofort-Such-UI-Tool hier.

Suchseite #

Ein wichtiger Teil einer großartigen E-Commerce-Sucherfahrung besteht darin, gute Suchergebnisse zu erhalten. Unsere Suchseite macht diese Benutzererfahrung schnell und einfach zu erstellen.

Die Suchseite ermöglicht es Ihnen, eine vollständige Seite zu erstellen, die die bestmöglichen Übereinstimmungen für eine gegebene Abfrage anzeigt.

<span 
  class="clerk"
  
  data-api="search/search"
  data-limit="40"
  data-labels='["Suchseite"]'
  data-query="INSERT_QUERY_HERE"
  data-orderby="INSERT_SORTIERATTRIBUT"
  data-order="asc_OR_desc">>
  
  <div class="product-search-result-list">
    <div>Produkte, die <i>{{ query }}</i> entsprechen</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>

Erfahren Sie mehr über das Suchseiten-UI-Tool hier.

Kategorieseite #

Eine gut strukturierte Kategorieseite ist der Schlüssel zu einem erfolgreichen E-Commerce-Geschäft. Unsere Kategorieseite macht diese Benutzererfahrung schnell und einfach zu erstellen. Damit können Sie eine vollständige Seite erstellen, die die bestmöglichen Ergebnisse für eine Kategorie anzeigt.

<span 
  class="clerk"
  
  data-api="recommendations/category/popular"
  data-limit="40"
  data-labels='["Kategorieseitenraster"]'
  data-category="INSERT_CATEGORY_ID"
  data-orderby="INSERT_SORTIERATTRIBUT"
  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>

Erfahren Sie mehr über das Kategorieseiten-UI-Tool hier.

Facetten #

Clerk.js bietet integrierte Unterstützung für dynamische facettierte Navigation sowohl für die Suche als auch für Kategorien. Alle Produktattribute, die Sie uns senden, können als Facetten verwendet werden.

Hier ist ein Beispiel für die grundlegende Verwendung:

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

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="schuhe"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["preis","kategorien","marke"]'
  data-facets-titles='{"preis": "PREIS-ÜBERSETZUNG", "kategorien": "KATEGORIEN-ÜBERSETZUNG", "marke": "MARKE-ÜBERSETZUNG"}'
  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>

Erfahren Sie mehr über das Facetten-UI-Tool hier.

Exit-Intent #

Das Exit-Intent-Popup reagiert, wenn ein Besucher versucht, Ihre Seite zu verlassen, indem er die Maus in die Nähe des oberen Randes des Browserfensters bewegt. Es erscheint und zeigt interessante Produkte an, wodurch ein abwandernder Besucher möglicherweise in einen kaufenden Kunden umgewandelt wird.

Jeder Content-Block kann bei der Absicht eines Besuchers, die Seite zu verlassen, ausgelöst werden, indem das Attribut data-exit-intent="true" zum Snippet hinzugefügt wird.

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

Erfahren Sie mehr über das Exit-Intent-UI-Tool hier.

Popup #

Das UI Kit enthält eine einfache Popup-Bibliothek, um einfach, aber benutzerfreundliche Popups mit beliebigem Inhalt 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>

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

Ausschluss von Produkten #

Clerk.js hat zwei verschiedene Möglichkeiten, Produkte auszuschließen, je nachdem, ob Sie spezifische IDs ausschließen oder vermeiden möchten, dass doppelte Produkte zwischen verschiedenen Slidern angezeigt werden.

Ausschluss spezifischer IDs #

Fügen Sie einfach das Attribut data-exclude zum Snippet hinzu. Der Inhalt von data-exclude sollte eine Liste der Produkt-IDs sein, die Sie nicht angezeigt haben möchten, d.h. die Produkte im Einkaufswagen 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>

Vermeidung von Duplikaten #

Dies geschieht, indem das Attribut data-exclude-from auf dem Clerk-Block hinzugefügt wird, wo immer Sie das Duplikat entfernen möchten. Der Wert des Attributs sollte ein CSS-Selektor für das andere Snippet sein, um Duplikate zu verhindern.

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

Erfahren Sie mehr über das Ausschluss von Produkten-UI-Tool hier.

Ereignisse #

Beim Erstellen benutzerdefinierter Setups müssen Sie häufig auf die Ergebnisse von Clerk reagieren oder diese ändern, bevor sie gerendert werden. Hier sind Ereignisse nützlich.

Ereignisse ermöglichen es Ihnen, Ereignis-Listener einzurichten, die Code zu bestimmten Zeiten vor, während oder nach dem Rendern der Ergebnisse von Clerk.js ausführen.

Ein häufiges Beispiel ist das Laden benutzerdefinierter Preise für einen angemeldeten Kunden in einem B2B-Setup. Ein Ereignis kann sofort nach dem Rendern der API von Clerk ausgeführt werden, sodass Sie benutzerdefinierte Preise für einen Kunden abrufen und sie den Produktelementen hinzufügen 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;
    }
})

Erfahren Sie mehr über die Ereignisse hier.