FAQ

App web a pagina singola (SPA) #

Questi sono anche chiamati Progressive Web Apps (PWA) e generalmente caricano il sito come una singola pagina, piuttosto che caricare pagine individuali come di consueto.

Quando una pagina viene caricata per la prima volta, la libreria Clerk.js attiva automaticamente una funzione per rendere tutti i blocchi Content su quella pagina.

Tuttavia, per le app a pagina singola che utilizzano framework come vue.js o next.js, le pagine vengono renderizzate con JavaScript piuttosto che con un caricamento standard della pagina. A causa di ciò, è necessario controllare il rendering con Clerk.js per abbinare il modo in cui carichi le pagine nell’app.

Includere Clerk.js #

Clerk.js deve essere caricato solo una volta, quando il sito viene inizialmente caricato. Dopo questo, la libreria sarà disponibile per tutta la sessione. Includila appena prima del </head> nel tuo HTML:

<!-- Inizio dello strumento di personalizzazione E-commerce di 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_PUBLIC_API_KEY'
    });
</script>
<!-- Fine dello strumento di personalizzazione E-commerce di Clerk.io - www.clerk.io -->

Controllare il Rendering #

Per impostazione predefinita, Clerk.js rende qualsiasi elemento che ha la classe clerk, indipendentemente dal fatto che sia stato inserito durante il caricamento iniziale della pagina o quando il DOM muta. Puoi controllare il timing inserendo l’elemento quando è pronto per essere reso.

In alternativa, puoi controllare il rendering con la funzione Clerk("content", "SELECTOR").

Ogni volta che una pagina viene caricata, esegui questi passaggi in ordine:

• Aggiungi il frammento Clerk all’HTML con un selettore unico che puoi mirare.
• Esegui Clerk("content", "SELECTOR") per renderizzarlo.

Quando il visitatore lascia la pagina, distruggi il frammento e renderizzalo di nuovo se il visitatore torna sulla stessa pagina. Questo per garantire che Clerk.js non veda il frammento come precedentemente reso, causando la mancata visualizzazione.

Esempio:

<span 
  id="clerk-custom-snippet"
  data-template="@home-page-visitor-recommendations">
</span>

<script>
  Clerk("content", "#clerk-custom-snippet")
</script>

Clerk.js può anche essere configurato per inizializzare automaticamente il Contenuto con i tuoi selettori personalizzati dopo la prima volta che lo rendi.

Impatto su Pagespeed #

Aggiungere uno strumento esterno come Clerk.js aumenterà il tempo necessario per caricare il tuo sito, ma è trascurabile rispetto alle conversioni aggiuntive che fornirà. Di seguito puoi vedere come impatta le prestazioni del tuo sito.

Prestazioni #

La libreria Clerk.js è di soli 37.5kb, quindi si carica molto rapidamente. Inoltre, carica gli elementi in modo asincrono, il che significa che il resto della pagina si carica mentre Clerk.js rende il contenuto.

Un aumento del tempo di caricamento di una pagina deriva più spesso dal caricamento di più immagini rispetto a prima, poiché i risultati di ricerca e le raccomandazioni di Clerk funzionano meglio quando sono visivamente accattivanti.

Per minimizzare il tempo di caricamento extra, ti consigliamo di utilizzare immagini in formato webp che abbiano una risoluzione corrispondente alla dimensione che hanno negli elementi Clerk.

Ad esempio, se le immagini nelle raccomandazioni hanno una risoluzione di 400x400px nella vista desktop, invia immagini con una risoluzione massima di 420x420px o simile.

Google Page Speed #

Se utilizzi Google Page Speed Insights o uno strumento simile per analizzare le prestazioni del tuo sito, potresti vedere Clerk.js elencato sotto Leverage browser caching.

Lo scopo di Clerk.js è rendere super semplice inserire i risultati di Clerk.io in qualsiasi sito web. Clerk.js contiene molte funzionalità per gestire il tracciamento e i componenti UI come Instant Search, slider, popup e altro.

Quando aggiungiamo nuove funzionalità UI o apportiamo miglioramenti a quelle esistenti, esse sono incluse in Clerk.js e devono essere scaricate dall’utente finale per poterle utilizzare.

Avere una scadenza della cache di 60 minuti significa che quando rilasciamo nuove funzionalità, saranno disponibili per tutti entro un massimo di 60 minuti. Più lungo è il tempo di cache, più tempo ci vorrà affinché tutti abbiano accesso alle funzionalità più recenti.

La cosa importante è che gli utenti finali devono scaricare Clerk.js una sola volta quando le nuove funzionalità sono disponibili.

La scadenza della cache di 60 minuti significa solo che il browser dell’utente finale controllerà con Clerk.io ogni 60 minuti. Se non sono state apportate modifiche a Clerk.js, nulla verrà scaricato.

