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:

• È robusto, poiché viene caricato in modo asincrono. Questo significa che il resto della pagina non dipenderà da una risposta API prima di essere caricato.
• È spesso più veloce, in quanto il tuo server può iniziare a renderizzare la pagina in parallelo mentre Clerk.js effettua chiamate e visualizza i risultati.
• Il tracciamento dei visitatori e dei clic viene gestito automaticamente per tutti i risultati mostrati da Clerk. Non sono necessari cookie, in quanto viene generato un valore hash dell’indirizzo IP e dell’useragent del visitatore, combinato con un sale univoco del negozio 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 chiave API così da sapere già per quale Store sta effettuando chiamate API.

Snippet #

Quando la pagina viene caricata, Clerk.js la scansiona in cerca di snippet con la classe “clerk”.

Usa 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 viene gestita dal Design, anch’esso referenziato dallo snippet.

Clerk.js usa i design Liquid per renderizzare HTML con i dati restituiti dall’API. Questi vengono formattati come script, referenziati tramite il loro ID in data-template nello 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>Risultati per {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Compra 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 il 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 tramite codice Liquid HTML in modo user-friendly da my.clerk.io.

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

Injection #

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

Leggi di più su Injection qui.

Configurazione #

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

ID Visitatore #

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

Se gli utenti acconsentono ai cookie, Clerk.js può essere configurato per piazzare un cookie persistente con l’ID visitatore, consentendo il tracciamento nel tempo.

Se preferisci gestire manualmente le sessioni, puoi configurare il parametro visitor che Clerk usa 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
});

Page Context #

Configura Clerk.js con il contesto della pagina che il visitatore sta visualizzando. Serve per arricchire i dati di tracciamento 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 o null
  category: null, // Imposta l'ID categoria sulle pagine categoria, es. 67 o null
  page: null      // Imposta l'ID o il tipo pagina su altre pagine, es. 'homepage' o null
});

Il contesto può anche fornire gli ID usati dai blocchi recommendation. Vedi Element context settings per come usarlo con l’Injection.

Lingua #

Configura Clerk.js con la lingua scritta del sito. Serve affinché Clerk.io gestisca correttamente la grammatica in Search e per recuperare le traduzioni giuste quando usi feed multi-lingua.

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

I valori accettati sono elencati sotto Supported languages.

Sostituisci i valori segnaposto con la logica della tua piattaforma per ottenere 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. Impostalo su null sulle pagine che non sono prodotto.
• category: L’ID della categoria visualizzata nelle pagine categoria. Impostalo su null sulle altre pagine.
• page: Un identificatore o stringa di tipo pagina sulle altre pagine come homepage, carrello, checkout. Impostalo su null se non applicabile.

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

Funzioni Design #

Clerk.js supporta Formatter e Globals, che possono essere usati per creare funzionalità javascript personalizzate all’interno dei tuoi design.

Formatter #

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

Globals #

Servono invece a usare dati del frontend che vuoi rendere accessibili nei design. Può essere, ad esempio, l’importo rimanente per ottenere la spedizione gratuita, il nome di un cliente loggato, un simbolo valuta o un tasso di conversione.

Di seguito un esempio di configurazione di formatter e globals.

Config #

Clerk('config', {
  formatters: {
    uppercase: function(string) {
        return string.toUpperCase();
    }
  },
  globals: {
    currency_symbol: '$'
  }
});

Design #

<div class="name">{{ product.name | uppercase }}</div>
<div class="price">{{ currency_symbol }}{{ product.price }}</div>

Output #

<div class="name">GREEN LIGHT SABER</div>
<div class="price">$1999.99</div>

Email Tracking #

Clerk.js può raccogliere automaticamente le email nella sessione del cliente per personalizzare le raccomandazioni email anche se non ha ancora completato un ordine.

Abilita collect_email nella config di Clerk.js:

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

Con questa opzione abilitata, Clerk.js monitorerà i campi email e invierà in automatico log/email quando un visitatore inserisce un indirizzo email.

Se vuoi 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 dispone di account cliente, chiama log/email ogni volta che un’email conosciuta è disponibile in sessione — sia quando il cliente effettua il login sia quando ritorna già loggato.

