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:

• È robusta, poiché viene caricata in modo asincrono. Questo significa che il resto della pagina non dipende da una risposta API per caricarsi.
• Spesso è più veloce, poiché il tuo server può iniziare a renderizzare la pagina in parallelo mentre Clerk.js effettua chiamate e rende i risultati.
• Il tracciamento dei visitatori e dei click viene gestito automaticamente per qualsiasi risultato mostrato da Clerk. Questo non richiede cookie, dato che generiamo un valore hash dell’IP e useragent del visitatore, combinati con un sale unico dello store che ruota ogni 30 giorni.

Clerk.js si carica 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 -->

Carica la libreria dal nostro CDN e 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 effettuare le chiamate API.

Snippet #

Quando la pagina viene caricata, Clerk.js la analizza per qualsiasi snippet con classe “clerk”.

Poi utilizza gli attributi dello snippet per costruire una chiamata API prendendo la chiave dall’inizializzazione nello script.

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

Gli elementi visivi sono gestiti dal Design, anch’esso referenziato dallo snippet.

Clerk.js utilizza i design Liquid per renderizzare l’HTML con i dati restituiti dall’API. Questi sono formattati come script, referenziati tramite l’ID in 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>Risultato della ricerca per {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Acquista ora</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Carica più risultati</a>
</script>

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

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

I design sono poi gestiti con il Design Editor o tramite codice Liquid HTML in modo intuitivo da my.clerk.io.

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

Injection #

Injection è una funzionalità che permette di inserire snippet di contenuto all’interno del sito senza doverlo aggiungere manualmente. Basta scegliere un selettore CSS dove iniettare lo snippet, e Clerk.js lo aggiungerà automaticamente al caricamento della pagina.

Leggi di più su Injection qui.

Configurazione #

Clerk.js permette diverse configurazioni che modificano il suo funzionamento.

Visitor IDs #

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

Se i clienti accettano i cookie, Clerk.js può essere configurato per inserire un cookie persistente con l’ID visitatore, che permette 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 disattivare il tracciamento della sessione impostando visitor a null.

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

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

// Disabling visitor tracking
Clerk('config', {
  visitor: null
});

Language #

Configura Clerk.js con la lingua scritta del sito. Questo viene usato per gestire correttamente la grammatica in Search e per recuperare le traduzioni corrette quando utilizzi i feed multilingua.

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

I valori accettati sono elencati in Lingue supportate.

Funzioni di Design #

Clerk.js supporta l’aggiunta di Formatters e Globals, che possono essere usati per creare funzionalità JavaScript personalizzate per l’ambiente di design.

Formatters #

Sono utilizzati per influenzare o modificare attributi. Ad esempio, puoi voler mostrare solo i primi 40 caratteri di una descrizione, oppure calcolare una percentuale di sconto specifica in base al tipo di cliente loggato.

Globals #

Destinate all’uso con dati frontend che vuoi rendere accessibili nei design. Esempi includono l’importo rimanente per la spedizione gratuita, il nome di un cliente loggato, un simbolo di valuta o un tasso di conversione.

Ecco un esempio di configurazione di formatters e globals.

Configurazione #

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 email nella sessione del cliente, per personalizzare le raccomandazioni email anche se non ha ancora effettuato un ordine.

Questo viene fatto 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 sul sito, registrandolo con log/email quando un visitatore scrive 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"}

Rendering Personalizzato #

Questa funzionalità è usata principalmente con Single Page Apps (SPA), Progressive Web Apps (PWA) e altre applicazioni che non utilizzano caricamenti di pagina tradizionali.

Clerk.js renderizza tutti gli elementi con la classe clerk, ma puoi usare anche altre classi come selettori personalizzati.

Per impostazione predefinita, Clerk richiede di eseguire Clerk("content", "SELECTOR") per rendere il contenuto ogni volta che deve essere visualizzato.

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

Questo comportamento continua fino a che non viene effettuato un refresh completo della pagina.

Debugging #

Clerk.js dispone di una modalità debug integrata che registra informazioni diagnostiche nella console e le mantiene per tutta la sessione attraverso i caricamenti della pagina.

Attiva dalla console:

Clerk("debug");

Oppure tramite parametri URL:

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

Per dettagli sulla struttura delle risposte di debug delle API, vedi Debug delle risposte.

Il debugger ha 4 parametri:

UI Kit #

Clerk.js include un set di strumenti UI per elementi importanti utili a migliorare l’esperienza utente. Questi spesso fanno risparmiare tempo di sviluppo per setup personalizzati.

Instant Search #

Una parte fondamentale di una ricerca e-commerce efficace è ottenere i risultati immediatamente mentre digiti. Il nostro componente UI Instant Search rende questa esperienza rapida e facile da implementare.

Qualsiasi contenuto Clerk.io può teoricamente essere convertito in una Instant Search, ma funziona meglio come dropdown che mostra i risultati della 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>Prodotti che corrispondono a <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 }}">Acquista ora</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Leggi di più sullo strumento UI Instant Search qui.

Search Page #

Una parte fondamentale di una ricerca e-commerce efficace è ottenere buoni risultati. La nostra Search Page rende questa esperienza veloce e semplice da costruire.

La Search Page ti permette di creare una pagina intera che mostra le migliori corrispondenze per una determinata 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>Prodotti che corrispondono a <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 }}">Acquista ora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostra altri risultati
    		</div>
    {% endif %}
  </div>
</span>

Leggi di più sullo strumento UI Search Page qui.

Category Page #

Una pagina categoria ben strutturata è fondamentale per il successo di un business eCommerce. La nostra Category Page rende questa esperienza semplice e veloce da creare. Ti permette di creare una pagina intera che mostra i risultati migliori per qualsiasi 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 }}">Acquista ora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostra altri risultati
    		</div>
    {% endif %}
  </div>
