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’utilizzare Clerk.js:

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

Clerk.js si carica con uno script di inizializzazione aggiunto all’header del sito web:

<!-- Inizio dello strumento di personalizzazione e-commerce Clerk.io - 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>
<!-- Fine dello strumento di personalizzazione e-commerce Clerk.io - www.clerk.io -->

Carica la libreria dal nostro CDN e ti consente di accedere alle sue funzionalità tramite l’oggetto Clerk, e configura Clerk.js con la chiave API in modo che sappia già per quale Negozio sta effettuando chiamate API.

Snippet #

Quando la pagina viene caricata, Clerk.js la scansiona per eventuali snippet con la classe “clerk”.

Utilizza quindi gli attributi dello snippet per costruire una chiamata API mentre ottiene 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>

I visual sono gestiti dal Design, che è anche referenziato dallo snippet.

Clerk.js utilizza design Liquid per renderizzare HTML con i dati restituiti dall’API. Questi sono formattati come script, referenziati dal loro ID in data-template nel tuo snippet.

<span class="clerk"
     data-api="search/search"
     data-query="jedi"
     data-limit="20"
     data-template="#clerk-template">
</span>

<script type="text/x-template" id="clerk-template">
  <h1>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 per includere solo un riferimento a un Content block, utilizzando la sintassi data-template="@content-block-id":

<span class="clerk"
     data-template="@product-page-alternatives"
     data-products="[12352]">
</span>

I design sono quindi gestiti con il Design Editor o con codice HTML Liquid in modo user-friendly da my.clerk.io.

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

Iniezione #

L’iniezione è una funzionalità che ti consente di inserire snippet di contenuto nel tuo sito web senza doverli aggiungere manualmente. Invece, scegli semplicemente un selettore CSS in cui iniettare lo snippet, e Clerk.js aggiungerà automaticamente il contenuto al caricamento della pagina.

Leggi di più su Iniezione qui.

Configurazione #

Clerk.js consente una varietà di configurazioni che cambiano il suo funzionamento.

ID Visitatori #

Per impostazione predefinita, Clerk.js genera ID visitatori anonimi, utilizzati per tracciare le sessioni.

Se i clienti accettano i cookie, Clerk.js può essere configurato per posizionare un cookie persistente con l’ID visitatore, che consente il tracciamento per un periodo di tempo più lungo.

Se preferisci gestire manualmente gli ID di sessione, puoi configurare il parametro visitor che Clerk utilizza 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 dei visitatori
Clerk('config', {
  visitor: null
});

Lingua #

Configura Clerk.js con la lingua scritta del sito web. Questo è utilizzato da Clerk.io per gestire correttamente le regole grammaticali nella ricerca e per recuperare le traduzioni corrette quando utilizzi feed multilingue.

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

Funzioni di Design #

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

Formatters #

Questi sono utilizzati per influenzare o modificare gli attributi. Ad esempio, potresti voler mostrare solo i primi 40 caratteri di una descrizione, o potresti dover calcolare una percentuale di sconto specifica in base al tipo di cliente che ha effettuato l’accesso.

Globals #

Questi sono destinati ad essere utilizzati con i dati frontend a cui desideri accedere nei design. Questo potrebbe includere esempi come l’importo rimanente necessario per ottenere la spedizione gratuita, il nome di un cliente loggato, un simbolo di valuta o un tasso di cambio.

Di seguito è riportato un esempio di configurazione di formatters e globals.

Config #

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

Design #

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

Output #

<div class="name">LUCE VERDE</div>
<div class="price">$1999.99</div>

Tracciamento Email #

Clerk.js può automaticamente raccogliere email nella sessione del cliente per essere utilizzate per personalizzare le raccomandazioni email anche se non hanno ancora effettuato un ordine.

Questo viene fatto configurando Clerk.js con collect_email: true come mostrato qui:

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

Con questo, Clerk.js monitorerà tutti i campi di input sul sito web e lo registrerà con log/email quando un visitatore scrive un indirizzo email in uno di essi:

https://api.clerk.io/v2/log/email?payload={"email":"test@test.com","key":"insert_api_key","visitor":"auto"}

Rendering Personalizzato #

Questo è principalmente utilizzato con Single Page Apps (SPA), Progressive Web Apps (PWA) e altre applicazioni che non utilizzano caricamenti di pagina tradizionali.

Clerk.js renderizza qualsiasi elemento con la classe clerk, ma altre classi possono essere utilizzate per personalizzare il rendering come selettori personalizzati.

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

Aggiungere auto_init_custom_selectors: true alla configurazione, fa sì che Clerk.js inizializzi automaticamente qualsiasi elemento selettore personalizzato mentre il DOM muta, purché siano già stati renderizzati con Clerk("content", "SELECTOR") almeno una volta.

Questo comportamento continua fino a quando non si verifica un aggiornamento completo della pagina.

Debugging #