Il tempo di scadenza della cache di 60 minuti è quindi un compromesso tra la minimizzazione delle richieste web e l’introduzione di nuove funzionalità e miglioramenti. La maggior parte delle sessioni è più breve di 60 minuti e quindi la richiesta verrà effettuata solo una volta per sessione.

Come puoi vedere nello screenshot, questa è una pratica normale che (così come Clerk.io) è utilizzata da Google Analytics, Facebook, Trustpilot e molti altri.

Impatto CLS #

Il Cumulative Layout Shift (CLS) può influenzare negativamente SEO e l’esperienza utente quando il contenuto iniettato dinamicamente sposta elementi su una pagina. In alcuni casi, tra gli altri fattori, Clerk può contribuire al punteggio CLS. Puoi leggere di più su CLS qui.

Segui questa linea guida solo nel caso in cui il tuo punteggio CLS sia superiore a 0.2 e gli elementi Clerk siano sopra la piega.

Per prevenire lo spostamento del contenuto, è necessario riservare un segnaposto per le raccomandazioni Clerk prima che Clerk.js le inietti. Per farlo, dobbiamo aggiungere un’altezza minima basata sull’altezza del contenuto previsto.

Esempio di codice:

.clerk-slider-wrapper {
    min-height: 300px; /* Regola in base all'altezza del contenuto previsto */
    width: 100%;
}

Effettuare chiamate API #

Puoi utilizzare Clerk.js per effettuare chiamate API, utilizzando la funzione integrata Clerk("call").

Questa funzione accetta 3 argomenti:

• Un endpoint API
• Un dizionario JSON di parametri
• Una funzione di callback per gestire la risposta

Richieste #

Di seguito è riportato un esempio di script che richiede i 10 prodotti più popolari e registra la risposta nella console. La risposta contiene un oggetto JavaScript con lo stato della chiamata API e il risultato.

Script #

function popularProducts(){
  Clerk("call",
    "recommendations/popular",
    {
      limit: 10,
      labels:["Home Page / Bestsellers"]
    },
    function(response){
      console.log(response);
    },
    function(response){
      console.error(response);
    }
  );
}

Risposta #

__clerk_cb_1(
  {
   "status":"ok",
   "count":72,
   "facets":null,
   "result":[399,410,551,338,403,439,425,402,406,456]
  }
);

Callback #

Quando effettui chiamate API, puoi utilizzare le funzioni callback per gestire la risposta come meglio credi. Le funzioni prendono response come argomento che contiene tutti i dati restituiti dall’API.

Di seguito è riportato un esempio che crea un elenco di elementi HTML collegati a categorie che corrispondono alla query “uomini”.

Clerk("call",
  "search/categories",
  {
      'query': "men",
      'limit': "10"
  },
  function(response) {
      var cat = response.categories;
      if (cat.length > 0) {
          let heading = document.createElement('h3');
          heading.textContent = 'Categorie Correlate';
          document.querySelector('#your-target').append(heading);
      }
      for (var index in cat) {
          var clerkName = cat[index].name;
          var clerkUrl = cat[index].url;
          let link = document.createElement('a');
          link.href = clerkUrl;
          link.textContent = clerkName;
          document.querySelector('#your-target').append(link);
      }
  }
)

Pulsanti Aggiungi al Carrello #

Questi pulsanti funzionano in modo diverso per ciascuna piattaforma e la funzionalità può cambiare a seconda dei plugin che utilizzi. Poiché i design di Clerk consistono in HTML & CSS, puoi solitamente aggiungere questa funzionalità se comprendi come funziona sul tuo sito.

Approccio Generale #

Alcuni pulsanti Aggiungi al carrello richiedono che Javascript venga eseguito, affinché funzionino. In questi casi, puoi aggiungere la funzionalità al metodo cart esistente di Clerk. Controlla come farlo nella nostra documentazione per sviluppatori qui.

Ispeziona il pulsante Aggiungi al carrello per identificare il codice associato ad esso, ad esempio, su una pagina di categoria. Il codice sarà solitamente un elemento <div> o un elemento button. Copia l’intero HTML del pulsante.

Copia e incolla questo codice nel tuo Design. Ora devi identificare le variabili nel codice. Spesso, devi trovare dove il codice utilizza:

• ID prodotto
• Quantità prodotto

Sostituisci i valori per l’ID prodotto con le variabili Liquid per questi punti dati. L’ID sarà sempre {{ product.id }} e la quantità varierà a seconda di come stai inviando i dati. Per questo esempio potrebbe essere {{ product.qty }}.

Incolla il tuo codice nell’HTML del tuo Design e testalo per assicurarti che funzioni.

Esempio #

Il pulsante Aggiungi al carrello qui sotto è un <div> che ha la classe button-container:

La quantità si trova all’interno del link del carrello dopo /cart?add= e l’ID prodotto si trova subito dopo &id_product=.

