Clerk.js

Panoramica #

Clerk.js è una libreria JavaScript che semplifica l’integrazione della nostra API con il frontend. Con soli 37,7kb, è una soluzione estremamente leggera.

Ci sono tre vantaggi nell’utilizzare Clerk.js:

• È robusto, perché viene caricato in modo asincrono. Questo significa che il resto della pagina non dipende dalla risposta dell’API prima del caricamento.
• È spesso più veloce, dal momento che il tuo server può iniziare a renderizzare la pagina in parallelo mentre Clerk.js effettua le chiamate e mostra i risultati.
• Il tracciamento dei visitatori e dei click viene gestito automaticamente per qualsiasi risultato mostrato da Clerk. Questo non richiede cookie, poiché generiamo un valore hash dell’IP e dell’useragent del visitatore, combinato con un sale unico dello store che viene aggiornato ogni 30 giorni.

Clerk.js viene caricato con uno script di inizializzazione aggiunto nell’header del sito web:

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

Viene caricata la libreria dal nostro CDN e ti permette di accedere alle sue funzionalità tramite l’oggetto Clerk, configurando Clerk.js con la chiave API in modo che sappia già per quale Store deve fare le chiamate API.

Snippet #

Quando la pagina viene caricata, Clerk.js la analizza in cerca di snippet con la classe “clerk”.

Poi utilizza gli attributi dello snippet per costruire una chiamata API, recuperando la chiave API dalla configurazione nello script di inizializzazione.

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

La parte visuale viene gestita dal Design, che è anch’esso referenziato dallo snippet.

Clerk.js utilizza i design Liquid per renderizzare HTML con i dati restituiti dall’API. Questi sono formattati come script, referenziati dal loro ID tramite data-template nello snippet.

<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>Search result for {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Buy Now</a>
    </div>
  {% endfor %}

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

Gli snippet possono anche essere semplificati includendo solo un riferimento a un blocco Content, usando la sintassi data-template="@content-block-id":

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

I design vengono poi gestiti con il Design Editor o con codice Liquid HTML in modo semplice da my.clerk.io.

I tuoi snippet dovranno solo contenere la classe clerk, informazioni specifiche della pagina come gli ID prodotto, e un riferimento all’ID di un blocco Content in data-template.

Injection #

Injection è una funzionalità che ti consente di inserire snippet di contenuto nel tuo sito senza doverlo aggiungere manualmente. Ti basta scegliere un CSS Selector dove iniettare lo snippet e Clerk.js lo aggiungerà automaticamente al caricamento della pagina.

Leggi di più su Injection qui.

Configurazione #

Clerk.js consente varie configurazioni che modificano il suo funzionamento.

Visitor IDs #

Per impostazione predefinita, Clerk.js genera visitor ID anonimi, utilizzati per tracciare le sessioni.

Se i clienti accettano i cookie, Clerk.js può essere configurato per piazzare un cookie persistente col visitor ID, permettendo il tracciamento su periodi più lunghi.

Se preferisci gestire manualmente gli ID di sessione, puoi configurare il parametro visitor che Clerk usa nelle chiamate API. In alternativa, puoi disabilitare totalmente il tracciamento della sessione impostando visitor a null.

// Visitor ID persistente
Clerk('config', {
  visitor: 'persistent'
});

// Visitor ID personalizzato
Clerk('config', {
  visitor: 'ABC123'
});

// Disabilitare il tracciamento dei visitor
Clerk('config', {
  visitor: null
});

Lingua #

Configura Clerk.js con la lingua scritta del sito. Questo permette a Clerk.io di gestire correttamente le regole grammaticali in Search e di recuperare le traduzioni quando usi feed multilingua.

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

I valori accettati sono elencati sotto Lingue supportate.

Funzioni di Design #

Clerk.js supporta l’aggiunta di Formatter e Global, che possono essere usati per creare funzionalità javascript personalizzate nei tuoi design.

Formatter #

Questi sono usati per influenzare o cambiare attributi. Ad esempio, potresti voler mostrare solo i primi 40 caratteri di una descrizione oppure calcolare una percentuale di sconto specifica in base al tipo di cliente loggato.

Global #

Questi sono pensati per essere usati con dati frontend che vuoi accedere nei design. Esempi possono essere la cifra mancante per ottenere la spedizione gratuita, il nome di un cliente loggato, un simbolo di valuta o un tasso di conversione.

Qui sotto un esempio di configurazione di formatter e global.

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>

Output #

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

Email Tracking #

Clerk.js può raccogliere automaticamente le email nella sessione del cliente per personalizzare le email recommendation anche se non hanno ancora effettuato un ordine.

Questo avviene configurando Clerk.js con collect_email: true come mostrato qui:

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

Così, Clerk.js monitorerà tutti i campi input nel sito e li registra tramite log/email quando un visitatore inserisce un indirizzo email in uno di essi:

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

Personalizzazione del Rendering #

Questa funzione è usata principalmente con Single Page App (SPA), Progressive Web App (PWA) e altre applicazioni che non usano caricamenti tradizionali delle pagine.

Clerk.js renderizza qualsiasi elemento con la classe clerk, ma possono essere usate altre classi per personalizzare il rendering come selettori personalizzati.

Di default, Clerk richiede di eseguire Clerk("content", "SELECTOR") ogni volta che un contenuto deve essere mostrato.

Aggiungendo auto_init_custom_selectors: true nella config, Clerk.js inizializza automaticamente ogni selettore personalizzato man mano che il DOM cambia, purché sia già stato renderizzato una volta con Clerk("content", "SELECTOR").

Questo comportamento continua fino a un refresh totale della pagina.

Debugging #

Clerk.js ha una modalità debug integrata che registrerà diverse informazioni nella console, a seconda del livello scelto. È configurata direttamente nell’URL:

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

Il debugger ha 4 parametri:

UI Kit #

Clerk.js include una serie di strumenti UI per elementi fondamentali che possono essere usati per migliorare l’esperienza utente. Questi spesso fanno risparmiare tempo di sviluppo per soluzioni personalizzate.

Instant Search #

Una componente chiave in una grande esperienza di ricerca e-commerce è ottenere risultati immediatamente mentre digiti. La nostra componente UI Instant Search rende questo processo rapido e semplice da implementare.

Qualsiasi contenuto Clerk.io può essere teoricamente reso un componente Instant Search, ma funziona al meglio come tendina che mostra i risultati di ricerca.

<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>Products matching <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 }}">Buy Now</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Approfondisci lo strumento Instant Search UI qui.

