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 prima di caricarsi.
• È spesso più veloce, poiché il tuo server può iniziare a renderizzare la pagina in parallelo mentre Clerk.js effettua le 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 e dello useragent del visitatore, combinato con un sale unico del negozio che viene ruotato ogni 30 giorni.

Clerk.js si carica tramite uno script di inizializzazione aggiunto nell’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 API key così da sapere già per quale Store sta effettuando le chiamate API.

Snippet #

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

Successivamente, utilizza gli attributi dello snippet per costruire una chiamata API ottenendo la API key dalla configurazione nello script di inizializzazione.

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

La visualizzazione è gestita dal Design, anch’esso referenziato dallo snippet.

Clerk.js utilizza i Liquid design per renderizzare l’HTML con i dati restituiti dall’API. Questi sono formattati come script, referenziati tramite il loro ID in data-template all’interno 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>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 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 con codice HTML Liquid in modo user-friendly da my.clerk.io.

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

Injection #

L’injection è una funzione che ti permette di inserire snippet di contenuto nel tuo sito senza aggiungerli manualmente. Basta scegliere un CSS Selector 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 diverse configurazioni che ne modificano il 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 creare un cookie persistente con il visitor ID, permettendo il tracciamento su un periodo più lungo.

Se preferisci gestire manualmente le session ID, 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'
});

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

Page Context #

Configura Clerk.js con il contesto della pagina che un visitatore sta visualizzando. Questo viene usato per arricchire i dati di tracciamento per funzioni di personalizzazione come Email Triggers, segmentazione Audience e contesto Chat.

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

Lingua #

Configura Clerk.js con la lingua scritta del sito. Serve a Clerk.io per gestire correttamente le regole grammaticali in Search e per recuperare le giuste traduzioni quando sono usati i feed multilingua.

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

I valori accettati sono elencati su Supported languages.

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

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

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

Funzioni di Design #

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

Formatters #

Sono utilizzati per influenzare o modificare 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.

Globals #

Sono pensati per essere utilizzati con dati frontend a cui vuoi accedere nei design. Possono essere, ad esempio, l’importo mancante 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.

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 di raccomandazione anche se non hanno ancora effettuato un ordine.

Abilita collect_email nella tua config di Clerk.js:

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

Con questa funzione abilitata, Clerk.js monitora gli input email e invia automaticamente log/email quando il visitatore inserisce un indirizzo email.

Se desideri registrare manualmente una email, puoi aggiungere anche uno snippet come questo:

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

Clienti loggati #

Se il tuo webshop ha account cliente, chiama log/email ogni volta che l’indirizzo email di un cliente è disponibile nella sessione — sia quando fanno login attivamente sia quando tornano sul sito già loggati.

L’approccio più semplice è controllare ad ogni caricamento pagina se una email è disponibile e, in tal caso, effettuare la chiamata. Per evitare chiamate API non necessarie, memorizza un flag nella sessione browser così da farla solo una volta per sessione:

<script type="text/javascript">
  if (!sessionStorage.getItem('clerk_email_logged')) {
    Clerk('call', 'log/email', {
      email: 'CUSTOMER_EMAIL'
    });
    sessionStorage.setItem('clerk_email_logged', '1');
  }
</script>

Sostituisci CUSTOMER_EMAIL con l’effettivo indirizzo email dalla tua piattaforma. Renderizza questo script solo quando un indirizzo email è disponibile — saltalo completamente per i guest.

Senza questa funzione, Clerk.io può collegare la sessione del visitatore a una email solo quando completa un acquisto. Registrandola ogni volta che una email è disponibile, il collegamento avviene subito, requisito per attivare email automatiche in base al comportamento di navigazione, mostrare raccomandazioni personalizzate nelle email, e applicare campagne di Merchandising mirate a specifici segmenti Audience.

Come avviene l’associazione #

Quando viene registrata una email, Clerk invia sia il visitor ID sia l’indirizzo email all’API per collegarli.