L’ID prodotto è anche riferito in data-id-product, e la quantità prodotto è riferita in .data-minimal_quantity

Questi valori devono essere sostituiti con tag Liquid nel Design in modo che gli ID e le quantità di prodotto appropriati siano utilizzati nell’output HTML.

Con queste modifiche, il pulsante Aggiungi al carrello finale apparirà così:

<div class="button-container">
  <a 
    class="button ajax_add_to_cart_button btn btn-default" 
    style="position: relative;" 
    href="https://www.examplelinktocart.com/cart?add={{ product.qty }}&amp;id_product={{ product.id }}&amp;" 
    rel="nofollow" 
    title="Aggiungi al Carrello" 
    data-id-product-attribute="0" 
    data-id-product="{{ product.id }}" 
    data-minimal_quantity="{{ product.qty }}">
    <span style="color: orange !important">
      <i class="icon-shopping-cart" aria-hidden="true"></i>
    </span>
  </a>
</div>

Errori comuni nella console #

Clerk.js registra molti errori nella console, che puoi utilizzare per risolvere problemi.

Cliccando sul link di errore otterrai ulteriori informazioni su cosa è andato storto, che puoi utilizzare per risolvere l’errore da solo o per inviare al nostro team di supporto che ti aiuterà. Di seguito troverai un elenco degli errori più comuni.

LogicalError: Contenuto sconosciuto #

Questo errore verrà visualizzato se il frammento che hai inserito fa riferimento a un Content che non esiste, nell’attributo data-template.

Per risolverlo, assicurati che il nome nel codice di incorporamento corrisponda a un blocco Content che hai creato in my.clerk.io.

Puoi cliccare su Modifica Contenuto per qualsiasi Content, per vedere quale dovrebbe essere il riferimento.

AuthenticationError: Endpoint API non valido #

Questo errore si verifica se hai utilizzato la classe clerk nel tuo HTML da qualche parte. Questa classe è riservata per l’uso con i nostri frammenti, poiché Clerk.js utilizza questa classe per identificare gli elementi da rendere.

Per risolverlo, assicurati di nominare la classe in modo diverso, come clerk-product.

ParsingError: Tipo di argomento prodotto non valido #

Questo errore significa che l’ID fornito per un prodotto ha un tipo o una sintassi errati.

Ad esempio, se i tuoi ID prodotto sono interi, devono esserlo anche nel codice di incorporamento. Inoltre, ricorda le parentesi attorno all’ID, per renderlo una lista.

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

ParsingError: Tipo di argomento categoria non valido #

Questo errore significa che l’ID fornito per una categoria ha un tipo o una sintassi errati.

Nella maggior parte dei casi, si verifica se il segnaposto nel codice di incorporamento della categoria non è stato sostituito da un ID reale:

<span 
  class="clerk" 
  data-template="@category-page" 
  data-category="INSERT_CATEGORY_ID">
</span>

L’output del codice dovrebbe contenere l’ID della categoria:

<span 
  class="clerk" 
  data-template="@category-page" 
  data-category="257">
</span>

Se hai copiato il frammento manualmente, assicurati di selezionare il tuo sistema di negozio nel Scegli la tua piattaforma a discesa prima di copiare il frammento. Cambierà quindi per includere la logica della tua piattaforma per selezionare l’ID categoria corretto.

Se la tua piattaforma non è elencata, devi aggiungere manualmente la logica per selezionare l’ID categoria corretto in base alla funzionalità del tuo negozio online.

AuthenticationError: Chiave API pubblica errata #

Questo errore verrà visualizzato se la chiave API pubblica che hai fornito non corrisponde a nessun account in Clerk.io.

Per risolvere questo, accedi a my.clerk.io, e vai a Impostazioni > Chiavi API. Qui puoi trovare la Chiave API Pubblica che puoi quindi aggiungere al tuo script di tracciamento Clerk.js direttamente nel codice, o nelle impostazioni per la tua integrazione, a seconda della tua piattaforma.

Inviare dati di vendita da un sistema POS/ERP #

Per alcuni negozi online, è rilevante caricare i dati di vendita da altri sistemi rispetto al negozio online effettivo, ad esempio se desideri ottimizzare l’algoritmo basato sulle vendite da un negozio fisico, o negozio B2B.

Clerk.io non differenzia tra ordini provenienti da varie fonti - purché tu possa fornire un ID, un timestamp e un elenco di prodotti acquistati, possono essere caricati su Clerk.io.

L’approccio consigliato è utilizzare l’ API CRUD poiché consente di automatizzare completamente il compito. Implementando queste chiamate API, puoi inviare i dati degli ordini direttamente al tuo Negozio in Clerk.io.

Basta creare una chiamata POST all’endpoint /orders nel tuo sistema ERP o negozio online, eseguire il lavoro a intervalli regolari, ad esempio una volta al mese, e sarai in grado di utilizzare gli ordini offline per potenziare le tue raccomandazioni online e i risultati di ricerca.