Search Page #

Una parte fondamentale di una grande esperienza di ricerca e-commerce è avere buoni risultati di ricerca. La nostra Search Page rende questa esperienza utente rapida e semplice da costruire.

La Search Page ti permette di creare una pagina completa che mostra le migliori corrispondenze per qualsiasi query.

<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>Products matching <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 }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

Approfondisci lo strumento Search Page UI qui.

Category Page #

Una pagina categoria ben strutturata è fondamentale per il successo di una attività eCommerce. La nostra Category Page rende questa esperienza rapida e facile da implementare. Ti permette di creare una pagina intera che mostra i migliori risultati per una categoria.

<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 }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

Approfondisci lo strumento Category Page UI qui.

Facets #

Clerk.js offre il supporto integrato per la navigazione faccettata dinamica su ricerca e categorie. Qualsiasi attributo del prodotto che invii può essere usato come facet.

Ecco un esempio di utilizzo base:

<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="View More"
  data-facets-searchbox-text="Search for "
  data-facets-design="133995">
</span>

Approfondisci lo strumento Facets UI qui.

Exit Intent #

Il popup exit intent si attiva quando il visitatore prova a lasciare il sito portando il mouse vicino alla parte superiore della finestra del browser. Si apre e mostra prodotti interessanti, potenzialmente convertendo un visitatore in uscita in un cliente.

Qualsiasi Content block può essere attivato al tentativo di uscita di un visitatore aggiungendo l’attributo data-exit-intent="true" allo snippet.

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

Approfondisci lo strumento Exit Intent UI qui.

Popup #

L’UI Kit contiene una semplice libreria popup per creare con facilità popup user-friendly con qualsiasi contenuto. Ogni elemento HTML sul sito con la classe clerk-popup verrà mostrato come popup.

<div id="my-popup" class="clerk-popup">Hello, world!</div>

<script type="text/javascript">
  var my_popup = Clerk('ui', 'popup', '#my-popup');
  
  // mostra popup
  my_popup.show(); 
  /* oppure */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // nascondi popup
  my_popup.hide(); 
  /* oppure */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Approfondisci lo strumento Popup UI qui.

Escludere Prodotti #

Clerk.js offre due modi diversi per escludere prodotti, a seconda che tu voglia escludere ID specifici o evitare la visualizzazione di prodotti duplicati tra diversi slider.

Escludere ID Specifici #

Aggiungi semplicemente l’attributo data-exclude allo snippet. Il contenuto di data-exclude deve essere una lista di ID prodotto che non vuoi mostrare, cioè i prodotti nel carrello del cliente o una lista di prodotti che non possono vedere.

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

