Qualsiasi (webshop)

Commesso.js

Panoramica #

Clerk.js è una libreria JavaScript che semplifica l’integrazione della nostra API con il vostro frontend. L’utilizzo di Clerk.js presenta tre vantaggi:

  • È robusto, poiché viene caricato in modo asincrono. Ciò significa che il resto della pagina non dipende dalla risposta dell’API prima del caricamento.
  • Spesso è più veloce, perché il server può iniziare il rendering della pagina in parallelo con Clerk.js che effettua le chiamate e restituisce i risultati.
  • Il tracciamento dei visitatori e dei clic viene gestito automaticamente per tutti i risultati mostrati da Clerk. Ciò non richiede l’uso di cookie, poiché generiamo un valore hash dell’IP e dell’useragent del visitatore, abbinato a un sale unico del negozio che ruota ogni 30 giorni.

Clerk.js viene caricato con uno script di tracciamento leggero aggiunto all’header del sito web.

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
  (function(w,d){
    var e=d.createElement('script');e.type='text/javascript';e.async=true;
    e.src='https://cdn.clerk.io/clerk.js';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
    w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){ w.__clerk_q.push(arguments) };
  })(window,document);

  Clerk('config', {
    key: 'insert_api_key'
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Questo script carica la libreria dal nostro CDN e consente di accedere alle sue funzionalità attraverso l’oggetto “Clerk”. Lo script configura Clerk.js con la chiave API, in modo che sappia già per quale Store sta effettuando le chiamate API.

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

Utilizza quindi gli attributi dello snippet per creare una chiamata API, ottenendo la chiave API dalla configurazione dello script di inizializzazione.

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

La rappresentazione visiva è gestita dal disegno, a cui fa riferimento anche lo snippet.

Clerk.js utilizza i design Liquid, conosciuti da Shopify, per rendere l’HTML con i dati restituiti dall’API. Questi dovrebbero essere formattati come script, con un ID a cui fare riferimento in “data-template” del proprio 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>Search result for {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Buy Now</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Load More Results</a>
</script>

Gli snippet possono anche essere semplificati per includere solo un riferimento a un Content all’interno di my.clerk.io.

I progetti vengono poi gestiti con un editor visuale o con il codice HTML liquido proprio come nel frontend.

Con questo approccio, la maggior parte della configurazione viene effettuata in modo semplice dal pannello di amministrazione. Gli snippet dovranno contenere solo la classe “clerk “, qualsiasi informazione specifica della pagina, come gli ID dei prodotti, e un riferimento all’ID di un blocco Content in “data-template “.

<span class="clerk"
     data-template="@product-page-alternatives"
     data-products="[12352]">
</span>
Screenshot 2023-06-13 at 11.49.01

Configurazione #

Clerk.js consente una varietà di configurazioni.

Come già detto, se si preferisce gestire manualmente gli ID di sessione, è possibile configurare il parametro visitor che Clerk utilizza nelle chiamate API. In alternativa, è possibile disattivare completamente il tracciamento delle sessioni impostando visitor a null.

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

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

È possibile aggiungere Formatters e Globals all’ambito di progettazione.

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

I globali devono essere usati con i dati di frontend a cui si vuole accedere nei progetti. Ad esempio, l’importo rimanente necessario per ottenere la spedizione gratuita, il nome di un cliente connesso, un simbolo di valuta o un tasso di conversione.

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

// Use in Design

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

Tracciamento automatico delle e-mail dei visitatori #

Clerk.js è in grado di **raccogliere automaticamente le e-mail nella sessione di navigazione del cliente, da utilizzare per le e-mail di Cestino abbandonato e altre campagne e-mail.

È sufficiente configurare Clerk.js con collect_email: true come mostrato qui:

HTML

<!-- 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',
    collect_email: true
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Kit UI #

Clerk.js include una serie di strumenti UI per elementi importanti come il search dropdown e le facets di una pagina di ricerca.

Ad esempio, il kit per il dropdown di ricerca consente di creare uno snippet che controlla il campo di input attraverso un selettore CSS e visualizza un dropdown con il contenuto corrispondente alla ricerca effettuata dal visitatore.

<span
  class="clerk"

  data-api="search/predictive"
  data-limit="6"

  data-instant-search="INSERT_CSS_SELECTORS_HERE">

  <dl class="product-search-result-list">
    <dt>Products matching <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 }}">Buy Now</a>
      </dd>
    {% endfor %}
  </dl>
</span>

I Facet consentono di estendere lo snippet della pagina di ricerca esistente per includere filtri per i prodotti nella pagina di ricerca.

<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": "YOUR-PRICE-LABEL-TRANSLATION-GOES-HERE", "categories": "YOUR-CATEGORIES-LABEL-TRANSLATION-GOES-HERE", "brand": "YOUR-BRAND-LABEL-TRANSLATION-GOES-HERE"}'
  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>

Eventi #

Quando si creano configurazioni più personalizzate, ad esempio per le aziende B2B, è spesso necessario reagire o modificare i risultati di Clerk prima di renderli.

È qui che Events è utile.

Gli eventi consentono di impostare ascoltatori di eventi che eseguono codice in momenti specifici, prima, durante o dopo il rendering dei risultati di Clerk.js. Un caso d’uso comune è quello in cui è necessario verificare quale utente è loggato e recuperare prezzi specifici per il suo gruppo di clienti o rimuovere prodotti che non sono autorizzati a vedere.

Ad esempio, un evento può essere eseguito immediatamente dopo la risposta dell’API di Clerk, consentendo di chiamare il database dei prezzi con l’ID del cliente e i prodotti restituiti da Clerk per ottenere i prezzi corretti prima che Clerk.js visualizzi i risultati.

Clerk("on", "response", function(content, data) {
    let products = data['product_data'];
    const product_ids = data['result'];
    const customer_prices = getUniquePrices(customer_group, product_ids); // {"27746": 310.25, "26994": 124.50}
    products.forEach(product =>
      product['price'] = customer_prices[product['id']]) // Add customer price based on product ID;
  })