Questo permette a Clerk di identificare le attività svolte da quel visitatore nella cronologia sessione (ad esempio prodotti visti, click, ricerche) e associare tali comportamenti all’indirizzo email.

Con questa associazione, gli stessi dati comportamentali possono essere usati sia per l’invio email (es: email trigger e personalizzate) sia per la personalizzazione onsite nelle raccomandazioni per i clienti loggati.

Custom Rendering #

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

Clerk.js renderizza qualsiasi elemento con la classe clerk, ma è possibile usare altre classi per personalizzare il rendering come custom selectors.

Per impostazione predefinita, Clerk necessita che venga chiamato Clerk("content", "SELECTOR") per renderizzare il contenuto ogni volta che deve essere mostrato.

Aggiungendo auto_init_custom_selectors: true alla config, Clerk.js inizializza automaticamente qualsiasi elemento custom selector man mano che il DOM viene modificato, purché siano già stati renderizzati con Clerk("content", "SELECTOR") almeno una volta.

Questo comportamento continua fino a che non avviene un vero refresh della pagina.

Debugging #

Clerk.js possiede una modalità debug integrata che registra informazioni di diagnostica nella console del browser. Salva la configurazione in sessionStorage sotto la chiave __clerk_debug, mantenendo attiva la modalità debug tra le navigazioni nella stessa sessione browser.

Per impostazione predefinita, la modalità debug è abilitata con level impostato su warn e collect su true.

Modalità di Attivazione #

Esistono tre modi per abilitare la modalità debug.

Console shorthand

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

Clerk('debug');              // Abilita con i valori 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 log
Clerk('debug', {             // Passa un oggetto configurazione completo
  enable: true,
  level: 'log',
  group: true
});

Config path

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

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

URL hash

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

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

Quando è attivata via URL hash, la configurazione viene anche salvata in sessionStorage sotto la chiave __clerk_tmp_config.

Opzioni di Config #

Session Storage #

Quando la modalità debug è attivata, la configurazione viene salvata su sessionStorage come __clerk_debug. Questo garantisce che le impostazioni di debug persistano tramite la navigazione tra le pagine senza influenzare altre tab o durare oltre la sessione.

Consent Management Platforms (CMP) come Cookiebot potrebbero segnalare __clerk_debug come uno storage che richiede documentazione. Si tratta di una chiave funzionale usata solo per scopi di debug da sviluppatore. Non contiene dati personali o informazioni di tracciamento.

Per dettagli sulla struttura delle risposte di 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 setup personalizzati.

Instant Search #

Un elemento fondamentale di una grande esperienza di ricerca e-commerce è ottenere risultati immediati appena inizi a digitare. Il componente UI Instant Search rende questa esperienza veloce e semplice da costruire.

Qualsiasi contenuto Clerk.io può, in teoria, essere trasformato in un Instant Search component, ma funziona meglio come un dropdown 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>

Leggi di più sullo strumento UI Instant Search qui.

Search Page #

Un elemento fondamentale dell’esperienza di ricerca e-commerce è ottenere risultati di qualità. La nostra Search Page rende questa esperienza veloce e semplice da realizzare.

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

<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 categoria ben strutturata è fondamentale per il successo di un business eCommerce. La nostra Category Page rende questa esperienza veloce e semplice da costruire. Permette 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 }}">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 supporto integrato per la navigazione dinamica attraverso facets sia nella ricerca che nelle categorie. Qualsiasi attributo di prodotto inviato a Clerk.io può essere usato come facet.

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 di exit intent reagisce se un visitatore prova a lasciare il sito portando il cursore vicino al bordo superiore della finestra. Appare mostrando prodotti interessanti, potenzialmente convertendo un visitatore in uscita in un cliente.

Un qualsiasi blocco Element può essere attivato sull’intento 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 user-friendly con qualsiasi contenuto. Qualsiasi elemento HTML sul tuo sito con la classe clerk-popup sarà 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>