L’approccio più semplice è controllare a ogni caricamento pagina se c’è un’email disponibile e, in tal caso, effettuare la chiamata. Per evitare chiamate API superflue, salva un flag nella session del browser in modo che venga richiamata 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’indirizzo email reale dalla tua piattaforma. Renderizza questo script solo quando un’email è effettivamente disponibile — saltalo completamente per gli ospiti.

Senza questa chiamata, Clerk.io può associare la sessione di un visitatore a un indirizzo email solo al completamento dell’acquisto. Loggare la mail appena disponibile permette che il legame avvenga subito, requisito per innescare email automatiche basate sul comportamento di navigazione, mostrare raccomandazioni personalizzate all’interno delle email e applicare campagne di Merchandising rivolte a segmenti Audience specifici.

Come funziona l’associazione #

Quando viene loggata una email, Clerk invia sia l’ID visitatore sia l’indirizzo email all’API affinché possano essere collegati.

Questo consente a Clerk di identificare cosa ha fatto quel visitatore nella cronologia sessione (prodotti visualizzati, clic, ricerche) e associare tali comportamenti all’indirizzo email.

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

Context Reloads #

I context reloads mantengono le raccomandazioni rilevanti mentre un cliente naviga su una single-page app o un headless storefront senza un caricamento pagina completo. Ad esempio, un blocco “Popolari in questa categoria” può aggiornarsi quando il cliente passa a un’altra categoria.

Questa opzione è abilitata di default per i blocchi i cui ID provengono dal contesto di Clerk.js (id_source: 'context'). Quando un valore di contesto cambia, Clerk.js ri-renderizza i blocchi già inizializzati che usano quella chiave con il nuovo valore.

Aggiorna contesto #

Chiama il setter pubblico del contesto ogni volta che cambia il valore rilevante. Ad esempio, dopo essere passati alla categoria 276:

Clerk('context', 'category', '276');

Sostituisci 276 con l’ID categoria del tuo store. Il contesto può essere impostato prima o dopo che un blocco è stato inizializzato. Impostare lo stesso valore di nuovo non fa nulla e non innesca un altro reload.

Le chiavi osservate sono:

Observer Comparison #

I context reload funzionano anche con l’osservazione DOM disattivata. Aggiornano i blocchi già presenti in pagina quando cambia un valore, senza richiedere la modifica dell’HTML della pagina.

L’osservazione DOM rileva markup aggiunto così Clerk.js può inizializzare blocchi aggiunti successivamente e ritentare injection i cui target sono comparsi. È abilitata separatamente. I context reload non usano MutationObserver, timer o listener DOM.

Context Event #

Usa l’evento context per reagire ai cambiamenti dal tuo frontend. Si attiva per ogni effettivo cambio di contesto, anche quando i reload automatici sono disabilitati. L’evento appartiene al contesto e non al singolo blocco.

Clerk('on', 'context', ({ key, value, previous, context }) => {
  // Aggiorna la tua UI qui se serve.
});

Disabilita i reload #

Se il tuo store gestisce questi aggiornamenti UI autonomamente, disabilita i reload automatici con:

Clerk('config', 'context_watch', false);

L’evento context rimane disponibile anche coi reload automatici disattivati.

Navigazione #

Nelle single-page app, popstate e hashchange eseguono il passaggio condiviso di content-and-injection. I target di injection URL possono essere creati quando cambiano le loro condizioni e i blocchi derivati dal contesto vengono ricaricati quando cambiano i valori di riferimento.

Aggiorna il contesto Clerk.js mentre il visitatore naviga, in modo che i valori riflettano la view in corso. Vedi la single-page app guide per l’inizializzazione e il rendering manuale.

Limiti #

I blocchi i cui ID provengono da elementi pagina, e i popup, non vengono ricaricati dai cambiamenti di contesto.

Durante l’injection, un blocco che manca di un valore di contesto richiesto viene saltato fino al prossimo passaggio di injection. Fanno eccezione le email: i blocchi email possono essere creati senza una email e popolati quando diventa disponibile.

L’osservazione DOM può scatenare il passaggio di injection che crea un blocco saltato. Questo fallback è distinto dal ricaricare un blocco già renderizzato.

Ogni chiave modificata genera una richiesta API aggiuntiva. Evita di aggiornare il contesto in loop stretto o a ogni evento di routing salvo che i cambi siano intenzionali.

DOM Observation #

