FAQ

App single-page (SPA) #

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

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

Tuttavia, per le app single-page 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.

Includi Clerk.js #

Clerk.js deve essere caricato solo una volta, quando il sito viene caricato inizialmente. Dopo questo, la libreria sarà disponibile per tutta la sessione. Includilo 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: 'INSERISCI_CHIAVE_API_PUBBLICA'
    });
</script>
<!-- Fine dello strumento di personalizzazione E-commerce di Clerk.io - www.clerk.io -->

Controlla 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 alla 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 sulla Velocità della Pagina #

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 influisce sulle 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 attraenti.

Per ridurre 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 Sfrutta la cache del browser.

Lo scopo di Clerk.js è rendere super semplice inserire i risultati da Clerk.io in qualsiasi sito web. Clerk.js contiene molte funzionalità per gestire il tracciamento e i componenti UI come Ricerca Istantanea, cursori, 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ù a lungo è il tempo di cache, più a lungo ci vorrà affinché tutti abbiano accesso alle funzionalità più recenti.

L’importante è che gli utenti finali debbano scaricare Clerk.js una sola volta quando sono disponibili nuove funzionalità.

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ò influire negativamente su SEO e sull’esperienza dell’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ù sul 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 evitare che il contenuto si sposti, è 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 funzioni callback per gestire la risposta come meglio credi. Le funzioni accettano 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 capisci 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 fare questo 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. Più 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 dovrebbero 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 finale Aggiungi al carrello 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 eseguire il debug dei problemi.

Facendo clic sul link dell’errore otterrai ulteriori informazioni su cosa è andato storto, che puoi utilizzare per eseguire il debug dell’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 Contenuto che non esiste, nell’attributo data-template.

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

Puoi fare clic su Modifica Contenuto per qualsiasi Contenuto, 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 un altro modo, 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 un elenco.

<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="INSERISCI_ID_CATEGORIA">
</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 menu 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 in base alle 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 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 più modi di lavorare con la conversione di valuta in Clerk.io. Un modo semplice per farlo funzionare è delineato di seguito.

Inviare Oggetti Prezzo #

Clerk deve conoscere i prezzi di ciascun prodotto nelle diverse valute. Il modo più semplice per farlo è inviarli come un oggetto JSON codificato come 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",
    // Esempio di JSON codificato come stringa
    "prices_formatted": '{"USD":"$100", "EUR":"€87.70", "GBP":"£68.68"}' 
  },
  {
    "id": 2,
    "name": "Un chilo di noci",
    "description": "Sono molte noci!",
    "price": 150,
    "categories": [1],
    "image": "http://example.com/images/products/2.jpg",
    "url": "http://example.com/product/2",
    // Esempio di JSON codificato come stringa
    "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 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 vengano 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 accetta 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 stati 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, fare 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 = INSERISCI_ID_CLIENTE;
  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 INSERISCI_ID_CLIENTE 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 ciascun prezzo a un particolare gruppo cliente.

Questo dovrebbe essere inviato come un oggetto JSON codificato come 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 essere equivalente 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"
  }
});

Recupera 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;
    }
    }
  }
});

Mostra 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 normalmente visualizzerà un errore 401 Non autorizzato 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 deve monitorare 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 eseguire il debug del 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 vendite sulla tua pagina di successo ordine.

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

Controlla i Registri #

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 che viene inviata a Clerk dopo che un acquisto è stato completato. Per eseguire il debug di questo, dovrai effettuare un ordine di prova.

Tuttavia, in alcuni casi potrebbe essere correlato allo script di tracciamento vendite stesso e può essere eseguito il debug guardando i registri 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. Fai clic su Dettagli per vedere di più.

Se non riesci a vedere errori nei registri, 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. Fai clic sulla chiamata che inizia con sale (normalmente sale?key=…).

Qui vedrai i dati che vengono inviati e ricevuti dall’endpoint API di tracciamento vendite. Fai clic su Anteprima per identificare eventuali errori che possono causare la mancata registrazione 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 come stringa nel tracciamento 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 gli attributi di dati necessari nel tracciamento 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 la Console nel tuo 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 Clerk #

Se tracci le vendite con successo in my.clerk.io, ma nessuna di esse appare come influenzata 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. Fai clic su qualsiasi prodotto tramite Ricerca o 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 #

