Qualsiasi (webshop)

Clerk.js

Integra Clerk.io in qualsiasi frontend con una libreria JS leggera.

Panoramica #

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

Ci sono tre vantaggi nell’usare Clerk.js:

È robusto, poiché viene caricato in modo asincrono. Questo significa che il resto della pagina non dipende da una risposta dell’API prima del caricamento.
È spesso più veloce, poiché il tuo server può iniziare a rendere la pagina in parallelo mentre Clerk.js effettua le chiamate e rende i risultati.
Il tracciamento di visitatori e click viene gestito automaticamente per qualsiasi risultato mostrato da Clerk. Questo non richiede cookie, poiché generiamo un valore hash dell’IP del visitatore e dello useragent, combinato con un sale unico che ruota ogni 30 giorni.

Clerk.js viene caricato 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, configurando Clerk.js con la API key in modo che sappia già per quale Store sta effettuando chiamate API.

Snippet #

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

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

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

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

Clerk.js utilizza i Liquid designs per rendere l’HTML con i dati restituiti dall’API. Questi sono formattati come script, richiamati dal 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 includendo 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 tramite il Design Editor o con Liquid HTML code in maniera user-friendly da my.clerk.io.

I tuoi snippet dovranno solo contenere la classe clerk, eventuali info specifiche di pagina come gli ID prodotti, 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 doverlo fare manualmente. Invece, devi solo 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 permette una varietà di configurazioni che ne modificano il funzionamento.

Visitor IDs #

Per impostazione predefinita, Clerk.js genera 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 visitatore, consentendo il tracciamento su periodi più lunghi.

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

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

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

// Disabling visitor tracking
Clerk('config', {
  visitor: null
});

Page Context #

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

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

Lingua #

Configura Clerk.js con la lingua del sito web. Questo serve a Clerk.io per gestire correttamente le regole grammaticali in Search e per recuperare le giuste traduzioni quando usi i multi-language feeds.

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

I valori accettati sono elencati in Supported languages.

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

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

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

Funzioni di Design #

Clerk.js supporta l’aggiunta di Formatters e Globals, che possono essere usati per creare funzionalità Javascript personalizzate per i tuoi design.

Formatters #

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

Globals #

Sono pensati per essere usati con dati frontend che vuoi accedere nei design. Esempi tipici sono l’importo residuo per ottenere la spedizione gratuita, il nome del cliente loggato, un simbolo di valuta o un tasso di conversione.

Sotto trovi un esempio di configurazione di formatters e globals.

Configurazione #

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 durante la sessione del cliente per personalizzare le raccomandazioni via email anche se non ha ancora effettuato 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 gli input delle email e invia automaticamente log/email quando un visitatore inserisce un indirizzo email.

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

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

Come avviene l’associazione #

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

Questo permette a Clerk di identificare cosa ha fatto quel visitatore nella cronologia della sessione (ad esempio prodotti visualizzati, click e ricerche) e di associare quel comportamento all’indirizzo email.

Grazie a questa associazione, gli stessi dati comportamentali possono essere usati sia per casi email (come invii email trigger e personalizzati) che per la personalizzazione onsite nelle raccomandazioni per clienti loggati.

Rendering Personalizzato #

Questa funzione è pensata soprattutto per Single Page App (SPA), Progressive Web App (PWA) e altre applicazioni senza caricamenti di pagina tradizionali.

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

Per impostazione predefinita, Clerk richiede di eseguire Clerk("content", "SELECTOR") per effettuare il rendering del contenuto ogni volta che deve essere mostrato.

Aggiungendo auto_init_custom_selectors: true alla config, Clerk.js inizializza automaticamente tutti i selettori custom quando il DOM si modifica, a patto che siano già stati renderizzati almeno una volta con Clerk("content", "SELECTOR").

Questo comportamento continua fino a un refresh completo della pagina.

Debugging #

Clerk.js dispone di una modalità debug integrata che registra informazioni diagnostiche nella console del browser. Mantiene la sua configurazione in sessionStorage sotto la chiave __clerk_debug, mantenendo la modalità debug attiva durante le varie navigazioni nella stessa sessione del browser.

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

Modalità di attivazione #

Ci sono tre modi per attivare la modalità debug.