Clerk.js ha una modalità di debug integrata che registrerà varie informazioni nella console, a seconda del livello scelto. È configurato direttamente nell’URL:

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

Il debugger ha 4 parametri:

UI Kit #

Clerk.js include un insieme di strumenti UI per elementi importanti che possono essere utilizzati per migliorare l’esperienza utente. Questi spesso risparmiano tempo di sviluppo per configurazioni personalizzate.

Ricerca Istantanea #

Una parte fondamentale di una grande esperienza di ricerca e-commerce è ottenere risultati immediatamente mentre inizi a digitare. Il nostro componente UI di Ricerca Istantanea rende questa esperienza utente rapida e facile da costruire.

Qualsiasi contenuto di Clerk.io può teoricamente essere trasformato in un componente di Ricerca Istantanea, ma funziona meglio come un menu a discesa che mostra i risultati della ricerca.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
  data-labels='["Ricerca Istantanea"]'
      
  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ù sul tool UI di Ricerca Istantanea qui.

Pagina di Ricerca #

Una parte fondamentale di una grande esperienza di ricerca e-commerce è ottenere buoni risultati di ricerca. La nostra Pagina di Ricerca rende questa esperienza utente rapida e facile da costruire.

La Pagina di Ricerca ti consente di creare una pagina completa che mostra i migliori possibili risultati per qualsiasi query data.

<span 
  class="clerk"
  
  data-api="search/search"
  data-limit="40"
  data-labels='["Pagina di Ricerca"]'
  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 tool UI della Pagina di Ricerca qui.

Pagina di Categoria #

Una pagina di categoria ben strutturata è fondamentale per un’attività eCommerce di successo. La nostra Pagina di Categoria rende questa esperienza utente rapida e facile da costruire. Questo ti consente di creare una pagina completa che mostra i migliori possibili risultati per qualsiasi categoria.

<span 
  class="clerk"
  
  data-api="recommendations/category/popular"
  data-limit="40"
  data-labels='["Griglia Pagina di Categoria"]'
  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 tool UI della Pagina di Categoria qui.

Facets #

Clerk.js viene fornito con supporto integrato per la navigazione dinamica a faccette sia per la ricerca che per le categorie. Qualsiasi attributo di prodotto che ci invii può essere utilizzato come faccetta.

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": "TRADUZIONE-PREZZO", "categories": "TRADUZIONE-CATEGORIE", "brand": "TRADUZIONE-MARCA"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="Visualizza di più"
  data-facets-searchbox-text="Cerca per "
  data-facets-design="133995">
</span>

Leggi di più sul tool UI delle Facets qui.

Intento di Uscita #

Il popup per l’intento di uscita reagisce quando un visitatore cerca di lasciare il tuo sito passando il mouse vicino alla parte superiore della finestra del browser. Si apre e mostra prodotti interessanti, convertendo possibilmente un visitatore in uscita in un cliente acquirente.

Qualsiasi Content block può essere attivato in base all’intento di uscita di un visitatore aggiungendo l’attributo data-exit-intent="true" allo snippet.

<span
  class="clerk"
  
  data-api="recommendations/visitor/complementary"
  data-limit="20"
  data-labels='["Intento di Uscita / Popup"]'
  
  data-exit-intent="true">
</span>

Leggi di più sul tool UI dell’Intento di Uscita qui.

Popup #

Il UI Kit contiene una semplice libreria di popup per creare facilmente popup semplici ma user-friendly con qualsiasi contenuto. Qualsiasi elemento HTML sul tuo sito web con la classe clerk-popup verrà visualizzato come un 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 tool UI del Popup qui.

Escludere Prodotti #

Clerk.js ha due modi diversi per escludere prodotti, a seconda che tu voglia escludere ID specifici o evitare di mostrare prodotti duplicati tra diversi slider.

Escludere ID Specifici #

Basta aggiungere l’attributo data-exclude allo snippet. Il contenuto di data-exclude dovrebbe essere un elenco degli ID prodotto che non vuoi siano mostrati, ad esempio i prodotti nel carrello del cliente o un elenco di prodotti che non possono vedere.

<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 dovrebbe essere un selettore CSS per gli altri snippet da cui prevenire i duplicati.

Nell’esempio seguente, .clerk-2 esclude qualsiasi prodotto che si trova in .clerk-1, e .clerk-3 esclude qualsiasi prodotto che si trova 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>

Leggi di più sul tool UI per Escludere Prodotti qui.

Eventi #

Quando costruisci configurazioni più personalizzate, spesso avrai bisogno di reagire o modificare i risultati di Clerk prima di renderizzarli. Qui è dove Eventi sono utili.

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

Un esempio comune è caricare prezzi personalizzati per un cliente loggato in una configurazione B2B. Un evento può essere eseguito immediatamente dopo che l’API di Clerk ha terminato il rendering, consentendo di recuperare prezzi personalizzati per un cliente e aggiungerli agli elementi del 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.