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 dalla risposta dell’API prima del caricamento.
• Spesso è più veloce, poiché il tuo server può iniziare a renderizzare la pagina in parallelo mentre Clerk.js effettua chiamate e renderizza i risultati.
• Il tracciamento dei visitatori e dei click è gestito automaticamente per tutti i risultati mostrati da Clerk. Questo non richiede cookie, poiché generiamo un valore hash dell’indirizzo IP del visitatore e dello useragent, combinato con un sale univoco dello store che ruota ogni 30 giorni.

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

<!-- 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 sta effettuando le chiamate API.

Snippet #

Quando la pagina è caricata, Clerk.js la scansiona alla ricerca di qualsiasi snippet con la classe “clerk”.

Utilizza poi 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 visiva è gestita tramite il Design, che viene referenziato dallo snippet stesso.

Clerk.js utilizza i design Liquid per renderizzare l’HTML con i dati restituiti dall’API. Questi sono formattati come script e referenziati tramite il loro ID nell’attributo data-template del 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>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 altri risultati</a>
</script>

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

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

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

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

Injection #

L’injection è una funzionalità che permette di inserire automaticamente snippet di contenuto nel tuo sito senza doverli aggiungere manualmente. Basta scegliere un selettore CSS dove iniettare lo snippet, e Clerk.js lo aggiungerà automaticamente al caricamento della pagina.

Leggi di più sull’ Injection qui.

Configurazione #

Clerk.js permette varie configurazioni che cambiano come funziona.

ID dei Visitatori #

Di default, Clerk.js genera ID visitatori anonimi, usati per tracciare le sessioni.

Se i clienti accettano i cookie, Clerk.js può essere configurato per inserire un cookie persistente con l’ID visitatore, consentendo il tracciamento su un periodo più lungo.

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

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

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

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

Contesto della Pagina #

Configura Clerk.js con il contesto della pagina che il visitatore sta visualizzando. Questo serve per arricchire i dati di tracciamento per funzionalità di personalizzazione come i Trigger Email, la segmentazione Audience e il contesto Chat.

Clerk('context', {
  product: null,  // Imposta l’ID prodotto sulle pagine prodotto, es. 12345 o null
  category: null, // Imposta l’ID categoria sulle pagine categoria, es. 67 o null
  page: null      // Imposta l’ID pagina o tipo sulle altre pagine, es. 'homepage' o null
});

Lingua #

Configura Clerk.js con la lingua scritta del sito. Questo serve a Clerk.io per gestire correttamente la grammatica nella Search, e per recuperare le traduzioni corrette quando usi feed multilingua.

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

I valori accettati sono elencati in Lingue supportate.

Sostituisci i valori segnaposto con la logica della tua piattaforma per ottenere dinamicamente gli ID. Ogni valore deve essere impostato in base al tipo di pagina in cui si trova il visitatore:

• product: L’ID del prodotto visualizzato nelle pagine prodotto. Impostare su null nelle altre pagine.
• category: L’ID della categoria visualizzata nelle pagine categoria. Impostare su null nelle altre pagine.
• page: Un identificativo o tipo di pagina nelle altre tipologie di pagina come homepage, carrello o checkout. Impostare su null se non applicabile.

Se la tua piattaforma non ha un ID specifico disponibile per un certo tipo di pagina, lascia il valore impostato su null. Imposta solo i valori per le tipologie di pagina rilevanti.

Funzioni Design #

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

Formatter #

Servono a 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 connesso.

Global #

Sono dati frontend che vuoi rendere disponibili nei design. Possono essere l’importo mancante per la spedizione gratuita, il nome del cliente autenticato, il simbolo della 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>

Tracciamento Email #

Clerk.js può raccogliere automaticamente le email nella sessione del cliente per personalizzare le raccomandazioni email 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>

In questo modo Clerk.js monitorerà tutti i campi input nel sito, e lo registrerà 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"}

Rendering Personalizzato #

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

Clerk.js renderizza tutti gli elementi con la classe clerk, ma possono essere utilizzate altre classi come selettori personalizzati.

Di default, Clerk richiede di eseguire Clerk("content", "SELECTOR") per renderizzare i contenuti ogni volta che devono essere mostrati.

Aggiungendo auto_init_custom_selectors: true alla config, Clerk.js inizializza automaticamente ogni elemento con selettore personalizzato man mano che il DOM si aggiorna, purché siano già stati renderizzati almeno una volta con Clerk("content", "SELECTOR").