Console shorthand

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

Clerk('debug');              // Abilita con valori predefiniti
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ò essere configurata anche tramite la classica chiamata config:

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

URL hash

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

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

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

Opzioni di Config #

Opzione	Descrizione	Tipo	Predefinito
`enable`	Abilita o disabilita i messaggi debug nella console.	`bool`	`true`
`level`	Imposta il livello di log. Valori accettati: `log`, `warn`, `error`.	`string`	`warn`
`collect`	Se `true`, i messaggi vengono archiviati nello storage del browser. Se `false`, viene usato uno storage temporaneo.	`bool`	`true`
`group`	Raggruppa messaggi correlati per una lettura più semplice.	`bool`	—
`collapsed`	Se `true`, i gruppi sono collassati di default. Vale solo se `group` è attivo.	`bool`	—
`clear`	Cancella tutti i messaggi log salvati.	`bool`	—

Session Storage #

Quando la modalità debug è attiva, la configurazione viene salvata in sessionStorage nella chiave __clerk_debug. Questo garantisce che le impostazioni debug persistano mentre l’utente naviga tra le pagine, senza influenzare altre schede o andare oltre la sessione.

Le Consent Management Platform (CMP) come Cookiebot possono segnalare __clerk_debug come storage da documentare. Si tratta di una chiave funzionale usata solo per debugging sviluppatori. Non contiene dati personali o informazioni di tracciamento.

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

UI Kit #

Clerk.js include una serie di strumenti UI per elementi chiave utilizzabili per migliorare l’esperienza utente. Questi spesso fanno risparmiare tempo di sviluppo per setup personalizzati.

Instant Search #

Un aspetto chiave di una grande esperienza di ricerca e-commerce è ottenere risultati immediatamente mentre inizi a digitare. Il nostro componente Instant Search rende questa esperienza veloce e semplice da implementare.

Qualsiasi contenuto Clerk.io può teoricamente essere trasformato in un componente Instant Search, ma funziona al meglio come 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>Prodotti corrispondenti a <i>{{ query }}</i></dt>
    
    {% for product in products %}
      <dd class="product clerk-instant-search-key-selectable">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Acquista ora</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Leggi di più sullo strumento UI Instant Search qui.

Search Page #

Un aspetto chiave di una grande esperienza di ricerca e-commerce è ottenere risultati di qualità. La nostra Search Page rende questa esperienza completa e facile da implementare.

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

<span 
  class="clerk"
  
  data-api="search/search"
  data-limit="40"
  data-labels='["Search Page"]'
  data-query="INSERT_QUERY_HERE"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">>
  
  <div class="product-search-result-list">
    <div>Prodotti corrispondenti a <i>{{ query }}</i></div>
    
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Acquista ora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostra altri risultati
    		</div>
    {% endif %}
  </div>
</span>

Leggi di più sullo strumento UI Search Page qui.

Category Page #

Una pagina categoria ben strutturata è fondamentale per il successo di un eCommerce. La nostra Category Page rende questa esperienza facile e veloce da implementare. Consente di creare una pagina intera con i migliori risultati per ogni categoria.

<span 
  class="clerk"
  
  data-api="recommendations/category/popular"
  data-limit="40"
  data-labels='["Category Page Grid"]'
  data-category="INSERT_CATEGORY_ID"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">
  
  <div class="product-category-result-list">
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Acquista ora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostra altri risultati
    		</div>
    {% endif %}
  </div>
</span>

Leggi di più sullo strumento UI Category Page qui.

Clerk.js offre il supporto nativo per la navigazione facettata dinamica sia per ricerca che categorie. Qualsiasi attributo prodotto inviato può essere utilizzato 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="Visualizza altro"
  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 quando un visitatore tenta di lasciare il sito spostando il mouse vicino alla parte superiore della finestra del browser. Si apre mostrando prodotti interessanti, potenzialmente convertendo un visitatore in uscita in un cliente.

Ogni blocco Element può essere attivato in risposta all’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.

