Clerk.js

Panoramica #

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

Ci sono tre vantaggi nell’utilizzare Clerk.js:

• È robusto, perché viene caricato 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 chiamate e mostra i risultati.
• Il tracciamento dei visitatori e dei clic viene gestito automaticamente per qualsiasi risultato mostrato da Clerk. Questo non richiede cookie, poiché generiamo un valore hash dell’IP e dello user agent del visitatore, combinato con un sale unico del negozio che ruota ogni 30 giorni.

Clerk.js viene caricato tramite 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 -->

Questo carica la libreria dal nostro CDN e ti permette di accedere alle sue funzionalità tramite l’oggetto Clerk, configurando Clerk.js con la API key, così da sapere già per quale Store effettuare le chiamate API.

Snippet #

Quando la pagina viene 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 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 parte grafica è gestita dal Design, che viene anch’esso referenziato dallo snippet.

Clerk.js utilizza i Liquid designs per renderizzare l’HTML con i dati restituiti dall’API. Questi sono formattati come script e referenziati tramite il loro ID in data-template all’interno dello 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 di 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 per includere 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 tramite il Design Editor o tramite Liquid HTML code in modo intuitivo 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 #

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

Leggi di più su Injection qui.

Configurazione #

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

Visitor IDs #

Clerk.js genera di default ID visitatore anonimi, utilizzati per tracciare le sessioni.

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

Se preferisci gestire manualmente gli ID di sessione, puoi configurare il parametro visitor che Clerk usa nelle chiamate API. In alternativa, è possibile disabilitare completamente il tracciamento della sessione impostando visitor a null.

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

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

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

Page Context #

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

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

Lingua #

Configura Clerk.js con la lingua scritta del sito. Questo serve per consentire a Clerk.io di gestire correttamente le regole grammaticali in Search e per richiamare le traduzioni corrette quando si usano 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 recuperare dinamicamente gli ID. Ogni valore va impostato in base al tipo di pagina su cui si trova il visitatore:

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

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

Design Functions #

Clerk.js supporta Formatters e Globals, che puoi utilizzare per creare funzionalità javascript personalizzate nei tuoi design.

Formatters #

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

Globals #

Questi servono per accedere a dati frontend utilizzabili nei design. Ad esempio, l’importo rimanente per la spedizione gratuita, il nome di un cliente registrato, il simbolo di valuta o un tasso di conversione.

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 via email anche prima di un ordine.

Abilita collect_email nella configurazione di Clerk.js:

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

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

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

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

Clienti loggati #

Se il tuo webshop è dotato di account cliente, chiama log/email ogni volta che l’email di un cliente noto è disponibile in sessione—sia quando effettua il login, sia quando ritorna sul sito già autenticato.

L’approccio più semplice è controllare a ogni caricamento di pagina se è presente un indirizzo email, e se sì effettuare la chiamata. Per evitare chiamate superflue all’API, memorizza un flag nella session del browser così si attiva una sola 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’indirizzo effettivo dalla tua piattaforma. Mostra questo script solo quando è disponibile un indirizzo email — omettilo completamente per gli ospiti.

Senza questa chiamata, Clerk.io può collegare la sessione email di un visitatore solo quando termina un acquisto. Registrarla ogni volta che disponibile significa collegarla subito, requisito necessario per attivare email automatiche basate sul comportamento di navigazione, mostrare raccomandazioni personalizzate all’interno delle email, ed applicare campagne di Merchandising dedicate a specifici segmenti Audience.

Come funziona l’associazione #

Quando una email viene registrata, Clerk invia sia l’ID visitatore che l’indirizzo email all’API così da collegarli.

Questo permette a Clerk di identificare cosa ha fatto quel visitatore nella sua history di sessione (ad esempio prodotti visualizzati, clic, ricerche) e associare tali comportamenti con l’indirizzo email.

Una volta creata l’associazione, gli stessi dati comportamentali possono essere utilizzati sia per le email (come quelle automatiche o personalizzate), sia per la personalizzazione delle recommendations onsite dei clienti loggati.

DOM Observation #

Abilita l’osservazione DOM se il tuo webshop aggiunge contenuti Clerk.io dopo il caricamento della pagina. Clerk.js osserva i cambiamenti alla struttura della pagina—il DOM—per rilevare contenuti appena appaiono.

Puoi abilitare lo stesso comportamento tramite SPA Auto Detect Changes in my.clerk.io, o aggiungendo observe_dom: true nella configurazione di Clerk.js.

Esempio Side Cart #

Immagina che il tuo webshop crei il side cart solo quando un visitatore aggiunge un prodotto. Il carrello include uno snippet di recommendation Clerk.io, che quindi viene aggiunto quando il carrello si apre.

