Clerk.js

Panoramica #
Clerk.js è una libreria JavaScript che semplifica l’integrazione della nostra API con il frontend. Con solo 37,7kb, è una soluzione estremamente leggera.
Ci sono tre vantaggi nell’utilizzare Clerk.js:
- È robusta, poiché viene caricata in modo asincrono. Questo significa che il resto della pagina non dipende da una risposta dell’API prima di caricarsi.
- È spesso più veloce, poiché il tuo server può iniziare a renderizzare la pagina in parallelo mentre Clerk.js effettua le chiamate e visualizza i risultati.
- Il tracciamento dei visitatori e dei click viene gestito automaticamente per qualsiasi risultato visualizzato da Clerk. Non sono necessari cookie, poiché viene generato un valore hash dell’IP e dello useragent del visitatore, combinato con un sale unico per lo store che ruota ogni 30 giorni.
Clerk.js si carica con uno script di inizializzazione aggiunto nell’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 l’API key in modo che sappia già per quale Store sta effettuando le chiamate API.
Snippet #
Quando la pagina viene caricata, Clerk.js la scansiona alla ricerca di qualsiasi snippet con la classe “clerk”.
Utilizza quindi gli attributi dallo snippet per costruire una chiamata API ottenendo 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 è gestita dal Design, che è anch’esso richiamato dallo snippet.
Clerk.js utilizza
Design Liquid per renderizzare l’HTML con i dati restituiti dall’API. Questi sono formattati come script e richiamati dal loro ID tramite 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>Risultato della ricerca 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 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 codice HTML Liquid in modo user-friendly da my.clerk.io.
I tuoi snippet dovranno solo contenere la classe clerk, eventuali informazioni specifiche della pagina come gli ID dei prodotti, e un riferimento all’ID di un blocco Element in data-template.
Iniezione #
L’iniezione è una funzione che consente di inserire snippet di contenuto nel tuo sito senza doverlo fare manualmente. Ti basta scegliere un selettore CSS 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 numerose configurazioni che ne modificano il funzionamento.
Per configurare Clerk.js in my.clerk.io, apri il tuo Store e vai su Developers > Clerk.js Config. Regola le impostazioni e clicca su Save.
Queste impostazioni si applicano automaticamente al caricamento di Clerk.js. Non sovrascrivono i valori già impostati nel tuo snippet di tracciamento o nella console del browser. Le modifiche possono richiedere fino a 10 minuti per essere applicate.
ID Visitatore #
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, permettendo un tracciamento a lungo termine.
Se preferisci gestire manualmente gli ID di sessione, puoi configurare il parametro visitor che Clerk usa nelle chiamate API. In alternativa, puoi disattivare completamente il tracciamento della sessione impostando visitor su null.
// Visitor ID persistente
Clerk('config', {
visitor: 'persistent'
});
// Visitor ID personalizzato
Clerk('config', {
visitor: 'ABC123'
});
// Disattivazione tracciamento visitatore
Clerk('config', {
visitor: null
});
Contesto Pagina #
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, segmentazione Audience e contesto Chat.
Clerk('context', {
product: null, // Imposta l’ID prodotto nelle pagine prodotto, es. 12345 o null
category: null, // Imposta l’ID categoria nelle pagine categoria, es. 67 o null
page: null // Imposta l’ID o tipo pagina nelle altre pagine, es. 'homepage' o null
});
Il contesto può anche fornire gli ID usati dai blocchi di raccomandazione. Vedi Impostazioni contesto Element per come usarlo con Injection.
Lingua #
Configura Clerk.js con la lingua scritta del sito. Questo permette a Clerk.io di gestire correttamente le regole grammaticali in Search, e di recuperare le traduzioni corrette quando usi feed multilingua.
Clerk('config', {
language: 'italian'
});
I valori accettati sono elencati sotto Lingue supportate.
Sostituisci i valori fittizi con la logica della tua piattaforma per ottenere dinamicamente gli ID. Ogni valore deve essere impostato in base al tipo di pagina visitata:
- product: ID del prodotto visualizzato nelle pagine prodotto. Impostare su
nullnelle pagine non di prodotto. - category: ID della categoria visualizzata nelle pagine categoria. Impostare su
nullnelle pagine non di categoria. - page: Identificativo o tipo pagina nelle altre pagine come homepage, carrello o checkout. Impostare su
nullse non applicabile.
Se la piattaforma non ha un ID specifico per un tipo di pagina, lascia il valore su null. Imposta solo i valori per i tipi pagina rilevanti.
Funzioni di Design #
Clerk.js supporta l’aggiunta di Formatter e Global, che possono essere utilizzati per creare funzionalità javascript personalizzate nei tuoi Design scopes.
Formatter #
Vengono utilizzati per influenzare o modificare gli attributi. Ad esempio, potresti voler mostrare solo i primi 40 caratteri di una descrizione, o calcolare una percentuale di sconto specifica in base al tipo di cliente loggato.
Global #
Sono pensati per essere usati con dati frontend che vuoi rendere disponibili nei design. Ad esempio l’importo mancante per la spedizione gratuita, il nome di un cliente loggato, un simbolo di valuta oppure un tasso di conversione.
Di seguito un esempio di configurazione di formatter e global.
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>
Tracciamento Email #
Clerk.js può raccogliere automaticamente le email nella session del cliente per personalizzare le Email Recommendations anche se non hanno ancora effettuato un ordine.
Per attivare la raccolta email automatica in my.clerk.io, apri il tuo Store, vai su Developers > Clerk.js Config, abilita Collect Emails e clicca su Save.
In alternativa, abilita collect_email nella configurazione Clerk.js nel codice:
<script type="text/javascript">
Clerk('config', {
key: 'insert_api_key',
collect_email: true
});
</script>
Con questa funzione attiva, Clerk.js monitora gli input email e invia automaticamente log/email quando un visitatore inserisce un indirizzo email.
Questo identifica il visitatore; non lo iscrive al marketing. Vedi Email setup per la gestione delle iscrizioni.
Se vuoi registrare un’email manualmente, puoi inserire uno snippet come questo:
<span class="clerk" data-api="log/email" data-email="EMAIL@EXAMPLE.COM"></span>
Clienti loggati #
Se il tuo webshop ha account clienti, chiama log/email ogni volta che l’email di un cliente noto è disponibile nella sessione—sia quando si logga attivamente sia quando ritorna sul sito già loggato.
L’approccio più semplice è controllare a ogni caricamento pagina se un’email è disponibile, e in tal caso effettuare la chiamata. Per evitare chiamate API inutili, salva un flag nella sessione del browser in modo che venga inviata 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 il reale indirizzo email dalla tua piattaforma. Rendi visibile questo script solo quando c’è effettivamente un’email—saltalo per i guest.
Senza questa logica, Clerk.io può collegare la sessione del visitatore a un’email solo dopo un acquisto. Registrando l’email appena disponibile, il collegamento diventa immediato, requisito per inviare email automatizzate in base alla navigazione, mostrare raccomandazioni personalizzate nelle email e applicare campagne Merchandising rivolte a segmenti Audience specifici.
Come funziona l’associazione #
Quando un’email viene registrata, Clerk invia sia l’ID del visitatore che l’indirizzo email all’API in modo che possano essere collegati.
Questo permette a Clerk di identificare cosa ha fatto quel visitatore nella sua sessione (prodotti visti, click, ricerche) e associare quel comportamento all’indirizzo email.
Così, gli stessi dati comportamentali possono essere usati sia per (email trigger e personalizzate), sia per la personalizzazione onsite nelle Recommendations per clienti autenticati.
Context Reloads #
I context reload mantengono pertinenti le raccomandazioni mentre l’utente naviga su una single-page app o un headless storefront senza ricaricare tutta la pagina. Ad esempio, un blocco “Popolari in questa categoria” può aggiornarsi quando l’utente passa a un’altra categoria.
Questa funzione è attiva di default per i blocchi il cui ID deriva dal contesto Clerk.js (id_source: 'context'). Quando un valore del contesto cambia, Clerk.js ri-renderizza i blocchi già inizializzati che usano quella chiave, con il nuovo valore.
Aggiornamento del Contesto #
Chiama il setter pubblico del contesto quando il valore rilevante cambia. Ad esempio, dopo la navigazione nella categoria 276:
Clerk('context', 'category', '276');
Sostituisci 276 con l’ID della categoria dal tuo store. Puoi impostare il contesto prima o dopo l’inizializzazione di un blocco. Riapplicare lo stesso valore non produce effetti.
Le chiavi osservate sono:
| Chiave | Comportamento |
|---|---|
product | Aggiorna blocchi derivati dal prodotto corrente. Fornisce anche il tipo products (plurale). |
category | Aggiorna i blocchi derivati dalla categoria corrente. |
page | Aggiorna i blocchi derivati dal contesto pagina corrente. |
email | Popola o aggiorna i blocchi quando il contesto email diventa disponibile o cambia. |
Confronto con l’Observer #
I context reload funzionano anche con osservazione DOM disattivata. Aggiornano i blocchi già presenti in pagina quando un valore cambia, senza modificare l’HTML.
L’osservazione DOM rileva nuovo markup aggiunto così Clerk.js può inizializzare blocchi appena aggiunti e riprovare iniezioni il cui target è comparso. È abilitata separatamente. I context reload non usano MutationObserver, timer o listener DOM.
Evento contesto #
Usa l’evento context per reagire ai cambiamenti nel tuo frontend. Viene chiamato a ogni reale cambio di contesto, anche se i reload automatici sono disattivati. L’evento è relativo al contesto, non a un singolo blocco.
Clerk('on', 'context', ({ key, value, previous, context }) => {
// Qui puoi aggiornare la tua UI se serve.
});
Disabilitare i Reload #
Se il tuo store gestisce da sé questi aggiornamenti UI, disattiva i context reload automatici con:
Clerk('config', 'context_watch', false);
L’evento context resta disponibile anche coi reload automatici disabilitati.
Navigazione #
Nelle single-page app, popstate e hashchange fanno ripartire il controllo injection/contenuto. Le iniezioni basate su URL possono essere create quando cambiano le condizioni di corrispondenza, e i blocchi derivati dal contesto si ricaricano quando i valori cambiano.
Aggiorna il contesto Clerk.js quando l’utente naviga, così i valori riflettono la vista attuale. Consulta la guida per single-page app per inizializzazione e rendering manuale.
Limiti #
I blocchi il cui ID deriva dagli elementi pagina, e i popup, non vengono ricaricati dai cambi di contesto.
Durante l’iniezione, viene saltato un blocco a cui manca un valore di contesto richiesto, fino al prossimo controllo injection. Fanno eccezione le email: i blocchi email possono essere creati anche senza email e popolati quando diventa disponibile.
L’osservazione DOM può innescare il controllo injection che crea il blocco saltato. Questo fallback è separato dal ricaricare un blocco già renderizzato.
Ogni chiave cambiata genera una chiamata API aggiuntiva. Evita di aggiornare il contesto in loop o a ogni evento di routing, a meno che i cambi siano intenzionali.
Osservazione DOM #
Abilita l’osservazione DOM quando il tuo webshop aggiunge contenuti Clerk.io dopo il caricamento pagina. Clerk.js osserva le modifiche alla struttura della pagina (DOM) così può rilevare i contenuti appena appaiono.
Puoi abilitare questa funzione tramite SPA Auto Detect Changes in my.clerk.io o aggiungendo observe_dom: true alla configurazione 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 Recommendations Clerk.io e quindi aggiunge lo snippet in pagina quando il carrello si apre.
Con l’approccio basato su timer, Clerk.js controlla le modifiche ogni secondo. Lo snippet puede attendere il prossimo check prima che Clerk.js lo rilevi.
Con observe_dom attivo, l’aggiunta del carrello fa subito scattare un controllo. Clerk.js può rilevare lo snippet subito e mostrare le Recommendations, riducendo l’attesa dopo l’apertura del carrello.
Altri esempi #
Stesso comportamento aiuta quando i contenuti appaiono senza ricaricare la pagina:
- Add-to-cart popup: Il webshop mostra un popup con Recommendations Clerk.io dopo che l’utente aggiunge un prodotto. Clerk.js rileva i nuovi contenuti quando il popup appare.
- Sezione lazy-load: Il webshop aggiunge un blocco Clerk.io più in basso nella pagina mentre l’utente scorre. Clerk.js lo rileva quando viene aggiunto.
- Single-page app: Un’app React o Vue aggiunge i contenuti Clerk.io quando l’utente naviga tra le viste. Clerk.js rileva i nuovi contenuti senza attendere il reload totale della pagina.
L’osservazione DOM vale anche per blocchi contenuto, form iscrizione email e live search.
Attivare l’osservazione #
Scegli uno di questi modi per abilitare l’osservazione DOM:
- Backend: Su my.clerk.io, apri il tuo Store e vai su Settings > Features. Abilita SPA Auto Detect Changes.
- Codice: Aggiungi
observe_dom: truealla tua configurazione Clerk.js, come mostrato sotto.
Entrambe le opzioni abilitano la stessa funzione; è sufficiente usarne una.
Clerk('config', {
key: 'INSERT_PUBLIC_API_KEY',
observe_dom: true
});
Conserva la public API key del tuo Store e qualsiasi altra opzione già presente.
Dovrai comunque aggiungere il corretto snippet Clerk.io e configurare Element e Design. L’osservazione serve a far rilevare a Clerk.js i contenuti aggiunti in seguito; non si traduce in posizionamenti Recommendations automatici.
Per rendering manuale e selettori custom, vedi Custom Rendering.
Utilizzo risorse #
Clerk.js raggruppa le modifiche rapide della pagina in un unico passaggio e limita i passaggi completi a uno ogni 500 ms. L’osservatore resta inattivo quando la pagina è ferma e non genera nuove chiamate API o traffico di rete.
L’impostazione è opt-in. Gli Store che non la abilitano tengono il comportamento attuale.
Custom Rendering #
È usato soprattutto con Single Page App (SPA), Progressive Web App (PWA) e altre applicazioni che non usano normali caricamenti di pagina.
Clerk.js renderizza gli elementi con la classe clerk, ma puoi usare altre classi per personalizzare il rendering come selettori personalizzati.
Per default, Clerk richiede di eseguire Clerk("content", "SELECTOR") ogni volta che vuoi mostrare il contenuto.
Aggiungendo auto_init_custom_selectors: true alla config, Clerk.js inizializza automaticamente gli elementi dei selettori personalizzati mentre il DOM cambia, purché siano già stati renderizzati una volta con Clerk("content", "SELECTOR").
Questo comportamento continua fino a un refresh completo della pagina.
Debugging #
Clerk.js ha una modalità debug integrata che logga informazioni diagnostiche nella console del browser. Salva la configurazione in sessionStorage sotto il nome __clerk_debug, mantenendo la modalità debug attiva per tutte le navigazioni nella stessa sessione browser.
Per default, debug è attivo con level su warn e collect su true.
Modi di attivazione #
Ci sono tre modi per attivare la modalità debug.
Shorthand in console
Il modo più semplice è chiamare Clerk('debug') dalla console. Accetta diversi formati di argomento:
Clerk('debug'); // Abilita con default
Clerk('debug', true); // Abilita
Clerk('debug', false); // Disabilita
Clerk('debug', 'on'); // Abilita
Clerk('debug', 'off'); // Disabilita
Clerk('debug', 'warn'); // Imposta il livello di log
Clerk('debug', { // Passa un oggetto configurazione completo
enable: true,
level: 'log',
group: true
});
Percorso config
La debug mode può essere configurata anche con la normale chiamata config:
Clerk('config', 'debug', {
enable: true,
level: 'log',
collect: true,
group: true,
collapsed: false
});
Hash URL
Puoi attivare la modalità debug aggiungendo un hash alla URL. Utile per condividere link di debug:
https://yourwebsite.com/#clerkjs:debug.enable=true&debug.level=warn
Se l’attivi tramite hash, la configurazione viene salvata in sessionStorage sotto la chiave __clerk_tmp_config.
Opzioni Config #
| Opzione | Descrizione | Tipo | Default |
|---|---|---|---|
enable | Abilita/disabilita i messaggi debug nella console browser. | bool | true |
level | Imposta il livello di log. Accetta log, warn, error. | string | warn |
collect | Se true, salva i log nello storage browser. Se false, storage temporaneo. | bool | true |
group | Raggruppa i log correlati in console. | bool | — |
collapsed | Se true, i gruppi vengono chiusi di default (vale solo se group). | bool | — |
clear | Cancella tutti i log salvati. | bool | — |
Session Storage #
Quando è attiva la debug mode, la configurazione viene salvata in sessionStorage come __clerk_debug. Così le impostazioni persistono mentre il visitatore passa tra pagine diverse, senza toccare altri tab o persistere oltre la sessione.
Consent Management Platforms (CMP) come Cookiebot potrebbero segnalare __clerk_debug come voce storage da documentare. È una chiave funzionale usata solo a scopo di debug sviluppatori. Non contiene dati personali o di tracciamento.
Per dettagli sulla struttura delle risposte API in debug, vedi Response debugging.
UI Kit #
Clerk.js include un set di strumenti UI per elementi importanti che possono arricchire l’esperienza utente. Questi aiutano a ridurre i tempi di sviluppo per personalizzazioni.
Instant Search #
Una parte fondamentale di una grande esperienza search eCommerce è ottenere risultati immediati mentre si digita. Il nostro componente UI Instant Search rende questa esperienza rapida e semplice da costruire.
Qualsiasi contenuto Clerk.io può teoricamente essere trasformato in componente Instant Search, ma dà il meglio come dropdown con i risultati della 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ù sull’ Instant Search UI tool qui.
Search Page #
Per una grande esperienza search eCommerce è fondamentale ottenere buoni risultati. La nostra Search Page permette di realizzare una pagina completa che mostra i migliori risultati per una 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.
Category Page #
Una pagina categoria ben strutturata è la chiave per l’eCommerce di successo. La nostra Category Page consente di creare velocemente una pagina intera con i migliori risultati della 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ù sul Category Page UI tool qui.
Facet #
Clerk.js integra il supporto per la navigazione dinamica a faccette sia per search che per categorie. Qualsiasi attributo prodotto inviato può diventare una faccetta.
Esempio di uso 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 exit intent si attiva quando il visitatore cerca di lasciare il sito spostando il mouse vicino al bordo superiore della finestra browser. Si apre mostrando prodotti interessanti, trasformando potenzialmente un visitatore in cliente.
Qualsiasi blocco Element può essere attivato su intenzione di uscita 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ù sull’ Exit Intent UI tool qui.
Popup #
UI Kit contiene una libreria di popup semplice per creare facilmente popup user-friendly con qualsiasi contenuto. Ogni elemento HTML del tuo 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ù sul Popup UI tool 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 da una tua UI, fornire dati contestuali all’AI rispetto alle azioni del visitatore o ricevere eventi della conversazione nel tuo frontend.
Vedi tutta la documentazione di metodi ed eventi nelle Chat JS docs.
Aprire Chat da bottone personalizzato #
Se vuoi attivare la Chat da un tuo bottone/UI invece che dal launcher standard, usa toggle:
<button onclick="Clerk('chat', 'toggle')">
Serve aiuto?
</button>
Puoi anche usare open e close in modo indipendente per controllare lo stato in modo esplicito.
Mostrare Chat solo in pagine specifiche #
Per default, Chat è visibile su tutto il sito. Per mostrarla solo dove desideri, disattivala nella config globale e attivala dove ti serve:
// Nella config globale Clerk.js — nascondi Chat ovunque
Clerk('config', { key: 'your-public-api-key' });
Clerk('chat', 'disable');
// Poi nelle pagine dove vuoi mostrarla
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ù pertinenti. Chiamalo quando cambia il contesto—navigazione, aggiunta a carrello, aggiornamento preferenze.
// Su una pagina prodotto
Clerk('chat', 'metadata', {
current_page: {
page_type: 'product',
page_id: '12345'
}
});
// Dopo che l’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: include le informazioni utili alla conversazione su quella pagina.
Modificare il comportamento AI in base a cosa fa il visitatore #
Il metodo prompt_message invia un’istruzione di sistema all’AI. Il cliente non la vede, ma cambia come l’AI risponde nella conversazione attuale.
// Dopo aggiunta al carrello—spingi AI verso cross-sell
Clerk('chat', 'prompt_message', 'L’utente ha appena aggiunto un Lightsaber al carrello. Suggerisci prodotti complementari come accessori o protezioni.');
// Su pagina checkout—focalizza sull’acquisto
Clerk('chat', 'prompt_message', 'L’utente è sulla pagina di checkout. Aiutalo a concludere l’ordine e rispondi a domande dell’ultimo minuto.');
Passaggio a agente umano #
Quando il visitatore richiede assistenza umana, l’evento onSupport si attiva con il riassunto della conversazione. Puoi aprire la chat helpdesk e fargli trovare il contesto—l’utente non dovrà ripetere informazioni.
Clerk('config', {
key: 'your-public-api-key',
chat: {
onSupport: (e) => {
// e.summary contiene il riassunto in chiaro della conversazione effettuata
const summary = e.summary || 'Nessun riassunto conversazione disponibile.';
// Esempio: apri Intercom e pre-popolalo con il contesto
Intercom('showNewMessage', 'Continuando dalla Chat AI:\n\n' + summary);
}
// Esempio: apri Zendesk con il contesto precompilato
if (window.zE) {
zE('messenger', 'open');
zE('messenger:set', 'conversationFields', [
{ id: 'clerk_chat_summary', value: summary }
]);
}
// Opzionalmente nascondi Clerk Chat una volta completato il passaggio
Clerk('chat', 'disable');
}
}
});
L’evento onSupport viene attivato solo quando Contact Support è configurato nelle impostazioni di Chat e il visitatore richiede esplicitamente un operatore umano.
Reagire agli eventi di Chat #
Usa gli hook degli eventi per integrare il comportamento della Chat con il resto del tuo frontend — ad esempio, per registrare messaggi, sincronizzare lo stato o passare la conversazione a un operatore umano.
Clerk('config', {
key: 'your-public-api-key',
chat: {
onMessage: (e) => {
// Si attiva a ogni messaggio — il ruolo è '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 un riassunto della conversazione
openLiveChatWithSummary(e);
}
}
});
Puoi anche registrare gli hook degli eventi dinamicamente dopo la configurazione iniziale:
Clerk('chat', 'on', 'message', function(e) {
console.log('Nuovo messaggio:', e.message.text);
});
Leggi di più nella documentazione Chat JS.
Esclusione dei prodotti #
Clerk.js offre due modalità diverse per escludere prodotti, a seconda che tu voglia escludere degli 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 deve essere una lista degli ID dei prodotti che non vuoi mostrare, ad es. 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 vuoi rimuovere un duplicato. Il valore dell’attributo deve essere un selettore CSS per l’altro snippet o gli altri snippet da cui evitare i duplicati.
Nell’esempio sotto, .clerk-2 esclude qualsiasi prodotto presente in .clerk-1, e .clerk-3 esclude qualsiasi prodotto presente sia in .clerk-1 sia in .clerk-2.
<span class="clerk clerk-1"
data-template="@clerk-banner-1">
</span>
<span class="clerk clerk-2"
data-exclude-from=".clerk-1"
data-template="@clerk-banner-2">
</span>
<span class="clerk clerk-3"
data-exclude-from=".clerk-1,.clerk-2"
data-template="@clerk-banner-3">
</span>
Eventi #
Quando crei configurazioni più personalizzate, spesso sarà necessario reagire o modificare i risultati da Clerk prima della loro visualizzazione. È qui che gli Eventi sono utili.
Gli eventi ti permettono di impostare listener che eseguono codice in momenti specifici, prima, durante o dopo che Clerk.js visualizza i risultati.
Un esempio comune è caricare prezzi personalizzati per un cliente autenticato in una configurazione B2B. Un evento può essere eseguito subito dopo che le API di Clerk hanno terminato il rendering, permettendoti di recuperare i prezzi personalizzati per un 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 Eventi qui.
SEO e Prestazioni #
Clerk.js alimenta esperienze d’acquisto personalizzate senza rallentare il sito o danneggiare la SEO. Usando il rendering lato client e il caricamento ottimizzato, bilancia velocità, prestazioni e visibilità sui motori di ricerca.
SEO e velocità #
È un luogo comune pensare che funzionalità JavaScript come Clerk.js danneggino le prestazioni o la SEO. Gli strumenti automatici spesso trascurano ottimizzazioni come 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 sito di essere caricato mentre Clerk viene inizializzato.
- 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 server-side efficiente e un caricamento non bloccante degli asset di Clerk.js.
Impatto sulle prestazioni #
- La natura leggera e asincrona di Clerk.js comporta in genere un impatto minimo sui tempi di caricamento della pagina.
- Gli impatti sulle prestazioni dipendono spesso dalle immagini aggiuntive mostrate dalle Recommendations, non dallo script in sé. Per ridurre l’impatto:
- Usa formati ad alta efficienza e dimensioni appropriate come WebP.
- Ridimensiona le immagini in base alle dimensioni di visualizzazione (ad es. 400×400 px → max 420×420 px).
- Per evitare spostamenti di layout (CLS), riserva spazio per il contenuto Clerk iniettato.
Es.:
.clerk-slider-wrapper {
min-height: 300px; /* regola in base alle necessità */
width: 100%;
}
Aspetti SEO #
Comprendere come Clerk.js interagisce con i motori di ricerca aiuta a garantire che la tua implementazione supporti sia l’esperienza utente sia la visibilità nella ricerca.
Collegamenti e indicizzabilità #
- Clerk.js inietta dinamicamente i link delle recommendations lato client.
- Questi link possono migliorare il linking interno collegando pagine correlate, se i motori di ricerca li renderizzano e li seguono correttamente.
- Poiché sono inseriti tramite JavaScript, dovresti verificare come i crawler dei motori di ricerca li visualizzano e li interpretano.
- Se i link sono correttamente indicizzati, possono migliorare l’indicizzabilità e permettere ai motori di ricerca di scoprire e indicizzare più pagine.
Distribuzione del PageRank #
- Quando i motori di ricerca possono eseguire la scansione, i link Clerk.js possono aiutare a distribuire il PageRank tra le pagine chiave.
- Questo supporta una migliore visibilità e posizionamento di pagine prodotto e categorie.
Benefici osservati #
- Una corretta integrazione Clerk.js può portare a strutture di linking interno più forti, che possono supportare una migliore visibilità nei risultati di ricerca.
- Le dashboard di Clerk.io forniscono analytics sull’influenza sugli ordini, miglioramenti delle conversioni e contributo al fatturato da Search, Recommendations, Email e Audience.
Best practice consigliate #
- Ottimizza le immagini (formato WebP, risoluzione corretta).
- Riserva spazio di layout per elementi dinamici per prevenire spostamenti di layout.
- Monitora le metriche reali invece di basarti solo su punteggi automatici. Usa le dashboard di Clerk per valutare l’impatto su tutti i canali.
Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.