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’usare Clerk.js:

• È robusta, poiché viene caricata in modo asincrono. Questo significa che il resto della pagina non dipende dalla risposta di un’API prima del caricamento.
• È spesso più veloce, poiché il tuo server può iniziare a eseguire il rendering della pagina in parallelo mentre Clerk.js effettua chiamate e visualizza 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 del visitatore e dello useragent, combinati con un sale unico dello store che viene ruotato 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 -->

Carica 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 effettuare chiamate API.

Snippet #

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

Utilizza poi gli attributi dello snippet per costruire una chiamata API, ottenendo 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>

L’aspetto visivo viene gestito dal Design, che è anch’esso referenziato dallo snippet.

Clerk.js utilizza i design Liquid per visualizzare l’HTML con i dati restituiti dall’API. Sono formattati come script, referenziati dal loro ID tramite data-template nel tuo 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, utilizzando la sintassi data-template="@content-block-id":

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

I design sono poi gestiti con il Design Editor o con codice Liquid HTML, in modo user-friendly da my.clerk.io.

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

Injection #

Injection è una funzionalità che permette di inserire snippet di contenuto nel tuo sito senza doverli aggiungere manualmente. Basta selezionare un CSS Selector in cui inserire lo snippet, e Clerk.js lo aggiungerà automaticamente al caricamento della pagina.

Leggi di più su Injection qui.

Configurazione #

Clerk.js consente diverse configurazioni che ne cambiano il funzionamento.

Visitor IDs #

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

Se i clienti acconsentono ai cookie, Clerk.js può essere configurato per posizionare un cookie persistente con l’ID visitatore, permettendo il tracciamento su un periodo più lungo.

Se preferisci gestire manualmente gli ID di sessione, puoi configurare il parametro visitor che Clerk utilizza nelle chiamate API. In alternativa, puoi disattivare completamente il tracciamento delle sessioni impostando visitor su null.

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

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

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

Lingua #

Configura Clerk.js con la lingua in cui è scritto il sito web. Questo serve a Clerk.io per gestire correttamente le regole grammaticali in Search, e per recuperare le traduzioni corrette quando utilizzi i feed multilingue.

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 utilizzati per creare funzionalità javascript personalizzate per i tuoi ambiti design.

Formatters #

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

Globals #

Questi sono pensati per essere utilizzati con dati frontend a cui vuoi accedere nei design. Esempi possono essere l’importo rimanente per la spedizione gratuita, il nome di un cliente loggato, un simbolo di valuta o un tasso di conversione.

Di seguito un esempio di configurazione di formatters e 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>

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 raccomandazioni email anche se non ha ancora effettuato ordini.

Questo si ottiene configurando Clerk.js con collect_email: true come mostrato di seguito:

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

Con questa opzione, Clerk.js monitorerà tutti i campi input sul sito, registrando 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 #

Questo è utilizzato principalmente con Single Page App (SPA), Progressive Web App (PWA) e altre applicazioni che non utilizzano caricamenti tradizionali della pagina.

Clerk.js effettua il rendering di tutti gli elementi con la classe clerk, ma possono essere usate anche altre classi per personalizzare il rendering come selettori custom.

Per impostazione predefinita, Clerk richiede che tu esegua Clerk("content", "SELECTOR") per effettuare il rendering del contenuto ogni volta che deve essere visualizzato.

Aggiungendo auto_init_custom_selectors: true alla configurazione, Clerk.js inizializzerà automaticamente qualsiasi elemento selettore personalizzato man mano che il DOM viene modificato, purché sia già stato renderizzato almeno una volta con Clerk("content", "SELECTOR").

Questo comportamento continua fino al refresh completo della pagina.

Debugging #

Clerk.js possiede una modalità debug integrata che registra informazioni diagnostiche nella console.

Abilitala dalla console:

Clerk("debug");

Oppure abilitandola tramite parametri URL:

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

Per dettagli sulla struttura delle risposte di debug API, consulta Response debugging.

Il debugger ha 4 parametri:

UI Kit #

Clerk.js include una serie di strumenti UI per elementi importanti che possono essere utilizzati per migliorare l’esperienza utente. Questi spesso fanno risparmiare tempo di sviluppo per setup custom.

Instant Search #

Una parte chiave di una grande esperienza di ricerca e-commerce è ottenere risultati immediati mentre inizi a digitare. Il nostro componente UI Instant Search rende questa esperienza rapida e facile da realizzare.

Qualsiasi contenuto di Clerk.io può teoricamente essere reso un componente Instant Search, ma funziona al meglio come un menu a discesa 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>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>

Leggi di più sullo strumento UI Instant Search qui.

Search Page #

Una parte importante di una grande esperienza di ricerca e-commerce è ottenere buoni risultati di ricerca. La nostra Search Page rende questa esperienza rapida e semplice da realizzare.

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

Leggi di più sullo strumento UI Search Page qui.

Category Page #