Con l’approccio timer-based, Clerk.js controlla cambiamenti una volta al secondo. Lo snippet recommendation può dunque apparire solo al prossimo check.

Con observe_dom attivo, l’aggiunta del side cart fa immediatamente scattare il controllo. Clerk.js riconosce subito lo snippet e inizia a mostrare le recommendations, riducendo l’attesa dopo la comparsa del carrello.

Altri esempi #

Lo stesso comportamento è utile in altri casi dove il contenuto compare senza un reload completo:

• Popup aggiunta al carrello: Il webshop mostra un popup con le recommendations Clerk.io dopo che il visitatore aggiunge un prodotto. Clerk.js rileva il nuovo contenuto non appena il popup viene creato.
• Sezione lazy-loaded: Il webshop aggiunge un blocco Clerk.io in fondo alla pagina quando il visitatore scrolla. Clerk.js lo intercetta quando appare.
• Single-page app: Una app React o Vue aggiunge contenuti Clerk.io durante la navigazione delle view. Clerk.js rileva i nuovi contenuti senza attendere un reload.

L’osservazione DOM si applica anche a blocchi contenuto, form di iscrizione email e live search.

Abilita l’osservazione #

Puoi abilitare l’osservazione DOM in uno di questi modi:

• Backend: In my.clerk.io, apri lo Store e vai su Settings > Features. Abilita SPA Auto Detect Changes.
• Codice: Aggiungi observe_dom: true alla tua configurazione Clerk.js come mostrato qui sotto.

Le due opzioni abilitano la stessa funzione. È sufficiente sceglierne una.

Clerk('config', {
  key: 'INSERT_PUBLIC_API_KEY',
  observe_dom: true
});

Mantieni la tua API key pubblica e qualsiasi altro parametro già presente in configurazione.

Dovrai comunque aggiungere il relativo snippet Clerk.io e configurare Element e Design. Abilitare l’osservazione aiuta Clerk.js a rilevare contenuti caricati dopo; non aggiunge placements di recommendation al tuo webshop.

Per rendering manuale e selettori custom, vedi Rendering personalizzato.

Utilizzo risorse #

Clerk.js raggruppa i rapidi cambiamenti della pagina in un unico passaggio e limita i controlli completi a uno ogni 500 ms. L’osservatore non consuma risorse quando la pagina è inattiva e non introduce ulteriori chiamate API o traffico di rete.

L’impostazione è opzionale. I negozi che non la abilitano mantengono il comportamento predefinito.

Rendering personalizzato #

Questa modalità è usata principalmente con Single Page App (SPA), Progressive Web App (PWA) o altre applicazioni che non utilizzano caricamenti tradizionali delle pagine.

Clerk.js renderizza ogni elemento con la classe clerk, ma è possibile usare altre classi come selettori custom.

Per default, si richiede di eseguire Clerk("content", "SELECTOR") per renderizzare ogni volta che il contenuto deve essere mostrato.

Aggiungendo auto_init_custom_selectors: true alla configurazione, Clerk.js inizializza automaticamente tutti i selettori custom ogni volta che il DOM cambia, a condizione che siano già stati renderizzati una volta con Clerk("content", "SELECTOR").

Questo comportamento continua fino a un refresh completo della pagina.

Debugging #

Clerk.js include una modalità debug che scrive informazioni diagnostiche nella console del browser. La configurazione viene salvata in sessionStorage con la chiave __clerk_debug, mantenendo la modalità attiva tra le navigazioni nella stessa sessione.

Di default, la modalità debug è attiva con level 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') nella console del browser. Accetta diversi formati di argomento:

Clerk('debug');              // Abilita con le impostazioni predefinite
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
});

Config path

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

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

URL hash

La modalità debug può esser 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, la configurazione viene salvata anche in sessionStorage con la chiave __clerk_tmp_config.

Opzioni di configurazione #

Session Storage #

Quando la modalità debug è attiva, la configurazione viene salvata in sessionStorage con la chiave __clerk_debug. Questo garantisce che i settings persistano tra le pagine, senza influenzare altre tab o durare oltre la sessione.

Consent Management Platforms (CMP) come Cookiebot possono segnalare __clerk_debug come storage item che richiede documentazione. Si tratta di una chiave funzionale utilizzata solo per il debug da sviluppatori. Non contiene dati personali né informazioni di tracciamento.

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

UI Kit #

Clerk.js include una serie di strumenti UI per elementi chiave, utili per migliorare l’esperienza utente e risparmiare tempo di sviluppo per setup personalizzati.

Instant Search #

Una parte fondamentale dell’esperienza di ricerca e-commerce è ricevere risultati immediati durante la digitazione. Il nostro componente UI Instant Search semplifica e velocizza questo aspetto.