Abilita l’osservazione DOM quando il tuo webshop aggiunge contenuto Clerk.io dopo il caricamento pagina. Clerk.js monitora i cambi nella struttura della pagina, chiamata DOM, così da rilevare i contenuti man mano che compaiono.

Puoi abilitare lo stesso comportamento tramite SPA Auto Detect Changes su my.clerk.io o aggiungendo observe_dom: true alla configurazione Clerk.js.

Esempio Side Cart #

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

Con l’approccio basato su timer, Clerk.js controlla eventuali cambi una volta al secondo. Lo snippet recommendation può attendere fino al prossimo controllo prima che Clerk.js lo rilevi.

Con observe_dom attivo, aggiungere il side cart scatena subito un controllo. Clerk.js rileva prima lo snippet e comincia a renderizzare le raccomandazioni, riducendo l’attesa dopo la comparsa del carrello.

Altri esempi #

Lo stesso comportamento è utile in tutti i casi dove compaiono contenuti senza un vero refresh pagina:

• Popup add-to-cart: Il webshop crea un popup contenente raccomandazioni Clerk.io dopo che il cliente ha aggiunto un prodotto. Clerk.js rileva il contenuto aggiunto alla creazione del popup.
• Sezione lazy-loaded: Il webshop aggiunge un blocco Clerk.io più in basso nella pagina man mano che il visitatore scrolla. Clerk.js lo rileva quando viene aggiunto.
• Single-page app: Un’app React o Vue aggiunge contenuti Clerk.io quando il visitatore naviga verso una nuova view. Clerk.js rileva il nuovo contenuto senza attendere un nuovo caricamento pagina.

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

Abilitare l’osservazione #

Scegli uno dei due modi per abilitare la DOM observation:

• Backend: Su my.clerk.io, apri il tuo Store e vai su Settings > Features. Abilita SPA Auto Detect Changes.
• Codice: Aggiungi observe_dom: true alla tua configurazione Clerk.js già esistente, come sotto.

Entrambe le opzioni attivano la stessa feature, quindi ne basta una.

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

Mantieni la chiave API pubblica e tutte le altre opzioni che già usi.

Serve comunque aggiungere lo snippet Clerk.io appropriato e configurare il relativo Element e Design. L’osservazione abilita la rilevazione dei contenuti dinamici; non aggiunge di per sé posizionamenti raccomandazione al tuo sito.

Per rendering manuale e selettori personalizzati, vedi Custom Rendering.

Uso delle risorse #

Clerk.js raggruppa piccoli burst di cambiamenti in un unico passaggio e limita i passaggi completi a uno ogni 500 ms. L’observer non lavora quando la pagina è inattiva e non genera chiamate API o traffico di rete aggiuntivo.

Questa impostazione è opt-in. Gli store che non la abilitano mantengono il comportamento precedente.

Custom Rendering #

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

Clerk.js renderizza qualunque elemento con la classe clerk, ma si possono usare altre classi come selettori personalizzati.

Di default, serve eseguire Clerk("content", "SELECTOR") ogni volta che va mostrato del contenuto.

Aggiungendo auto_init_custom_selectors: true nella config, Clerk.js inizializza in automatico ogni selettore personalizzato mentre il DOM cambia, purché sia già stato renderizzato almeno una volta con Clerk("content", "SELECTOR").

Questo comportamento prosegue finché non c’è un full refresh della pagina.

Debugging #

Clerk.js ha una modalità debug integrata che scrive informazioni di diagnostica sulla console del browser. Salva le sue impostazioni su sessionStorage con la chiave __clerk_debug, così la modalità rimane attiva tra i cambi di pagina nella stessa sessione.

Di default, il debug è attivo con level a warn e collect su true.

Metodi di attivazione #

Tre modi per attivare la modalità debug.

Scorciatoia console

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

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

Config path

La modalità debug si può configurare anche tramite la chiamata config standard:

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

URL hash

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

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

Se attivata via URL hash, la configurazione viene conservata in sessionStorage sotto la chiave __clerk_tmp_config.

Opzioni Config #

Session Storage #

Quando la modalità debug è attiva, la configurazione viene salvata in sessionStorage con la chiave __clerk_debug. Così le impostazioni persistono durante la navigazione, senza toccare altri tab o persistere oltre la sessione.