La UI Kit include una semplice libreria popup per creare facilmente popup semplici ma user-friendly con qualsiasi contenuto. Ogni elemento HTML sul sito con la classe clerk-popup sarà 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 conversazionali. È utile quando vuoi attivare la chat dalla tua UI, inviare all’AI dati contestuali su cosa sta facendo il visitatore o agganciarti agli eventi della conversazione dal resto del frontend.

La documentazione completa dei metodi e degli eventi è disponibile nelle Chat JS docs.

Aprire Chat da un pulsante personalizzato #

Se vuoi attivare Chat da un tuo bottone o elemento UI invece dell’avvio predefinito, usa toggle:

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

Puoi usare anche open e close in modo indipendente per controllare lo stato in maniera esplicita.

Mostrare Chat solo in specifiche pagine #

Per impostazione predefinita, Chat è visibile su tutto il sito. Per mostrarla solo su alcune pagine, disabilitala nella config globale e abilitala selettivamente:

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

// Poi nelle pagine dove la vuoi attiva
Clerk('chat', 'enable');

Passare contesto carrello e pagina all’AI #

Il metodo metadata invia contesto strutturato a Chat così l’AI può dare risposte più rilevanti. Richiamalo ogni volta che il contesto del visitatore cambia — navigazione di pagina, aggiunta al carrello, aggiornamento preferenze.

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

// Dopo che il visitatore aggiunge un prodotto in 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 tutto il contesto rilevante alla conversazione in corso.

Modificare il comportamento AI in base all’attività del visitatore #

Il metodo prompt_message invia un’istruzione a livello di sistema all’AI. Il cliente non la vede, ma essa modifica il modo in cui l’AI risponde nella conversazione corrente.

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

// Nella pagina di checkout — aiutare a completare l’ordine
Clerk('chat', 'prompt_message', 'L’utente è nella pagina di checkout. Aiutalo a completare l’ordine e rispondi a eventuali domande finali.');

Passaggio a operatore umano #

Quando un visitatore ha bisogno di supporto umano, l’evento onSupport viene attivato con un riepilogo della conversazione. Usa questo evento per aprire il tuo helpdesk chat e passare il contesto all’agente — così il visitatore non dovrà ripetere tutto.

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

      // Esempio: apri Intercom con contesto precompilato
      if (window.Intercom) {
        Intercom('showNewMessage', 'Continua dalla Chat AI:\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 disabilita Clerk Chat dopo il passaggio
      Clerk('chat', 'disable');
    }
  }
});

L’evento onSupport si attiva solo quando Contact Support è configurato nelle impostazioni Chat e il visitatore ne fa esplicita richiesta.

Reagire agli eventi Chat #

Puoi usare i ganci evento per integrare Chat con il resto del frontend — ad esempio, registrando messaggi, sincronizzando lo stato o passando la conversazione ad un operatore umano.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onMessage: (e) => {
      // Si attiva su ogni messaggio — role è 'user', 'ai' o 'results'
      console.log(e.message.role, e.message.text);
    },
    onOpen: (e) => {
      // Si attiva quando la finestra Chat viene aperta o chiusa
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Si attiva quando il visitatore richiede un operatore umano
      // e contiene il riepilogo della conversazione
      openLiveChatWithSummary(e);
    }
  }
});

Puoi anche registrare gli hooks degli eventi dinamicamente dopo la config 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 modalità per escludere prodotti, in base al fatto che tu voglia escludere determinati ID o evitare duplicazioni tra diversi slider.

Esclusione di 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 quelli nel carrello cliente o una lista di prodotti non visualizzabili.

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

Evitare duplicati #

Questo viene fatto aggiungendo l’attributo data-exclude-from sul Clerk Block ovunque tu voglia rimuovere il duplicato. Il valore dell’attributo deve essere un CSS selector relativi agli altri snippet da cui evitare i duplicati.

Nell’esempio sotto, .clerk-2 esclude qualsiasi prodotto che sia in .clerk-1, e .clerk-3 esclude quelli che sono sia in .clerk-1 che in .clerk-2.

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

Eventi #

Quando realizzi setup più personalizzati spesso hai bisogno di reagire o modificare i risultati Clerk prima di renderizzarli. Qui tornano utili gli Events.

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

Un esempio comune è il caricamento di prezzi personalizzati per un cliente loggato in un setup B2B. Un evento può partire subito dopo che l’API di Clerk ha reso il risultato, permettendoti di recuperare prezzi custom per un cliente e aggiungerli agli elementi dei prodotti:

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 Performance #