Qualsiasi contenuto Clerk.io può teoricamente diventare un Instant Search, ma funziona meglio come dropdown con risultati 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ù sull’ Instant Search UI tool qui.

Pagina Search #

Un punto chiave per una buona esperienza di ricerca è ottenere risultati di qualità. La nostra Search Page ti permette di creare una pagina completa con il miglior matching possibile 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ù sul Search Page UI tool qui.

Pagina Categoria #

Una pagina categoria ben strutturata è essenziale per ogni eCommerce di successo. La nostra Category Page consente di creare una pagina dedicata con i migliori risultati del caso.

<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ù sul Category Page UI tool qui.

Facets #

Clerk.js offre il supporto nativo alla navigazione dinamica per facet sia in search che su categoria. Qualsiasi attributo prodotto può essere usato come 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="View More"
  data-facets-searchbox-text="Search for "
  data-facets-design="133995">
</span>

Leggi di più sul Facets UI tool qui.

Exit Intent #

Il popup di exit intent si attiva quando il visitatore prova a lasciare il sito, spostando il mouse verso l’alto della finestra. Può proporre prodotti interessanti e convertire un visitatore in uscita in acquirente.

Qualsiasi blocco Element può essere attivato con l’evento exit intent aggiungendo l’attributo data-exit-intent="true" nello 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ù sull’ Exit Intent UI tool qui.

Popup #

La UI Kit include una semplice libreria popup per creare facilmente popup user-friendly con qualsiasi contenuto. Qualsiasi elemento HTML sul sito con 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 il popup
  my_popup.show(); 
  /* o */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // nascondi il popup
  my_popup.hide(); 
  /* o */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Leggi di più sul Popup UI tool qui.

Chat #

Clerk.js espone una interfaccia JavaScript per controllare il widget Chat e reagire agli eventi della conversazione. Questo è utile se vuoi avviare Chat dalla tua UI, passare dati di contesto all’AI su ciò che sta facendo il visitatore, o integrare eventi col frontend.

La documentazione completa dei metodi ed eventi è disponibile nella Chat JS docs.

Apertura Chat con un bottone personalizzato #

Se vuoi avviare Chat da un tuo bottone o elemento UI, invece che dal launcher di default, usa toggle:

<button onclick="Clerk('chat', 'toggle')">
  Serve aiuto?
</button>

Puoi anche usare open e close separatamente per gestire lo stato esplicitamente.

Mostrare Chat solo su pagine specifiche #

Per default, Chat è visibile su tutto il sito. Per mostrarla solo su certe pagine, disabilitala nel config globale e abilitala selettivamente:

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

// Sulle pagine dove vuoi mostrarla
Clerk('chat', 'enable');

Passare il contesto carrello e pagina all’AI #

Il metodo metadata invia contesto strutturato a Chat così l’AI può rispondere in maniera più rilevante. Chiamalo ogni volta che cambia il contesto del visitatore—navigazione, aggiunta al carrello, aggiornamento preferenze.

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

// Dopo che un 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
  }
});

Il payload è flessibile—aggiungi il contesto che ti è più utile per le conversazioni in corso.

Modificare il comportamento AI in base alle azioni del visitatore #

Il metodo prompt_message invia un’istruzione di sistema all’AI. Il cliente non la vede, ma modifica la risposta dell’AI nella conversazione attuale.

// Dopo aggiunta al carrello—suggerisci cross-sell
Clerk('chat', 'prompt_message', 'L’utente ha appena aggiunto un Lightsaber al carrello. Suggerisci prodotti complementari come accessori o protezioni.');

// Sulla pagina di checkout—focus sul completamento ordine
Clerk('chat', 'prompt_message', 'L’utente è sulla pagina di checkout. Aiutalo a concludere l’acquisto e rispondi a eventuali domande.');

Passaggio a operatore umano #

Quando serve assistenza umana, l’evento onSupport si attiva con un riassunto della conversazione. Usa questo per aprire la chat helpdesk e trasmettere il contesto: l’agente è subito aggiornato senza far ripetere il visitatore.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onSupport: (e) => {
      // e.summary contiene il riassunto testo della conversazione
      const summary = e.summary || 'Nessun riassunto disponibile.';

      // Esempio: apri Intercom con contesto pre-populato
      if (window.Intercom) {
        Intercom('showNewMessage', 'Continuazione da AI Chat:\n\n' + summary);
      }

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

      // Facoltativo: nascondi Clerk Chat dopo il passaggio all’operatore
      Clerk('chat', 'disable');
    }
  }
});

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

Reagire agli eventi Chat #