I Consent Management Platform (CMP) come Cookiebot possono segnalare __clerk_debug tra gli storage che richiedono documentazione. Si tratta di una chiave funzionale, usata solo per debugging sviluppatori. Non contiene dati personali né tracciamento.

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

UI Kit #

Clerk.js include una serie di strumenti UI per elementi chiave pensati per ottimizzare la user experience. Spesso fanno risparmiare tempo di sviluppo per le configurazioni personalizzate.

Instant Search #

Uno degli aspetti chiave in un’esperienza di ricerca e-commerce di qualità è ricevere risultati immediati non appena si inizia a digitare. Il componente UI Instant Search rende questa esperienza semplice e veloce da implementare.

Qualunque contenuto Clerk.io può essere reso un componente Instant Search, ma è consigliato come dropdown che mostra risultati.

<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 }}">Compra ora</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Leggi di più sullo strumento UI Instant Search qui.

Search Page #

Un aspetto cruciale in una buona esperienza di ricerca e-commerce è ricevere risultati adeguati. Il Search Page permette di creare velocemente una pagina dedicata che mostra le migliori corrispondenze per una qualunque 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 }}">Compra ora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostra più risultati
    		</div>
    {% endif %}
  </div>
</span>

Leggi di più sullo strumento UI Search Page qui.

Category Page #

Una pagina categoria ben organizzata è fondamentale per un eCommerce di successo. Il Category Page consente una user experience veloce in cui mostrare i migliori risultati per qualunque 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 }}">Compra ora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostra più risultati
    		</div>
    {% endif %}
  </div>
</span>

Leggi di più sullo strumento UI Category Page qui.

Facets #

Clerk.js offre supporto integrato per la navigazione dinamica a faccette per ricerca e categorie. Qualunque attributo prodotto inviato 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="Vedi altri"
  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 ai tentativi di abbandono del sito rilevando il movimento del mouse vicino alla parte superiore della finestra browser. Mostra prodotti interessanti, trasformando magari un visitatore in procinto di andarsene in un cliente pagante.

Qualsiasi blocco Element può essere mostrato su intento di uscita 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ù sullo strumento UI Exit Intent qui.

Popup #

Lo UI Kit include una libreria di popup semplice per creare pop-up user-friendly con qualunque contenuto. Qualunque elemento HTML sul tuo 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');
  
  // 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 Chat e reagire agli eventi della conversazione. Utile se vuoi attivare la chat dalla tua UI, passare all’AI dati contestuali su ciò che il visitatore sta facendo, o agganciarti agli eventi della conversazione dal resto del frontend.

La reference completa di metodi ed eventi è disponibile nei Chat JS docs.

Aprire Chat da un pulsante personalizzato #

Se vuoi collegare Chat a un pulsante o elemento UI personalizzato invece del launcher standard, usa toggle:

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

Puoi anche usare open e close per controllare esplicitamente lo stato.

Mostrare Chat solo su pagine specifiche #

Di default, Chat è visibile su tutto il sito. Per mostrarlo solo su alcune pagine, disabilitalo nella config globale e abilitalo dove serve:

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

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

Passare dati del carrello e del contesto pagina all’AI #

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

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

// Quando un utente 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 — includi tutto ciò che è utile alle conversazioni di quella pagina.

Modificare il comportamento AI in base alle azioni del visitatore #

Il metodo prompt_message invia una istruzione di sistema all’AI. Il cliente non la vedrà mai, ma influenza le risposte dell’AI nella conversazione corrente.

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

// Sulla pagina di checkout — aiuta a completare l’acquisto
Clerk('chat', 'prompt_message', 'The user is on the checkout page. Help them complete their order and answer any last-minute questions.');

Passaggio a un operatore umano #

Quando un visitatore ha bisogno di supporto umano, l’evento onSupport si attiva includendo un riassunto della conversazione. Puoi usarlo per aprire la chat helpdesk e passare i dati contestuali all’operatore, così che sia già aggiornato — senza che il cliente debba ripetere tutto.

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

      // Esempio: apri Intercom con il contesto preinserito
      if (window.Intercom) {
        Intercom('showNewMessage', 'Continuando dalla 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 }
        ]);
      }

      // Opzionalmente nascondi Clerk Chat dopo il passaggio
      Clerk('chat', 'disable');
    }
  }
});