In alternativa, puoi caricare un file CSV manualmente, senza la necessità di codificare nulla. Puoi leggere di più sui file CSV qui.

Conversione di valuta #

Ci sono diversi modi di lavorare con la conversione di valuta in Clerk.io. Un modo semplice per farlo funzionare è delineato di seguito.

Inviare oggetti Prezzo #

Clerk ha bisogno di conoscere i prezzi di ciascun prodotto nelle diverse valute. Il modo più semplice per farlo è inviarli come un oggetto JSON codificato in stringa di prezzi formattati, con l’ISO della valuta come chiave, nel tuo Data Feed.

"products": [
  {
    "id": 1,
    "name": "Formaggio",
    "description": "Un bel pezzo di formaggio.",
    "price": 100,
    "list_price": 50,
    "categories": [25, 42],
    "image": "http://example.com/images/products/1.jpg",
    "url": "http://example.com/product/1",
    "on_sale": true,
    // Esempi di JSON codificati in stringa
    "prices_formatted": '{"USD":"$100", "EUR":"€87.70", "GBP":"£68.68"}',
    "list_prices_formatted": '{"USD":"$120", "EUR":"€97.70", "GBP":"£78.68"}'  
  },
  {
    "id": 2,
    "name": "Un chilo di noci",
    "description": "È un sacco di noci!",
    "price": 150,
    "categories": [1],
    "image": "http://example.com/images/products/2.jpg",
    "url": "http://example.com/product/2",
    "on_sale": false,
    // Esempio di JSON codificato in stringa
    "prices_formatted": '{"USD":"$150", "EUR":"€142", "GBP":"£120"}' ,
    "list_prices_formatted": '{"USD":"$150", "EUR":"€142", "GBP":"£120"}'
  }
]

Creare un Formatter #

In Clerk.js puoi definire funzioni JavaScript, che possono essere utilizzate con i tuoi Design.

Qui puoi definire una funzione che prende il tuo dizionario dei prezzi come argomento e restituisce il prezzo per una specifica valuta, basata sulla logica frontend di tua scelta.

Assicurati di sostituire currency con la valuta attualmente scelta dal frontend.

Clerk('config', {
  key: 'Your_API_Key',
  formatters: {
      currency_selector: function (price_list) {
      const currency = "EUR";
      price_groups_obj = JSON.parse(price_list)
        return price_groups_obj[currency];
      }
  }
});

Utilizzare il Formatter #

Dopo aver definito il formatter, può essere utilizzato nel tuo design con la sintassi sottostante:

<div class="price">
   <span class="price">
      {{ product.prices_formatted | currency_selector }}
   </span>
</div>

Prezzi specifici per cliente #

Per visualizzare prezzi completamente unici in base a quale cliente è connesso, crea un Evento in Clerk.io che inserisce il prezzo corretto prima che i prodotti siano renderizzati.

Eventi sono funzioni Javascript che vengono eseguite prima o dopo che Clerk.io mostra i prodotti.

Questo metodo è possibile se puoi cercare i prezzi dal tuo server, direttamente da una funzione Javascript, nel frontend basata su un ID prodotto e un ID cliente.

Per mostrare i prezzi individuali dei clienti, il codice dovrebbe essere eseguito subito dopo la risposta.

Di seguito è riportato un esempio di un semplice evento.

<span class="clerk" data-template="@home-page-popular"></span>

<script>
  Clerk('on', 'response', function(content, data) {
     console.log(data.result);
  });
</script>

La funzione prende l’argomento data che è l’intera risposta che Clerk.io restituisce dall’API.

Prezzi Individuali per Cliente #

Se hai bisogno di visualizzare prezzi completamente unici in base a quale cliente è connesso, devi impostare un Evento che inserisce il prezzo corretto dopo che i prodotti sono renderizzati.

Gli eventi sono funzioni Javascript che vengono eseguite prima o dopo che Clerk.io mostra i prodotti.

Questo approccio presuppone che tu possa cercare i prezzi dal tuo server con una chiamata AJAX nel frontend basata su ad esempio un ID prodotto e un ID cliente.

Il modo migliore è prima creare un contenitore di prezzo segnaposto nel tuo design, e poi sostituirlo con il prezzo restituito dalla tua chiamata AJAX.

Un esempio:

<div class="clerk-price-container">
   <span class="clerk-price">
      Caricamento prezzo...
   </span>
</div>

Puoi quindi utilizzare l’evento Clerk per attendere che i prodotti siano stati renderizzati, effettuare una richiesta al tuo server dei prezzi utilizzando l’ID prodotto e l’ID del cliente, prima di sostituirlo nell’HTML.

Ecco un esempio di come farlo:

<script>
  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;
      }
  })
  </script>