Usa gli hook per integrare il comportamento di Chat col frontend — ad esempio loggare messaggi, sincronizzare stato, o passare il controllo all’helpdesk.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onMessage: (e) => {
      // Ogni messaggio — role può essere 'user', 'ai' o 'results'
      console.log(e.message.role, e.message.text);
    },
    onOpen: (e) => {
      // Quando la finestra viene aperta/chiusa
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Quando il visitatore richiede l’operatore umano
      // e contiene il riassunto della conversazione
      openLiveChatWithSummary(e);
    }
  }
});

Puoi registrare hook eventi anche dinamicamente dopo la config iniziale:

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

Leggi di più nelle Chat JS docs.

Escludere prodotti #

Clerk.js offre due modalità diverse, secondo che tu voglia escludere specifici ID o evitare duplicati tra slider differenti.

Escludere ID specifici #

Basta aggiungere l’attributo data-exclude nello snippet. Il valore deve essere una lista degli ID prodotto da non mostrare, ad esempio quelli nel carrello del cliente, o prodotti che non deve vedere.

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

Evitare duplicati #

Aggiungi data-exclude-from nello snippet Clerk dove vuoi escludere i duplicati. Il valore deve essere un selettore CSS per gli altri snippet da cui vuoi evitare duplicati.

Nell’esempio sotto, .clerk-2 esclude prodotti presenti in .clerk-1, e .clerk-3 esclude prodotti di .clerk-1 e .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 ti può servire reagire o modificare i risultati di Clerk prima che vengano renderizzati. Qui Events è utile.

Events permette di impostare listener che eseguono codice in momenti specifici, prima, durante o dopo che Clerk.js mostra i risultati.

Un esempio comune: caricare prezzi personalizzati per un cliente B2B loggato. Un evento può scattare subito dopo il rendering dell’API, permettendo di recuperare prezzi custom per il cliente 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 Events qui.

SEO e Prestazioni #

Clerk.js alimenta esperienze di acquisto personalizzate senza rallentare il sito o penalizzare la SEO. Utilizzando rendering lato client e caricamento ottimizzato, bilancia velocità, prestazioni e visibilità sui motori di ricerca.

SEO e velocità #

È un malinteso pensare che funzionalità JavaScript come Clerk.js danneggino le prestazioni o la SEO. Gli strumenti automatici spesso trascurano ottimizzazioni quali caching, caricamento parallelo e gestione lato server.

Vantaggi dell’integrazione di Clerk.js #

• Lo script Clerk.js (≈ 37 - 38 KB) viene caricato in modo asincrono, consentendo al tuo sito di essere visualizzato mentre Clerk si inizializza.
• Gli elementi Clerk sono renderizzati lato client, il che significa che il tuo HTML di base rimane memorizzabile in cache, e i componenti dinamici vengono inseriti solo dopo il caricamento.
• Questo permette un caching efficiente lato server e un caricamento non bloccante degli asset di Clerk.js.

Impatto sulle prestazioni #

• La natura leggera e asincrona di Clerk.js di solito comporta un impatto minimo sui tempi di caricamento delle pagine.
• Nella pratica, la perdita di prestazioni deriva spesso dalle immagini aggiuntive mostrate nelle recommendations, non dallo script stesso. Per minimizzare l’impatto:
  • Utilizza formati ad alta efficienza e dimensioni adeguate come WebP.
  • Ridimensiona le immagini in base alle dimensioni di visualizzazione (es. 400×400 px → 420×420 px max).
• Per evitare spostamenti di layout (CLS), riserva spazio per il contenuto inserito da Clerk.

Esempio:

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

Considerazioni SEO #

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

Collegamenti e crawlabilità #

• Clerk.js inserisce i link di recommendations dinamicamente lato client.
• Questi link possono migliorare il collegamento interno collegando pagine correlate, se i motori di ricerca li visualizzano e li seguono correttamente.
• Poiché sono inseriti tramite JavaScript, è necessario verificare come i crawler dei motori di ricerca li visualizzano e li interpretano.
• I link correttamente scansionati possono migliorare la crawlabilità e consentire ai motori di ricerca di scoprire e indicizzare più pagine.

Distribuzione del PageRank #

• Quando i motori di ricerca possono scansionarli, i link di Clerk.js possono aiutare a distribuire l’equità dei link (PageRank) tra le pagine chiave.
• Questo supporta una maggiore visibilità e un ranking migliore delle pagine prodotto e categoria.

Benefici osservati #

• Una corretta integrazione di Clerk.js può correlarsi a strutture di collegamento interno più forti, il che può migliorare la visibilità nei risultati di ricerca.
• Le dashboard di Clerk.io forniscono analytics sull’influenza degli ordini, l’aumento delle conversioni e il contributo ai ricavi da Search, Recommendations, Email e Audience.

Best practice consigliate #

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