Clerk.js

Panoramica #

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

Ci sono tre vantaggi nell’usare Clerk.js:

• È robusta, poiché viene caricata in modo asincrono. Ciò 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 renderizzare la pagina in parallelo mentre Clerk.js effettua chiamate e mostra i risultati.
• Il tracciamento di visitatori e 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 ruota ogni 30 giorni.

Clerk.js si carica con uno script di inizializzazione aggiunto all’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, e configura Clerk.js con la API key così sa già per quale Store deve effettuare chiamate API.

Snippet #

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

Poi usa gli attributi dello snippet per costruire una chiamata API acquisendo la chiave API dalla config nello script di inizializzazione.

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

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

Clerk.js usa Liquid designs per generare HTML con i dati restituiti dall’API. Questi sono formattati come script, referenziati dal loro ID in 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>Risultato della Search 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 semplicemente un 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 vengono 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, qualsiasi informazione specifica della pagina come gli ID dei prodotti, e un riferimento all’ID di un blocco Element in data-template.

Iniezione #

L’injection è una funzione che ti consente di inserire snippet di contenuto all’interno del tuo sito web senza doverlo fare manualmente. Basta scegliere un selettore CSS in cui iniettare lo snippet, e Clerk.js lo aggiungerà automaticamente al caricamento della pagina.

Leggi di più sull’ Injection qui.

Configurazione #

Clerk.js consente una varietà di configurazioni che modificano il suo funzionamento.

ID Visitatori #

Per impostazione predefinita, Clerk.js genera ID anonimi dei visitatori, usati per tracciare le sessioni.

Se i clienti accettano i cookie, Clerk.js può essere configurato per salvare un cookie persistente con l’ID visitatore, permettendo il tracciamento su periodi più lunghi.

Se preferisci gestire manualmente gli ID di sessione, puoi configurare il parametro visitor usato 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 visitatori
Clerk('config', {
  visitor: null
});

Contesto Pagina #

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

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

Lingua #

Configura Clerk.js con la lingua scritta del sito web. Questo viene usato da Clerk.io per gestire correttamente la grammatica in Search e per recuperare le giuste traduzioni quando usi feed multilingua.

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

I valori accettati sono elencati sotto 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 visualizzata dal visitatore:

• product: L’ID del prodotto visualizzato nelle pagine prodotto. Impostalo su null per le pagine non prodotto.
• category: L’ID della categoria visualizzata nelle pagine categoria. Impostalo su null per le pagine non categoria.
• page: Un identificativo o una stringa per altre pagine come homepage, carrello o checkout. Impostalo su null se non applicabile.

Se la tua piattaforma non ha uno specifico ID disponibile per un tipo di pagina, lascia il valore a null. Imposta solo i valori per i tipi di pagina rilevanti.

Funzioni Design #

Clerk.js permette di aggiungere Formatters e Globals, che possono essere usati per creare funzionalità javascript personalizzate per i tuoi design scope.

Formatters #

Si usano per influenzare o modificare attributi. Per esempio, puoi voler mostrare solo i primi 40 caratteri di una descrizione, o dover calcolare una percentuale di sconto specifica in base al cliente loggato.

Globals #

Servono per dati frontend che desideri utilizzare nei design. Può trattarsi di esempi come l’importo mancante 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 gli indirizzi email nella sessione del cliente, da usare per personalizzare email recommendations anche se non hanno ancora effettuato un ordine.

Abilita collect_email nella tua configurazione di Clerk.js:

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

Con questa funzione attiva, Clerk.js monitora i campi email e invia automaticamente log/email quando un visitatore inserisce un indirizzo email.

Se vuoi registrare manualmente un’email, puoi anche aggiungere uno snippet come questo:

<span class="clerk" data-api="log/email" data-email="EMAIL@EXAMPLE.COM"></span>

Come avviene l’associazione #