Il codice sopra presuppone che tu possa identificare un cliente connesso con INSERT_CUSTOMER_ID e che tu abbia una funzione come FETCH_PRICE_FROM_SERVER che restituisce il prezzo per il prodotto in base al cliente.

price_container viene utilizzato per mirare al prodotto giusto in base all’ID disponibile in data-clerk-product-id, che viene aggiunto a tutti i prodotti da Clerk.js.

Infine, sostituisce il testo interno, “Caricamento prezzo…” in questo esempio, con il prezzo restituito dalla tua chiamata AJAX.

Prezzi per Gruppi di Clienti #

L’impostazione dei prezzi per gruppi di clienti consiste in 4 passaggi:

1. Includere i vari prezzi nel data feed
2. Includere una variabile che recupera l’attuale ID gruppo cliente
3. Creare una funzione per recuperare il prezzo rilevante
4. Mostrare il prezzo nel Design

Includere Oggetti Prezzo #

Inizia aggiungendo un attributo a tutti i prodotti che contiene tutte le varie opzioni di prezzo, assicurandoti di correlare ogni prezzo a un particolare gruppo cliente.

Questo dovrebbe essere inviato come un oggetto JSON codificato in stringa. Ad esempio:

"customer_group_prices": "{\"GROUP1\":100,\"GROUP2\":202,\"GROUP3\":309}"

Variabile ID Cliente #

Aggiungi una variabile globale dinamica a Clerk.js che recupera l’ID gruppo cliente dell’attuale cliente e lo aggiunge come valore.

Il valore dell’ID Gruppo Cliente deve corrispondere alla chiave del suo prezzo corrispondente nel Data Feed. Ad esempio, un utente che dovrebbe vedere il prezzo per il gruppo 2, quindi l’ID dovrebbe essere “GROUP2”.

Clerk('config', {
  globals: {
    customer_group: "GROUP2"
  }
});

Recuperare il Prezzo #

Ora puoi creare un Formatter, che prende il customer_group come argomento e restituisce il prezzo rilevante.

Fallo scrivendo una funzione che recupera il prezzo dal gruppo cliente specifico come chiave nel dizionario dei prezzi basato sull’ID customer_group.

Aggiungi questo nella configurazione di Clerk.js. Di seguito è riportato un esempio chiamato getPrice:

Clerk('config', {
  globals: {
    customer_group: "GROUP2"
  },
  formatters: {
    getPrice: function (product) {
      const gid = window.Clerk._config.globals.customer_group;
      if (product.customer_group_prices) {
        const map = JSON.parse(product.customer_group_prices);
        if (map[gid]) {
            return map[gid];
        } else {
            return product.price;
        }
    } else {
        return product.price;
    }
    }
  }
});

Mostrare il Prezzo #

Quando il formatter final_price è stato creato, puoi nominarlo direttamente nel tuo Design, insieme all’elenco customer_group_prices che hai creato nel passaggio 1:

<li style="text-align: center; width: 180px;">
	<a href="{{ product.url }}">
		<img sre="{{ product.image }}" />
		{{ product.name }}
	</a>
	<div class="price">
		{{ product | getPrice }}
	</div>
</li>

Sincronizzazione HTTP Auth #

Spesso l’autenticazione HTTP viene utilizzata sui siti di staging per evitare visitatori indesiderati.

Questo, in molti casi, bloccherà anche l’importatore di Clerk e tipicamente visualizzerà un errore 401 Unauthorized nel registro di sincronizzazione.

Puoi facilmente verificare l’importatore inserendo le informazioni di autenticazione nell’URL di importazione come di seguito, in Data Sync su my.clerk.io:

http://USER:PASS@www.ewoksRus.com/JSONFEED

Nessun Ordine Tracciato #

Clerk.io ha bisogno di tracciare continuamente le vendite dal negozio online per mantenere i risultati aggiornati con il comportamento dei tuoi clienti. Tuttavia, alcune impostazioni in un negozio online possono causare il fallimento del tracciamento delle vendite.

Di seguito, puoi scoprire come risolvere il tracciamento delle vendite quando utilizzi un’impostazione Clerk.js e vedere quali sono i problemi e le soluzioni più comuni.

Prima di iniziare #

Assicurati di aver installato:

• Lo script di tracciamento Clerk.js su tutte le pagine
• Lo script di tracciamento delle vendite sulla tua pagina di successo ordine.

Questi sono necessari per tracciare le vendite in generale quando utilizzi un’impostazione Clerk.js.

Controlla i Log #

Nella maggior parte dei casi, il tracciamento delle vendite fallisce a causa di errori negli ID visitatori o negli ID prodotto della chiamata di vendita inviata a Clerk dopo che un acquisto è stato completato. Per risolvere questo, dovrai effettuare un ordine di prova.

Tuttavia, in alcuni casi potrebbe essere correlato allo script di tracciamento delle vendite stesso e può essere risolto guardando i log in my.clerk.io > Data > Logs.