</span>

Leggi di più sullo strumento UI Category Page qui.

Facets #

Clerk.js offre il supporto nativo per la navigazione a filtri dinamici sia per la ricerca sia per le categorie. Tutti gli attributi prodotto che ci invii possono essere usati come facets.

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="Visualizza di più"
  data-facets-searchbox-text="Cerca per "
  data-facets-design="133995">
</span>

Leggi di più sullo strumento UI Facets qui.

Exit Intent #

Il popup exit intent reagisce quando un visitatore tenta di lasciare il sito passando con il mouse vicino al bordo in alto della finestra del browser. Si apre e mostra prodotti interessanti, potenzialmente convertendo un visitatore in fase di uscita in un cliente.

Qualsiasi blocco Element può essere attivato all’intento 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>

Leggi di più sullo strumento UI Exit Intent qui.

Popup #

Lo UI Kit contiene una semplice libreria per popup, facile da usare per creare popup user-friendly con qualsiasi contenuto. Qualsiasi elemento HTML sul sito con la classe clerk-popup verrà mostrato come popup.

<div id="my-popup" class="clerk-popup">Ciao, mondo!</div>

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

Leggi di più sullo strumento UI Popup qui.

Esclusione Prodotti #

Clerk.js prevede due modi diversi di escludere prodotti, a seconda che tu voglia escludere ID specifici oppure evitare la visualizzazione di prodotti duplicati tra vari slider.

Esclusione di ID Specifici #

Aggiungi semplicemente l’attributo data-exclude nello snippet. Il contenuto di data-exclude dovrebbe essere una lista degli ID dei prodotti che non vuoi vengano mostrati, ad esempio i prodotti nel carrello del cliente o che non possono essere visualizzati.

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

Evitare i Duplicati #

Si effettua aggiungendo l’attributo data-exclude-from sul blocco Clerk dove vuoi rimuovere il duplicato. Il valore dell’attributo deve essere un selettore CSS per l’altro/gli altri snippet da cui prevenire i duplicati.

Nell’esempio sotto, .clerk-2 esclude qualsiasi prodotto presente in .clerk-1, e .clerk-3 esclude qualsiasi prodotto in .clerk-1 o .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>

Eventi #

Quando crei setup più personalizzati avrai spesso bisogno di reagire o modificare i risultati di Clerk prima di renderizzarli. Qui tornano utili gli Eventi.

Gli eventi ti permettono di impostare listener che eseguono codice in momenti specifici prima, durante o dopo che Clerk.js abbia renderizzato i suoi risultati.

Un esempio comune è caricare prezzi personalizzati per un cliente loggato in uno scenario B2B. Un evento può essere eseguito subito dopo che l’API di Clerk ha finito di renderizzare, permettendoti di recuperare prezzi custom 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;
    }
})

Leggi di più sugli Eventi qui.

SEO e Performance #

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

SEO e Velocità #

È un misconception pensare che funzioni JavaScript come Clerk.js danneggino la performance o la SEO. Gli strumenti automatizzati spesso ignorano ottimizzazioni come caching, caricamenti paralleli e gestione lato server.

Benefici dell’Integrazione Clerk.js #

• Lo script Clerk.js (≈ 37 - 38 KB) si carica asincronamente, permettendo al sito di renderizzare mentre Clerk si inizializza.
• Gli elementi Clerk sono renderizzati lato client, quindi il tuo HTML base resta memorizzabile in cache e le componenti dinamiche vengono iniettate solo dopo il caricamento.
• Questo consente caching efficiente lato server e caricamento non bloccante degli asset Clerk.js.

Impatto sulle Performance #

• La leggerezza e l’asincronicità di Clerk.js comportano tipicamente un impatto minimo sui tempi di caricamento pagina.
• Nella realtà, il peso aggiuntivo deriva spesso dalle immagini aggiunte nelle recommendations, non dallo script stesso. Per minimizzare l’impatto:
  • Usa formati efficienti come WebP.
  • Ridimensiona le immagini alla dimensione di visualizzazione (es: 400×400 px → max 420×420 px).
• Per evitare salti di layout (CLS), riserva spazio per i contenuti Clerk iniettati.

Es.:

.clerk-slider-wrapper {
  min-height: 300px; /* regola secondo necessità */
  width: 100%;
}

Considerazioni SEO #

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

Linking e Scansione #

• Clerk.js inietta i link di raccomandazione dinamicamente lato client.
• Questi link possono migliorare l’interlinking interno collegando pagine correlate se i motori di ricerca li renderizzano e seguono correttamente.
• Poiché sono inseriti da JavaScript, dovresti verificare come i crawler li renderizzano e interpretano.
• Se correttamente scansionati, consentono ai motori di scoprire e indicizzare più pagine.

Distribuzione PageRank #

• Quando i motori di ricerca possono scansionarli, i link Clerk.js possono aiutare a distribuire authorità (PageRank) alle pagine chiave.
• Questo supporta maggiore visibilità e posizionamento delle pagine prodotto e categoria.

Benefici osservati #

• Un’integrazione Clerk.js corretta può correlare con una migliore struttura di linking interna, a vantaggio della visibilità sui risultati di ricerca.
• Le dashboard Clerk.io forniscono analytics sull’influenza sugli ordini, aumento delle conversioni e contributo al fatturato da Search, Recommendations, Email e Audience.

Best Practice raccomandate #

1. Ottimizza le immagini (formato WebP, giusta risoluzione).
2. Riserva spazio di layout per gli elementi dinamici per evitare sloittamenti di layout.
3. Monitora le metriche reali invece di affidarti solo ai punteggi automatici. Usa le dashboard Clerk per valutare l’impatto sui vari canali.