Una pagina di categoria ben strutturata è fondamentale per il successo di un eCommerce. La nostra Category Page rende questa esperienza rapida e facile da costruire. Questo ti permette di creare una pagina completa che mostra i migliori risultati per una determinata 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>

Leggi di più sullo strumento UI Category Page qui.

Facets #

Clerk.js offre il supporto integrato per la navigazione faccettata dinamica sia per la ricerca che per le categorie. Qualsiasi attributo prodotto inviato 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>

Leggi di più sullo strumento Facets qui.

Exit Intent #

Il popup di exit intent reagisce quando un visitatore tenta di lasciare il sito muovendo il mouse vicino alla parte superiore della finestra del browser. Apparirà mostrando prodotti interessanti, permettendo così di convertire un visitatore in uscita in un cliente.

Qualsiasi blocco Content 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 Exit Intent qui.

Popup #

Il UI Kit contiene una semplice libreria popup per creare facilmente popup semplici ma user-friendly con qualsiasi contenuto. Qualsiasi elemento HTML sul tuo sito con la classe clerk-popup verrà visualizzato come popup.

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

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

Leggi di più sullo strumento UI Popup qui.

Esclusione Prodotti #

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

Esclusione di ID Specifici #

Basta aggiungere l’attributo data-exclude allo snippet. Il contenuto di data-exclude deve essere una lista degli ID dei prodotti che non vuoi visualizzare (ad es. 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 in cui vuoi rimuovere il duplicato. Il valore dell’attributo deve essere un selettore CSS per l’altro/gli altri snippet da cui vuoi prevenire i duplicati.

Nell’esempio sotto, .clerk-2 esclude qualsiasi prodotto che sia in .clerk-1 e .clerk-3 esclude tutti i prodotti che siano 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 costruisci configurazioni più personalizzate, spesso avrai bisogno di reagire o modificare i risultati di Clerk prima del rendering. In questo caso sono utili gli Eventi.

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

Un esempio comune è caricare prezzi custom per un cliente loggato in un setup B2B. Un evento può essere eseguito subito dopo che l’API di Clerk ha fatto il rendering, permettendoti di recuperare prezzi personalizzati per un cliente, aggiungendoli 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 Prestazioni #

Clerk.js alimenta esperienze di shopping personalizzate senza rallentare il tuo sito né penalizzare la SEO. Grazie all’uso di rendering lato client e caricamento ottimizzato, equilibra velocità, performance e visibilità sui motori di ricerca.

SEO e Velocità #

È un luogo comune pensare che funzionalità JavaScript come Clerk.js danneggino prestazioni o SEO. Gli strumenti automatizzati spesso trascurano ottimizzazioni come caching, caricamento parallelo e gestione lato server.

Vantaggi 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: il tuo HTML di base resta in cache, e le componenti dinamiche vengono iniettate solo dopo il caricamento.
• Questo consente caching server efficiente e caricamento non bloccante delle risorse di Clerk.js.

Impatto sulle Prestazioni #

• La natura leggera e asincrona di Clerk.js comporta generalmente un impatto minimo sui tempi di caricamento.
• Nella realtà, l’impatto maggiore deriva più dalle immagini aggiuntive visualizzate nelle raccomandazioni che dallo script stesso. Per minimizzare questo impatto:
  • Usa formati ad alta efficienza come WebP.
  • Ridimensiona le immagini per adattarle alle dimensioni di visualizzazione (es. 400×400 px → max 420×420 px).
• Per evitare layout shift (CLS), riserva lo spazio per il contenuto Clerk iniettato.

Es.:

.clerk-slider-wrapper {
  min-height: 300px; /* adatta secondo necessità */
  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 sia la visibilità sui motori stessi.

Collegamento e Crawlability #

• Clerk.js inietta link alle raccomandazioni dinamicamente lato client.
• Questi link possono migliorare il linking interno collegando pagine correlate, se i motori di ricerca li renderizzano e seguono correttamente.
• Poiché vengono iniettati tramite JavaScript, dovresti verificare come i crawler li interpretano.
• I link correttamente esplorati possono migliorare la crawlabilità e permettere ai motori di scoprire e indicizzare più pagine.

Distribuzione del PageRank #

• Quando i motori di ricerca riescono a leggerli, i link di Clerk.js possono aiutare a distribuire l’equità del link (PageRank) tra pagine chiave.
• Questo sostiene la visibilità e ranking di pagine prodotto e categoria.

Benefici Osservati #

• Una corretta integrazione di Clerk.js può correlare con strutture di linking interno più robuste, che possono sostenere la visibilità nelle SERP.
• La dashboard di Clerk.io fornisce analytics su influenza ordini, aumento di conversioni e contributo al fatturato provenienti da Search, Recommendations, Email e Audience.

Best Practice Raccomandate #

1. Ottimizza le immagini (formato WebP, risoluzione corretta).
2. Riserva spazi nel layout per gli elementi dinamici per prevenire shift visivi.
3. Monitora metriche reali invece di basarti solo su indici automatici. Usa le dashboard di Clerk per valutare l’impatto su tutti i canali.