Se il tracciamento delle vendite fallisce a causa di un errore nel tuo script, spesso sarai in grado di vedere l’errore in questa pagina. Clicca Dettagli per vedere di più.

Se non riesci a vedere errori nei log, il modo più semplice per identificare altri problemi di tracciamento delle vendite è effettuare un ordine di prova.

Debugging Ordine di Prova #

In questo esempio, utilizziamo Chrome per mostrare come eseguire il debug del tracciamento delle vendite con un ordine di prova, ma altri browser hanno funzionalità simili.

1. Sul tuo negozio online, metti un paio di prodotti nel carrello.
2. Procedi al Checkout.
3. Prima di effettuare l’ordine, apri la Console del tuo browser.
4. Trova Network e cerca " clerk".
5. Effettua l’ordine, in modo da vedere la pagina di conferma ordine.
6. Clicca sulla chiamata che inizia con sale (normalmente sale?key=…).

Qui vedrai i dati che vengono inviati e ricevuti dall’endpoint API di tracciamento delle vendite. Clicca su Anteprima per identificare eventuali errori che possono causare il mancato tracciamento delle vendite.

Di seguito sono riportati errori comuni associati al tracciamento delle vendite.

Sintassi non valida nell’argomento: prodotti #

Questo errore si verifica se gli ID prodotto che invii hanno una sintassi errata. Gli errori più comuni sono:

• Gli ID prodotto sono codificati in stringa nel tracciamento delle vendite, ma stai utilizzando interi in Clerk.io o viceversa.
• L’elenco degli ID prodotto contiene caratteri di formattazione testo invece di puro JSON: "products":\[\\"id"\\:\\"123-m"\\\].

Argomento X mancante #

Questo significa che non stai inviando tutti i dati di cui Clerk.io ha bisogno per tracciare la vendita.

Assicurati di includere tutti i data attributes nel tracciamento delle vendite.

Nessuna chiamata effettuata #

Se non riesci a vedere la chiamata a sale anche con entrambi gli script installati, allora qualcosa ha causato il caricamento errato dello script Clerk.js. Testa questo seguendo questi passaggi:

1. Apri le Impostazioni di rete nel browser
2. Digita “Clerk”.
3. Se Clerk.js non è stato caricato correttamente, vedrai un ReferenceError:

Uncaught ReferenceError: Clerk is not defined

Se questo è il caso, devi controllare la tua impostazione Clerk.js:

• Assicurati che Clerk.js sia installato su tutte le pagine.
• Assicurati che non sia bloccato da altre funzionalità Javascript.

Nessun Impatto di Clerk #

Se tracci le vendite con successo in my.clerk.io, ma nessuna di esse appare come impattata da Clerk.io, potresti avere un errore nella tua impostazione di tracciamento visitatori / tracciamento clic.

Inizia assicurandoti che il tracciamento visitatori funzioni, facendo quanto segue:

1. Clicca su qualsiasi prodotto tramite la Ricerca o le Raccomandazioni di Clerk.io
2. Procedi a effettuare un ordine contenente questo prodotto
3. Accedi a my.clerk.io e vai a Dettagli Ordine
4. Aspetta che l’Ordine appaia.

Se il tracciamento visitatori funziona, vedrai il valore e l’impatto del prodotto che hai aggiunto tramite Clerk.io, in Ordini Tracciati:

Se non vedi alcun valore aggiunto nell’ordine che hai effettuato, le sezioni seguenti mostrano errori comuni che potrebbero causare questo.

Impostazioni API #

Se hai impostato Clerk.io con un’integrazione personalizzata direttamente con l’API, devi attivare attivamente il tracciamento visitatori. Leggi come farlo in questo articolo API.

ID Prodotto Errati #

Per il tracciamento visitatori per funzionare, il tracciamento dei clic e delle vendite deve tracciare gli stessi ID prodotto di quelli che ricevi nell’importatore. Di solito, se questo non funziona è perché stai tracciando gli ID variante invece degli ID genitore o il SKU invece dell’ID.

Per verificare se questo è il problema, fai quanto segue:

1. In my.clerk.io, vai a Data > Orders e clicca sull’ID di un ordine che hai effettuato.
2. Se Clerk.io non può identificare il prodotto, vedrai un ID e un immagine segnaposto:
3. Vai a Data > Products e cerca il nome del prodotto che hai aggiunto. Qui sarai in grado di vedere l’ID previsto per il prodotto.

Usa questo per configurare il tuo tracciamento delle vendite per utilizzare gli ID prodotto corretti.

Modifiche all’ID Visitatore #

Clerk.io utilizza un ID visitatore per identificare ciascuna sessione individuale, inclusi i prodotti che cliccano e acquistano. A causa di ciò, gli ID dovrebbero rimanere gli stessi per tutta la durata della sessione e preferibilmente anche attraverso più sessioni.