Evitare Duplicati #

Questo si ottiene aggiungendo l’attributo data-exclude-from sul Clerk Block dove vuoi eliminare il duplicato. Il valore dell’attributo deve essere un CSS selector per gli altri snippet da cui prevenire i duplicati.

Nell’esempio sotto, .clerk-2 esclude qualunque prodotto che sia in .clerk-1 e .clerk-3 esclude tutti i prodotti che siano in .clerk-1 oppure .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 #

Quando crei soluzioni più personalizzate, spesso hai bisogno di reagire o modificare i risultati di Clerk prima che vengano renderizzati. Qui tornano utili gli Events.

Gli eventi permettono di impostare listener che eseguono codice in momenti specifici prima, durante o dopo che Clerk.js renderizza i propri risultati.

Un esempio comune è caricare prezzi personalizzati per un cliente loggato in uno scenario B2B. Un evento può essere eseguito subito dopo il rendering della risposta API di Clerk, permettendoti di recuperare prezzi personalizzati per un cliente e aggiungerli agli elementi prodotto:

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

Approfondisci gli Events qui.

SEO e Performance #

Clerk.js alimenta esperienze di shopping personalizzate senza rallentare il sito o penalizzare la SEO. Grazie al rendering lato client e al caricamento ottimizzato, bilancia velocità, prestazioni e visibilità nei motori di ricerca.

SEO e Velocità #

È un falso mito che funzionalità JavaScript come Clerk.js penalizzino prestazioni o SEO. Gli strumenti automatici spesso non considerano ottimizzazioni come caching, caricamento in parallelo e gestione lato server.

Vantaggi dell’integrazione Clerk.js #

• Lo script di Clerk.js (≈ 37 - 38 KB) viene caricato in modo asincrono, consentendo al tuo sito di renderizzare mentre Clerk si inizializza.
• Gli elementi Clerk sono renderizzati lato client, quindi il tuo HTML di base rimane in cache e i componenti dinamici vengono iniettati solo dopo il caricamento.
• Questo permette un caching efficiente lato server e un caricamento “non bloccante” delle risorse Clerk.js.

Impatto sulle Prestazioni #

• La leggerezza e la natura asincrona di Clerk.js normalmente producono un impatto minimo sui tempi di caricamento della pagina.
• Nella realtà, l’impatto sulle prestazioni deriva spesso dalle immagini aggiuntive renderizzate nelle recommendations, non dallo script in sé. Per minimizzarlo:
  • Usa formati moderni e ad alta efficienza come WebP.
  • Ridimensiona le immagini in base alle dimensioni di visualizzazione (ad es. 400×400 px → 420×420 px max).
• Per evitare spostamenti di layout (CLS), riserva spazio per i contenuti Clerk che verranno iniettati.

Ad esempio:

.clerk-slider-wrapper {
  min-height: 300px; /* regola se necessario */
  width: 100%;
}

Considerazioni SEO #

Comprendere come Clerk.js interagisce con i motori di ricerca aiuta a garantire che la tua implementazione supporti sia l’esperienza utente che la visibilità su Google.

Linking e Crawlabilità #

• Clerk.js inietta collegamenti recommendation dinamicamente lato client.
• Questi collegamenti possono migliorare il linking interno collegando le pagine correlate, se i motori di ricerca li renderizzano e li seguono correttamente.
• Poiché sono iniettati via JavaScript, dovresti verificare come i crawler dei motori di ricerca li visualizzano e interpretano.
• Link correttamente crawlati possono migliorare la crawlabilità e permettere ai motori di scoprire/indicizzare più pagine.

Distribuzione del PageRank #

• Quando i motori di ricerca possono scansionarli, i link di Clerk.js possono aiutare a distribuire equamente il PageRank tra pagine chiave.
• Questo favorisce la visibilità e il posizionamento di pagine prodotto e categoria.

Benefici Osservati #

• Una corretta integrazione di Clerk.js può essere correlata a una migliore struttura di linking interno, a supporto di una maggiore visibilità nei risultati di ricerca.
• Le dashboard di Clerk.io forniscono analytics su influenza ordini, incremento conversioni e ricavi derivanti da Search, Recommendations, Email e Audience.

Best Practice Consigliate #

1. Ottimizza le immagini (formato WebP, risoluzione corretta).
2. Riserva spazio di layout per gli elementi dinamici per prevenire spostamenti di layout.
3. Monitora i dati reali invece che affidarti solo agli score automatici. Usa le dashboard Clerk per valutare l’impatto su tutti i canali.