Questo comportamento prosegue fino a che non avviene un refresh totale della pagina.

Debugging #

Clerk.js dispone di una modalità debug integrata che registra informazioni diagnostiche nella console del browser. Mantiene la configurazione in sessionStorage sotto la chiave __clerk_debug, mantenendo la modalità debug attiva tra le navigazioni di pagina all’interno della stessa sessione del browser.

Di default, la modalità debug è attiva con level impostato su warn e collect su true.

Modalità di Attivazione #

Ci sono tre modi per attivare la modalità debug.

Comando console

Il modo più semplice è chiamare Clerk('debug') dalla console del browser. Accetta diversi formati di argomento:

Clerk('debug');              // Abilita con impostazioni di default
Clerk('debug', true);        // Abilita
Clerk('debug', false);       // Disabilita
Clerk('debug', 'on');        // Abilita
Clerk('debug', 'off');       // Disabilita
Clerk('debug', 'warn');      // Imposta direttamente il livello di log
Clerk('debug', {             // Passa un oggetto di configurazione completo
  enable: true,
  level: 'log',
  group: true
});

Percorso config

La modalità debug può essere configurata anche tramite la normale chiamata config:

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

Hash nell’URL

La modalità debug può essere attivata aggiungendo un frammento hash all’URL. Utile per condividere link di debug con colleghi:

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

Quando viene attivata tramite hash dell’URL, la configurazione viene memorizzata anche in sessionStorage sotto la chiave __clerk_tmp_config.

Opzioni di Configurazione #

Session Storage #

Quando la modalità debug è attivata, la configurazione viene salvata in sessionStorage sotto la chiave __clerk_debug. Questo assicura che le impostazioni di debug persistano durante la navigazione tra pagine, senza influenzare altre schede o oltre la durata della sessione.

Piattaforme di gestione del consenso (CMP) come Cookiebot potrebbero segnalare __clerk_debug come voce di storage che richiede documentazione. Si tratta di una chiave funzionale utilizzata esclusivamente per scopi di debug per sviluppatori. Non contiene dati personali o informazioni di tracciamento.

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

UI Kit #

Clerk.js include una serie di strumenti UI per elementi chiave che possono essere utilizzati per migliorare l’esperienza utente. Spesso aiutano a risparmiare tempo nello sviluppo di configurazioni personalizzate.

Instant Search #

Una parte essenziale di una buona esperienza di ricerca e-commerce è ottenere risultati immediati mentre si digita. Il nostro componente UI Instant Search rende questa esperienza veloce e semplice da costruire.

Ogni contenuto di Clerk.io può teoricamente essere trasformato in un componente Instant Search, ma funziona al meglio come tendina 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 trovati per <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 #

Un elemento chiave di una buona esperienza di ricerca e-commerce è ottenere ottimi risultati di ricerca. La nostra Search Page rende questa esperienza semplice e veloce da realizzare.

La Search Page consente di creare una pagina intera 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>Prodotti trovati per <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 un eCommerce di successo. La nostra Category Page rende questa esperienza semplice e veloce da costruire. Consente di creare una pagina intera che mostra i migliori risultati per ogni 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.

Facet #

Clerk.js include il supporto integrato alla navigazione faccettata dinamica per ricerca e categorie. Qualsiasi attributo di prodotto inviato può essere utilizzato come una facet.

Ecco un esempio 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 altro"
  data-facets-searchbox-text="Cerca "
  data-facets-design="133995">
</span>

Leggi di più sullo strumento UI Facets qui.

Exit Intent #

Il popup exit intent reagisce quando un visitatore cerca di lasciare il sito portando il mouse vicino alla parte alta della finestra del browser. Il popup si apre e mostra prodotti interessanti, possibilmente convertendo un visitatore in partenza in un cliente.

Qualsiasi blocco Element può essere attivato all’intenzione di uscita del 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 #

L’UI Kit include una semplice libreria popup per creare facilmente popup dal design intuitivo con qualsiasi contenuto. Qualsiasi elemento HTML presente nel sito con la classe clerk-popup sarà visibile 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 popup
  my_popup.show(); 
  /* oppure */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // nascondi popup
  my_popup.hide(); 
  /* oppure */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Leggi di più sullo strumento UI Popup qui.