Questo ID visitatore viene creato automaticamente quando utilizzi Clerk.js per effettuare l’impostazione, ma se utilizzi un’impostazione API, o personalizzi i tuoi ID visitatori, potresti cambiarlo accidentalmente.

Questo errore è raro, ma puoi controllare l’ID visitatore seguendo questi passaggi:

1. Apri le tue Impostazioni di rete nel browser e restringi i risultati a “clerk”.
2. Inizia controllando eventuali chiamate undefined che sono correlate alla ricerca o alle raccomandazioni.
3. In payload puoi controllare l’attuale ID Visitante. Sarai in grado di farlo per tutte le chiamate associate a Clerk.io
4. Procedi a cliccare sul prodotto e a effettuare un ordine con questo prodotto.
5. Nella pagina di Successo Ordine, controlla di nuovo la tua rete e trova la chiamata a sale?.
6. Assicurati che visitor nel payload, corrisponda all’ID Visitante che hai visto nel passaggio 3.

Se gli ID visitor non corrispondono, devi scoprire perché cambiano. Una causa comune per il cambiamento degli ID visitatori potrebbe essere se rigeneri gli ID per ogni nuova pagina che viene caricata. Aggiorna il tuo codice per utilizzare lo stesso ID visitatore per ogni pagina.

Aggiornare a Clerk.js 2 #

Clerk.js 2 è una versione più veloce e molto più flessibile della nostra libreria JavaScript che rende l’installazione di Clerk.io su qualsiasi negozio online un gioco da ragazzi.

Tuttavia, poiché le due versioni funzionano in modo leggermente diverso, devi seguire questi passaggi per aggiornare con successo.

Le due principali differenze in Clerk.js 2 sono:

• I Design in my.clerk.io utilizzano il Liquid, ma possono anche essere facilmente creati utilizzando l’Editor di Design.

• Lo script deve essere inserito appena prima del nel template del tuo negozio online.

Creare Design #

Poiché Clerk.js 2 ha un approccio diverso ai Design, devi crearne di nuovi.

Puoi creare i tuoi design Clerk.js 2 sia ripetendoli nell’ Editor di Design, sia convertendo i tuoi vecchi design in codice Liquid, come spiegato nella guida sottostante. Di seguito è riportata una descrizione su come convertire i tuoi vecchi design in codice Liquid.

Opzione 1: Design dell’Editor #

1. Vai a my.clerk.io > Recommendations/Search > Designs > New Design.
2. Seleziona un tipo di design diverso da Blank e dagli un nome. Ti consigliamo di aggiungere “V2” in modo che sia ovvio che stai utilizzando i design Clerk.js 2 per questo.
3. Nell’ Editor di Design, clicca su uno degli elementi esistenti come il nome, l’immagine, il pulsante, ecc. per modificarlo, o aggiungi nuovi elementi al Design.
4. Clicca su Pubblica Design quando hai finito e vai a Passo 2 nella guida.
5. Infine, vai a Recommendations/Search > Content e cambia il tuo contenuto Clerk.io per utilizzare il tuo nuovo Design, poi clicca su Update Content.
6. Questo farà sì che temporaneamente non vengano visualizzati nel tuo webshop, fino a quando non avrai inserito Clerk.js 2 come descritto più avanti in questa guida.

Opzione 2: Conversione dei Design #

Poiché Clerk.js 2 utilizza il più flessibile linguaggio di template Liquid, devi convertire i Design in questo linguaggio.

1. Inizia andando a my.clerk.io >Recommendations/Search > Designs > New Design.
2. Seleziona Blank > Code e dagli un nome. Ti consigliamo di aggiungere “V2” in modo che sia ovvio che stai utilizzando i design Clerk.js 2 per questo.
3. Clicca su Crea Design.
4. Questo ti darà un design vuoto con HTML e CSS del prodotto che puoi utilizzare.
5. Torna alla panoramica dei design e clicca su Modifica Design per il tuo design Clerk.js 1. Ti consigliamo di farlo in una nuova scheda così puoi facilmente copiare il codice.
6. Ora devi copiare il vecchio design Clerk.js 1 nel tuo nuovo design Clerk.js 2.
   • Noterai che non c’è Codice Contenitore nel tuo nuovo.
   • Questo perché Liquid utilizza cicli for per renderizzare tutti i prodotti.
   • Copia il tuo vecchio HTML del Prodotto all’interno del ciclo for, il tuo vecchio Codice Contenitore intorno ad esso e copia anche il CSS.