Quando viene registrata un’email, Clerk invia sia l’ID visitatore sia l’indirizzo email all’API in modo che possano essere collegati.

Così, Clerk può identificare ciò che quel visitatore ha fatto nella sua sessione storica (ad esempio prodotti visualizzati, click e ricerche) e associare tale comportamento all’indirizzo email.

Con questa associazione, gli stessi dati comportamentali possono essere usati sia per casi d’uso email (come email trigger e personalizzate) che per la personalizzazione onsite nelle recommendations per clienti loggati.

Rendering Personalizzato #

Questa funzione si utilizza principalmente con Single Page Apps (SPA), Progressive Web Apps (PWA) e altre applicazioni che non usano caricamenti di pagina tradizionali.

Clerk.js renderizza qualsiasi elemento con la classe clerk, ma si possono usare anche altre classi per personalizzare il rendering tramite selettori custom.

Di default, occorre eseguire Clerk("content", "SELECTOR") per renderizzare il contenuto ogni volta che deve essere mostrato.

Aggiungendo auto_init_custom_selectors: true nella config, Clerk.js inizializza automaticamente qualsiasi elemento custom selector quando il DOM cambia, purché sia stato già renderizzato con Clerk("content", "SELECTOR") almeno una volta.

Questo comportamento resta attivo fino a un refresh completo della pagina.

Debug #

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

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

Console shorthand

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

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

Config path

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

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

URL hash

Puoi attivare la modalità debug aggiungendo un hash alla URL. Utile per condividere link di debug con colleghi:

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

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

Opzioni Config #

Session Storage #

Quando la modalità debug è attivata, la configurazione viene salvata su sessionStorage nella chiave __clerk_debug. Ciò assicura che le impostazioni di debug restino attive man mano che i visitatori navigano tra le pagine, senza influire su altre tab del browser o durare oltre la sessione.

Piattaforme di gestione del consenso (CMP) come Cookiebot possono segnalare __clerk_debug come elemento di storage che richiede documentazione. Si tratta di una chiave funzionale utilizzata esclusivamente per il debug degli sviluppatori. Non contiene dati personali né informazioni di tracciamento.

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

UI Kit #

Clerk.js include una serie di strumenti UI per elementi importanti che possono essere usati per migliorare l’esperienza utente. Spesso fanno risparmiare tempo di sviluppo per configurazioni personalizzate.

Instant Search #

Una parte chiave di una grande esperienza di search 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 Clerk.io può teoricamente essere trasformato in un componente Instant Search, ma funziona al meglio come un dropdown che mostra i risultati di search.

<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 corrispondenti 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 grande esperienza search e-commerce è ottenere buoni risultati di ricerca. La nostra Search Page rende questa esperienza facile e veloce da realizzare.

La Search Page consente di creare una pagina intera che mostra i migliori risultati 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 corrispondenti 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 eCommerce. La nostra Category Page rende questa esperienza rapida e facile da realizzare. Ti permette di creare una pagina intera che mostra i migliori risultati possibili 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 }}">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 include il supporto integrato per la navigazione dinamica a faccette sia per i risultati di search sia per le categorie. Qualsiasi attributo prodotto che ci invii può essere usato come faccetta.

Ecco un esempio di utilizzo di 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 UI Facets qui.

Exit Intent #

Il popup exit intent reagisce quando un visitatore cerca di lasciare il sito muovendo il mouse vicino al bordo superiore della finestra del browser. Si apre e mostra prodotti interessanti, potenzialmente convertendo un visitatore in 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 #

La UI Kit contiene una semplice libreria popup per creare popup immediati ma user-friendly con qualsiasi contenuto. Qualsiasi elemento HTML del 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 popup
  my_popup.show(); 
  /* oppure */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // chiudi popup
  my_popup.hide(); 
  /* oppure */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Leggi di più sullo strumento UI Popup qui.

Esclusione Prodotti #