Leggi di più sullo strumento UI Popup qui.

Chat #

Clerk.js espone un’interfaccia JavaScript per controllare il widget di Chat e reagire agli eventi di conversazione. Questo è utile quando vuoi attivare la chat dalla tua UI, passare dati contestuali all’AI su cosa sta facendo il visitatore, o integrare gli eventi conversazionali con il frontend.

La documentazione completa di metodi ed eventi è disponibile nelle Chat JS docs.

Aprire Chat da un Bottone Personalizzato #

Se vuoi attivare Chat da un tuo bottone o elemento UI invece del launcher predefinito, usa toggle:

<button onclick="Clerk('chat', 'toggle')">
  Need help?
</button>

Puoi anche usare open e close indipendentemente per controllare lo stato in modo esplicito.

Mostrare Chat Solo su Pagine Specifiche #

Per default, Chat è visibile su tutto il sito. Per mostrarla solo su alcune pagine, disattivala via config globale e abilitala selettivamente:

// Config globale Clerk.js — nascondi Chat ovunque
Clerk('config', { key: 'your-public-api-key' });
Clerk('chat', 'disable');

// Poi, sulle pagine in cui vuoi mostrarla
Clerk('chat', 'enable');

Passare Contesto Carrello e Pagina all’AI #

Il metodo metadata invia contesto strutturato a Chat così che l’AI possa dare risposte più rilevanti. Chiamalo ogni volta che il contesto del visitatore cambia: navigazione pagina, aggiunta al carrello, modifica preferenze.

// Su una pagina prodotto
Clerk('chat', 'metadata', {
  current_page: {
    page_type: 'product',
    page_id: '12345'
  }
});

// Dopo che il visitatore aggiunge un prodotto al carrello
Clerk('chat', 'metadata', {
  cart: {
    items: [
      { id: 101, name: 'Lightsaber', price: 99.95 },
      { id: 204, name: 'Force Gloves', price: 29.95 }
    ],
    total: 129.90
  }
});

La struttura del payload è flessibile: includi il contesto più utile per la conversazione che avviene su quella pagina.

Modificare il Comportamento AI in Base alle Azioni del Visitatore #

Il metodo prompt_message invia un’istruzione a livello di sistema all’AI. Il cliente non la vede mai, ma cambia la risposta AI nella conversazione corrente.

// Dopo aver aggiunto al carrello — suggerisci cross-sell all’AI
Clerk('chat', 'prompt_message', 'The user just added a Lightsaber to their cart. Suggest complementary products like accessories or protective gear.');

// Su pagina checkout — focus sul concludere l’ordine
Clerk('chat', 'prompt_message', 'The user is on the checkout page. Help them complete their order and answer any last-minute questions.');

Handoff a Operatore Umano #

Quando un visitatore ha bisogno di supporto umano, l’evento onSupport si attiva con un riassunto della conversazione. Usa questo evento per aprire la chat helpdesk e passare il contesto all’operatore, così non è necessario che il visitatore ripeta tutto.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onSupport: (e) => {
      // e.summary contiene un riassunto testuale della conversazione
      const summary = e.summary || 'No conversation summary available.';

      // Esempio: apri Intercom con riassunto precompilato
      if (window.Intercom) {
        Intercom('showNewMessage', 'Continuing from AI Chat:\n\n' + summary);
      }

      // Esempio: apri Zendesk con contesto precompilato
      if (window.zE) {
        zE('messenger', 'open');
        zE('messenger:set', 'conversationFields', [
          { id: 'clerk_chat_summary', value: summary }
        ]);
      }

      // Facoltativo: nascondi Chat Clerk dopo l’handoff
      Clerk('chat', 'disable');
    }
  }
});

L’evento onSupport si attiva solo quando Contact Support è configurato nelle impostazioni Chat e il visitatore richiede esplicitamente un operatore.

Reagire agli Eventi Chat #