7. Converti il Design nella sintassi di Liquid. La principale differenza è che i vecchi Design utilizzavano la sintassi {{ formatter attribute }} mentre la sintassi v2 è {{ product.attribute | formatter }}.
8. Controlla tutti i tuoi attributi e cambiali nel nuovo formato.
9. Se stai utilizzando dichiarazioni {{#if}} o {{#is}}, queste devono essere convertite anche. Usa la sintassi {% if product.attribute %} {% else %} {% endif %}.
10. Elimina id="{{ $id }}" e la classe :target dal codice contenitore nella versione Clerk.js 2 poiché non sono più supportati.
11. Di seguito è riportato un esempio di un design Clerk.js 1 e la versione completamente convertita:

Design Clerk.js 1 #

// HTML del Prodotto
<li class="clerk-product">
    <a href="{{ url }}">
        <img src="{{ image }}" />
        <div class="clerk-product-name">{{ name }}</div>
        <div class="clerk-price-wrapper">
            {{#if list_price}}
                <div class="clerk-old-price">
                    <s>Prezzo {{ money_eu list_price }}</s>
                </div>
                <span class="clerk-new-price">Prezzo {{ money_eu price }}</span>
            {{else}}
                <div class="clerk-product-price">Prezzo {{ money_eu price }}</div>
            {{/if}}
        </div>
    </a>
    <div class="clerk-cta-button btn button">Acquista Ora</div>
</li>

// Codice Contenitore
<h2>{{ headline }}</h2>
<ul id="{{ $id }}" class=":target clerk-slider"></ul>

<!-- Questo codice crea lo slider tramite il suo ID. -->
<script type="text/javascript">
    Clerk.ui.slider("{{ id }}").init();
</script>

Design Clerk.js 2 #

<h2>{{ headline }}</h2>

<ul class="clerk-slider">
    {% for product in products %}
    <li class="clerk-product">
        <a href="{{ product.url }}">
            <img src="{{ product.image }}" />
            <div class="clerk-product-name">{{ product.name }}</div>
            <div class="clerk-price-wrapper">
                {% if product.list_price %}
                    <span class="clerk-old-price"><s>Prezzo {{ product.list_price | money_eu }}</s></span>
                    <span class="clerk-new-price">Prezzo {{ product.price | money_eu }}</span>
                {% else %}
                    <div class="clerk-product-price">Prezzo {{ product.price | money_eu }}</div>
                {% endif %}
            </div>
            <div class="clerk-cta-button btn button">Acquista Ora</div>
        </a>
    </li>
    {% endfor %}
</ul>

13. Ora clicca su Aggiorna Design per salvare le modifiche.
14. Infine, vai a Recommendations/Search > Content e cambia il tuo blocco di contenuto per utilizzare il tuo nuovo Design.
15. Clicca su Aggiorna Contenuto. Questo farà sì che temporaneamente non vengano visualizzati nel tuo webshop, fino a quando non avrai completato Passo 2. Scegli il nuovo Design per tutto il Contenuto che deve essere aggiornato.

Sostituisci lo script #

1. Inizia localizzando il file di template che viene utilizzato per mostrare tutte le pagine del webshop, e dove si trova lo script originale di Clerk.js vicino al fondo.
2. Rimuovi il vecchio script di Clerk.js dal file. Dovrebbe apparire qualcosa del genere:

<!-- Inizio dello strumento di personalizzazione e-commerce Clerk.io - www.clerk.io -->
<script type="text/javascript">
    window.clerkAsyncInit = function() {
        Clerk.config({
            key: 'public_api_key'
        });
    };
    (function(){
        var e = document.createElement('script'); e.type='text/javascript'; e.async = true;
        e.src = document.location.protocol + '//api.clerk.io/static/clerk.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
    })();
</script>
<!-- Fine dello strumento di personalizzazione e-commerce Clerk.io - www.clerk.io -->

3. Vai a my.clerk.io > Settings > Tracking Code. Questo contiene il codice Clerk.js 2.
4. Copia questo codice, inseriscilo appena prima del tag </head> nel template, poi salvalo.

Congratulazioni! Ora stai utilizzando la configurazione molto migliorata di Clerk.js 2! Puoi vedere la documentazione completa per Clerk.js 2 qui.

Gestione di require.js #

Questa sezione si applica solo quando si utilizza Clerk.js 1.

In alcune configurazioni, Require.js impedisce il caricamento di Clerk.js, il che significa che non verranno mostrati slider o risultati di ricerca. Quando ciò accade, verrà mostrato il seguente errore nella tua console:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi gli approcci richiedono di apportare modifiche allo script di tracciamento, che hai inserito in fondo a tutte le pagine.

Includere “clerk” in Require.js #

L’approccio migliore è cercare di far riconoscere a Require.js Clerk.io.

Puoi farlo inserendo require(\['clerk'\], function() {}); in fondo allo script di tracciamento:

Ignorare Require.js #

Se la soluzione sopra non funziona, è possibile ignorare Require.js.

Puoi farlo inserendo window.__clerk_ignore_requirejs = true; in cima allo script di tracciamento:

Dopo aver utilizzato uno di questi approcci, Require.js sarà ora compatibile con Clerk.io.