Clerk.js abilita esperienze di shopping personalizzate senza rallentare il sito o danneggiare la SEO. Grazie al rendering lato client e al caricamento ottimizzato, bilancia velocità, performance e visibilità nei motori di ricerca.

SEO e Velocità #

C’è il mito che funzionalità JS come Clerk.js danneggino performance o SEO. Gli strumenti automatici spesso ignorano 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, permettendo al sito di caricarsi mentre Clerk si inizializza.
Gli elementi Clerk sono renderizzati lato client, quindi l’HTML base resta cacheabile e le componenti dinamiche sono iniettate solo dopo il caricamento.
Questo permette caching server-side efficiente e caricamento non bloccante delle risorse Clerk.js.

Impatto sulle performance #

La natura leggera e asincrona di Clerk.js comporta in genere impatto minimo sui tempi di caricamento.
In pratica, i rallentamenti derivano spesso dal caricamento di immagini supplementari mostrate nelle recommendations, non dallo script stesso. Per ridurre al minimo l’impatto:
- Usa formati ottimizzati come WebP dalle dimensioni corrette.
- Ridimensiona le immagini alle dimensioni di visualizzazione (es. 400×400 px → max 420×420 px).
Per evitare spostamenti di layout (CLS), riserva spazio per i contenuti Clerk iniettati.

Esempio:

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

Considerazioni SEO #

Comprendere come Clerk.js interagisce con i motori di ricerca aiuta a garantire una corretta usabilità e visibilità.

Collegamenti interni e crawlabilità #

Clerk.js inietta dinamicamente i link delle raccomandazioni lato client.
Questi link possono migliorare il linking interno collegando pagine correlate, purché i motori di ricerca li rendano e seguano correttamente.
Poiché sono iniettati tramite JavaScript, verifica come i crawler li renderizzano e interpretano.
Se i link sono correttamente scansionati, è possibile migliorare la crawlabilità e consentire ai motori di scoprire e indicizzare più pagine.

Distribuzione del PageRank #

Se i motori possono scansionarli, i link di Clerk.js possono aiutare a distribuire l’equity dei link (PageRank) tra le pagine chiave.
Questo contribuisce a una migliore visibilità e ranking delle pagine prodotto e categoria.

Benefici osservati #

Una corretta integrazione di Clerk.js può portare a strutture di linking interno più forti, migliorando la visibilità nei risultati di ricerca.
Le dashboard Clerk.io forniscono analytics su influenza degli ordini, incrementi di conversione e contributi di ricavo da Search, Recommendations, Email e Audience.

Best Practice raccomandate #

Ottimizza le immagini (formato WebP, risoluzione corretta).
Riserva spazio layout per elementi dinamici per prevenire spostamenti.
Monitora i dati reali invece dei soli punteggi degli strumenti automatici. Usa le dashboard Clerk per misurare l’impatto sui vari canali.

Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.

Clerk.js

Panoramica #

Snippet #

Injection #

Configurazione #

Visitor IDs #

Page Context #

Lingua #

Funzioni di Design #

Formatters #

Globals #

Configurazione #

Design #

Output #

Email Tracking #

Come avviene l’associazione #

Rendering Personalizzato #

Debugging #

Modalità di attivazione #

Opzioni di Config #

Session Storage #

UI Kit #

Instant Search #

Search Page #

Category Page #

Facets #

Exit Intent #

Popup #

Chat #

Aprire Chat da un pulsante personalizzato #

Mostrare Chat solo in specifiche pagine #

Passare contesto carrello e pagina all’AI #

Modificare il comportamento AI in base all’attività del visitatore #

Passaggio a operatore umano #

Reagire agli eventi Chat #

Esclusione Prodotti #

Esclusione di ID specifici #

Evitare duplicati #

Eventi #

SEO e Performance #

SEO e Velocità #

Vantaggi dell’Integrazione Clerk.js #

Impatto sulle performance #

Considerazioni SEO #

Collegamenti interni e crawlabilità #

Distribuzione del PageRank #

Benefici osservati #

Best Practice raccomandate #