Affinché il tracciamento visitatori funzioni, il tracciamento dei clic e delle vendite deve monitorare 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 controllare se questo è il problema, fai quanto segue:

1. In my.clerk.io, vai a Data > Orders e fai clic sull’ID di un ordine che hai effettuato.
2. Se Clerk.io non riesce a identificare il prodotto, vedrai un ID e un segnaposto immagine:
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 vendite per utilizzare gli ID prodotto corretti.

Modifiche all’ID Visitatore #

Clerk.io utilizza un ID visitatore per identificare ogni singola sessione, inclusi i prodotti che cliccano e acquistano. A causa di ciò, gli ID dovrebbero rimanere gli stessi per l’intera 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 impostazioni Network nel browser e restringi i risultati a “clerk”.
2. Inizia controllando eventuali chiamate undefined che sono correlate a ricerca o raccomandazioni.
3. In payload puoi controllare l’attuale ID Visitatore. 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 il tuo Network e trova la chiamata a sale?.
6. Assicurati che visitor nel payload, corrisponda all’ID Visitatore 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.

Aggiorna 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.

Crea 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 il tuo vecchio codice Design in Liquid, come spiega la guida sottostante.

Di seguito è riportata una descrizione su come convertire i tuoi vecchi Designs in Liquid.

Opzione 1: Designs dell’Editor di Design #

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, fai clic su uno degli elementi esistenti come il nome, l’immagine, il pulsante, ecc. per modificarlo, oppure aggiungi nuovi elementi al Design.
4. Fai clic 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, quindi fai clic su Update Content.
6. Questo causerà temporaneamente che 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 Designs #

Poiché Clerk.js 2 utilizza il linguaggio di template più flessibile template language Liquid, è necessario convertire i Designs 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. Fai clic su Crea Design.
4. Questo ti darà un design vuoto con HTML e CSS del prodotto che puoi utilizzare.
5. Torna alla panoramica del design e fai clic su Modifica Design per il tuo Design Clerk.js 1. Ti consigliamo di farlo in una nuova scheda in modo da poter copiare facilmente il codice.
6. Ora devi copiare il vecchio Design Clerk.js 1 nel tuo nuovo Design Clerk.js 2.
   • Noterai che non c’è nessun Container Code nel tuo nuovo.
   • Questo perché Liquid utilizza for loops per rendere tutti i prodotti.
   • Copia il tuo vecchio Product HTML inside the for-loop, il tuo vecchio Container Code around esso e copia anche il CSS.
7. Converti il Design nella sintassi di Liquid. La principale differenza è che i vecchi Designs utilizzavano la sintassi {{ formatter attribute }} mentre la sintassi della v2 è {{ product.attribute | formatter }}.
8. Controlla tutti i tuoi attributi e cambiali nel nuovo formato.
9. Se stai utilizzando le dichiarazioni {{#if}} o {{#is}}, anche queste devono essere convertite. Usa la sintassi {% if product.attribute %} {% else %} {% endif %}.
10. Elimina id="{{ $id }}" e la classe :target dal codice del 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 #

// Product HTML
<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>Price {{ money_eu list_price }}</s>
                </div>
                <span class="clerk-new-price">Price {{ money_eu price }}</span>
            {{else}}
                <div class="clerk-product-price">Price {{ money_eu price }}</div>
            {{/if}}
        </div>
    </a>
    <div class="clerk-cta-button btn button">Buy Now</div>
</li>

// Container Code
<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>Price {{ product.list_price | money_eu }}</s></span>
                    <span class="clerk-new-price">Price {{ product.price | money_eu }}</span>
                {% else %}
                    <div class="clerk-product-price">Price {{ product.price | money_eu }}</div>
                {% endif %}
            </div>
            <div class="clerk-cta-button btn button">Buy Now</div>
        </a>
    </li>
    {% endfor %}
</ul>

13. Ora fai clic 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. Fai clic su Aggiorna Contenuto. Questo causerà temporaneamente che 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 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 di 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 di 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, quindi salvalo.

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

Gestire require.js #

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

In alcune configurazioni, Require.js impedisce a Clerk.js di caricarsi, il che significa che non verranno mostrati slider o risultati di ricerca. Quando ciò accade, verrà visualizzato 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 tracking-script, che hai inserito in fondo a tutte le pagine.

Includere “clerk” in Require.js #

Il miglior approccio è cercare di far riconoscere Require.js a 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.