Esclusione Prodotti #

Clerk.js consente due modalità per escludere prodotti: a seconda che tu voglia escludere ID specifici o evitare duplicati tra slider diversi.

Escludere ID Specifici #

Aggiungi semplicemente l’attributo data-exclude allo snippet. Il valore di data-exclude deve essere una lista degli ID dei prodotti che non vuoi mostrare, per esempio i prodotti nel carrello del cliente o prodotti che non possono essere visti.

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

Evitare Duplicati #

Questo si realizza aggiungendo l’attributo data-exclude-from sul blocco Clerk dove vuoi rimuovere i duplicati. Il valore dell’attributo deve essere un selettore CSS per gli altri snippet da cui evitare i duplicati.

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

Se desideri realizzare configurazioni avanzate spesso occorre reagire o modificare i risultati di Clerk prima della renderizzazione. Qui sono utili gli Eventi.

Gli eventi permettono di impostare dei listener che eseguono codice in momenti specifici prima, durante o dopo la renderizzazione dei risultati di Clerk.js.

Un esempio comune è caricare prezzi personalizzati per un utente autenticato in un setup B2B. Un evento può essere lanciato immediatamente dopo che la risposta API di Clerk è stata renderizzata, permettendo di recuperare i prezzi personalizzati 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 offre esperienze di shopping personalizzate senza rallentare il sito o danneggiare la SEO. Grazie al rendering client-side e al caricamento ottimizzato, bilancia velocità, performance e visibilità sui motori di ricerca.

SEO e Velocità #

È errato pensare che funzionalità JavaScript come Clerk.js danneggino performance o SEO. Gli strumenti automatici spesso non rilevano ottimizzazioni come cache, caricamento parallelo o gestione server-side.

Vantaggi dell’Integrazione di Clerk.js #

• Lo script Clerk.js (≈ 37 - 38 KB) si carica in modo asincrono, permettendo al sito di renderizzare mentre Clerk si inizializza.
• Gli elementi Clerk sono renderizzati client-side, quindi il tuo HTML di base resta in cache e i componenti dinamici vengono inseriti solo dopo il caricamento.
• Questo abilita caching server-side efficiente e caricamento non bloccante degli asset di Clerk.js.

Impatto sulle Performance #

• La natura leggera e asincrona di Clerk.js comporta generalmente un impatto minimo sui tempi di caricamento della pagina.
• Nel mondo reale, i rallentamenti spesso derivano da immagini aggiuntive mostrate nelle recommendations, non dallo script stesso. Per minimizzare l’impatto:
  • Usa formati efficienti come WebP.
  • Ridimensiona le immagini secondo le dimensioni di visualizzazione (es: 400×400 px → 420×420 px max).
• Per evitare layout shift (CLS), riserva spazio per i contenuti Clerk che saranno iniettati.

Esempio:

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

Aspetti SEO #

Capire come Clerk.js interagisce con i motori di ricerca aiuta a garantire che la tua implementazione sia ottimale sia per l’utente sia per la visibilità sui search engine.

Link interni e Crawlabilità #

• Clerk.js inietta i link alle recommendations dinamicamente lato client.
• Questi collegamenti possono migliorare il linking interno collegando pagine affini, se i motori di ricerca li renderizzano e seguono correttamente.
• Poiché vengono iniettati via JavaScript, è bene verificare come i crawler li interpretano.
• Link opportunamente crawlati possono migliorare la crawlabilità e permettere ai motori di scoprire e indicizzare più pagine.

Distribuzione del PageRank #

• Quando i motori possono eseguirli, i link di Clerk.js aiutano a distribuire la link equity (PageRank) sulle pagine chiave.
• Questo migliora la visibilità e il ranking delle pagine prodotto e categoria.

Benefici Osservati #

• Un’integrazione corretta di Clerk.js può correlare con una struttura di linking interno più robusta, supportando risultati migliori nei motori di ricerca.
• La dashboard di Clerk.io offre analisi su influenza degli ordini, incremento di conversione e contributo di Search, Recommendations, Email e Audience.

Best Practice Consigliate #

1. Ottimizza le immagini (formato WebP, risoluzione corretta).
2. Riserva spazio a layout per evitare layout shift su elementi dinamici.
3. Monitora metriche reali invece di affidarti solo ai punteggi automatici. Usa le dashboard Clerk per valutare l’impatto multi-channel.