Usa gli hook degli eventi per integrare il comportamento Chat col resto del frontend: esempio logging dei messaggi, sincronizzazione stato, handoff.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onMessage: (e) => {
      // Si attiva per ogni messaggio — ruolo: 'user', 'ai', 'results'
      console.log(e.message.role, e.message.text);
    },
    onOpen: (e) => {
      // Si attiva all’apertura/chiusura Chat
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Si attiva per richiesta operatore umano
      // e contiene il riassunto conversazione
      openLiveChatWithSummary(e);
    }
  }
});

Puoi anche registrare hook dinamicamente dopo la configurazione iniziale:

Clerk('chat', 'on', 'message', function(e) {
  console.log('New message:', e.message.text);
});

Leggi di più nelle Chat JS docs.

Escludere Prodotti #

Clerk.js possiede due modalità distinte per escludere prodotti: in base a ID specifici o per evitare duplicati tra diversi slider.

Escludere ID Specifici #

Aggiungi semplicemente l’attributo data-exclude allo snippet. Il contenuto di data-exclude deve essere una lista degli ID prodotto che non vuoi vengano mostrati, ad esempio i prodotti nel carrello del cliente o prodotti non autorizzati.

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

Evitare Duplicati #

Questo si fa aggiungendo l’attributo data-exclude-from sul Clerk Block dove vuoi eliminare il duplicato. Il valore dell’attributo deve essere il CSS selector dello/gli snippet da cui vuoi evitare duplicati.

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

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

Un esempio comune è caricare prezzi personalizzati per un cliente B2B loggato. Un evento può partire subito dopo il rendering API, permettendo di recuperare prezzi custom dal tuo server 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 d’acquisto 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à #

È un errore pensare che funzionalità JavaScript come Clerk.js danneggino SEO e performance. Gli strumenti automatici 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 asincronamente, così il sito si renderizza mentre Clerk si avvia.
• Gli elementi Clerk sono renderizzati lato client: l’HTML base resta cacheabile e i componenti dinamici vengono iniettati solo dopo il caricamento.
• Questo abilita caching server-side efficiente e caricamento non-bloccante degli asset Clerk.js.

Impatto sulle Performance #

• La leggerezza e l’asincronia di Clerk.js comportano un impatto minimo sui tempi di caricamento pagina.
• L’impatto vero spesso dipende dalle immagini aggiuntive visualizzate nelle raccomandazioni, non dallo script. Per minimizzare:
  • Usa formati ottimizzati come WebP.
  • Ridimensiona le immagini rispetto alle dimensioni display (es. 400×400 px → 420×420 px max).
• Per evitare spostamenti layout (CLS), riserva spazio per i contenuti Clerk iniettati.

Esempio:

.clerk-slider-wrapper {
  min-height: 300px; /* modifica a piacere */
  width: 100%;
}

Considerazioni SEO #

Sapere come Clerk.js interagisce con i motori di ricerca aiuta a garantire sia esperienza utente che visibilità SEO.

Linking e Crawlabilità #

• Clerk.js inietta i link alle raccomandazioni dinamicamente lato client.
• Questi link possono migliorare l’internal linking collegando le pagine simili, se i motori li renderizzano e seguono correttamente.
• Poiché sono iniettati via JavaScript, verifica come i crawler visualizzano le pagine.
• Link adeguatamente scansionati possono migliorare la crawlabilità e consentire ai motori di scoprire e indicizzare più pagine.

Distribuzione PageRank #

• Quando i motori possono scansionarli, i link Clerk.js contribuiscono a distribuire il PageRank tra le pagine chiave.
• Ciò sostiene la visibilità e il ranking delle pagine prodotto e categoria.

Benefici Osservati #

• Un’integrazione Clerk.js corretta può correlarsi a una struttura di linking interno più solida, che facilita la visibilità nei risultati di ricerca.
• Le dashboard Clerk.io forniscono analytics su influenza ordini, aumento conversioni e ricavi da Search, Recommendations, Email e Audience.

Best Practice Raccomandate #

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