L’evento onSupport si attiva solo quando Contact Support è configurato tra le opzioni della Chat e il visitatore richiede esplicitamente un umano.

Reagire agli eventi Chat #

Usa i hook di evento per integrare il comportamento Chat con il resto del frontend — per esempio loggare messaggi, sincronizzare lo stato o passare la chat a un operatore.

Puoi anche registrare hook di evento dinamicamente dopo la configurazione iniziale:

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

Leggi di più nella Chat JS docs.

Esclusione Prodotti #

Clerk.js offre due modi diversi per escludere prodotti, a seconda che si desideri escludere ID specifici o evitare la visualizzazione di prodotti duplicati tra diversi slider.

Esclusione di ID Specifici #

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

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

Evitare i Duplicati #

Questo si ottiene aggiungendo l’attributo data-exclude-from al Clerk Block ovunque tu voglia rimuovere i duplicati. Il valore dell’attributo dovrebbe essere un selettore CSS per l’altro/i snippet da cui evitare duplicati.

Nell’esempio qui sotto, .clerk-2 esclude qualsiasi prodotto sia presente in .clerk-1 e .clerk-3 esclude tutti i prodotti presenti in .clerk-1 o .clerk-2.

<span class="clerk clerk-1"
  data-template="@clerk-banner-1">
</span>
 
<span class="clerk clerk-2"
  data-exclude-from=".clerk-1"
  data-template="@clerk-banner-2">
</span>
 
<span class="clerk clerk-3"
  data-exclude-from=".clerk-1,.clerk-2"
  data-template="@clerk-banner-3">
</span>

Eventi #

Quando si costruiscono configurazioni più personalizzate, spesso è necessario reagire o modificare i risultati di Clerk prima della loro visualizzazione. Questo è il caso in cui Eventi sono utili.

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

Un esempio comune è caricare prezzi personalizzati per un cliente autenticato in un setup B2B. Un evento può essere eseguito subito dopo che l’API di Clerk ha terminato il rendering, consentendo di recuperare i prezzi personalizzati 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;
    }
})

Per saperne di più sugli Eventi qui.

SEO e Performance #

Clerk.js permette esperienze di shopping personalizzate senza rallentare il sito o danneggiare la SEO. Usando rendering client-side e caricamento ottimizzato, bilancia velocità, performance e visibilità nei motori di ricerca.

SEO e Velocità #

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

Vantaggi dell’integrazione Clerk.js #

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

Impatto sulle Performance #

• La natura leggera e asincrona di Clerk.js generalmente comporta un impatto minimo sui tempi di caricamento della pagina.
• Un eventuale peggioramento reale delle performance deriva spesso dalle immagini aggiuntive mostrate nelle recommendations, non dallo script in sé. Per minimizzare l’impatto:
  • Usa formati efficienti e di dimensioni adeguate, come WebP.
  • Ridimensiona le immagini per adattarle alle dimensioni di visualizzazione (es. 400×400 px → max 420×420 px).
• Per evitare spostamenti di layout (CLS), riserva spazio per i contenuti Clerk inseriti.

Esempio:

.clerk-slider-wrapper {
  min-height: 300px; /* regola se necessario */
  width: 100%;
}

Considerazioni SEO #

Comprendere come Clerk.js si relaziona con i motori di ricerca aiuta a garantire che l’implementazione favorisca sia l’esperienza utente che la visibilità.

Collegamento e Crawlabilità #

• Clerk.js inserisce i link alle recommendations dinamicamente lato client.
• Questi link possono migliorare il collegamento interno mettendo in relazione pagine affini, se i motori di ricerca li renderizzano e li seguono correttamente.
• Poiché sono iniettati via JavaScript, è necessario verificare come i crawler interpretano e gestiscono questi link.
• Link opportunamente scoperti possono migliorare la crawlabilità e consentire ai motori di ricerca di scoprire e indicizzare più pagine.

Distribuzione PageRank #

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

Vantaggi Osservati #

• Una corretta integrazione Clerk.js può essere correlata a una struttura di linking interno più solida, che può migliorare la visibilità nei risultati di ricerca.
• Le dashboard di Clerk.io offrono analytics sull’influenza degli ordini, incremento delle conversioni e contributo al fatturato delle funzioni 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 e previeni 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.