Clerk.js ha due modi differenti 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 dovrebbe essere una lista degli ID dei prodotti che non vuoi mostrare (ad esempio 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 realizza aggiungendo l’attributo data-exclude-from sul blocco Clerk dove vuoi rimuovere i duplicati. Il valore dell’attributo deve essere il selettore CSS degli altri snippet da cui vuoi escludere i duplicati.

Nell’esempio qui sotto, .clerk-2 esclude qualsiasi prodotto presente in .clerk-1, e .clerk-3 esclude qualsiasi prodotto sia in .clerk-1 che in .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 configurazioni personalizzate è spesso necessario reagire o modificare i risultati di Clerk prima del rendering. Qui entrano in gioco gli Eventi.

Gli Eventi ti consentono di impostare degli event listener che eseguono codice in momenti specifici prima, durante o dopo che Clerk.js ha renderizzato i suoi risultati.

Un esempio comune è caricare prezzi personalizzati per un cliente loggato in una configurazione B2B. Un evento può essere eseguito subito dopo il rendering dell’API di Clerk, permettendo di recuperare prezzi personalizzati per il cliente e inserirli negli 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 abilita esperienze di acquisto personalizzate senza rallentare il sito o penalizzare la SEO. Grazie all’uso del rendering lato client e al caricamento ottimizzato, bilancia velocità, performance e visibilità di ricerca.

SEO e Velocità #

È un equivoco pensare che funzionalità JavaScript come Clerk.js peggiorino le performance o la SEO. Gli strumenti automatizzati spesso trascurano ottimizzazioni come caching, caricamento parallelo e gestione server-side.

Vantaggi dell’integrazione Clerk.js #

• Lo script Clerk.js (≈ 37 - 38 KB) viene caricato in modo asincrono, permettendo al sito di renderizzare mentre Clerk si inizializza.
• Gli elementi Clerk sono generati lato client, quindi l’HTML di base resta cacheabile e i componenti dinamici vengono iniettati solo dopo il caricamento.
• Questo consente un caching lato server efficiente e il caricamento non bloccante degli asset Clerk.js.

Impatto sulle Prestazioni #

• La natura leggera e asincrona di Clerk.js comporta un impatto minimo sui tempi di caricamento pagina.
• Nella pratica, il rallentamento reale è spesso dovuto alle immagini aggiuntive mostrate nelle recommendations, non allo script in sé. Per ridurre questo impatto:
  • Usa formati efficienti come WebP.
  • Ridimensiona le immagini alle dimensioni di visualizzazione (es. 400×400 px → max 420×420 px).
• Per evitare uno spostamento del layout (CLS), riserva spazio per i contenuti Clerk iniettati.

Esempio:

.clerk-slider-wrapper {
  min-height: 300px; /* regola 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 la user-experience che la visibilità nella ricerca.

Collegamenti e Scanabilità #

• Clerk.js inietta collegamenti di recommendations dinamicamente lato client.
• Questi collegamenti possono migliorare il linking interno collegando pagine correlate, se i motori di ricerca li rendono e li seguono correttamente.
• Poiché sono iniettati via JavaScript, è necessario verificare come i crawler li interpretano e seguono.
• Se sono correttamente scansionati, i link migliorano la scanabilità e consentono ai motori di ricerca di scoprire e indicizzare più pagine.

Distribuzione PageRank #

• Quando i motori di ricerca li possono scansionare, i link iniettati da Clerk.js possono aiutare a distribuire il PageRank sulle pagine chiave.
• Questo supporta una migliore visibilità e ranking di pagine prodotto e categoria.

Benefici Osservati #

• Una corretta integrazione di Clerk.js può correlarsi con una struttura di linking interno più forte, il che può aiutare a migliorare la visibilità nei risultati di ricerca.
• Le dashboard Clerk.io forniscono analytics su influenza ordini, aumento delle conversioni e ricavi attribuibili alle funzioni Search, Recommendations, Email e Audience.

Best Practice Raccomandate #

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