FAQ

App single-page (SPA) #

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

Quando una pagina viene caricata per la prima volta, la libreria Clerk.js automaticamente attiva una funzione per rendere tutti i blocchi Content 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 questo, è 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. 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: 'INSERT_PUBLIC_API_KEY'
    });
</script>
<!-- Fine dello strumento di personalizzazione E-commerce di Clerk.io - www.clerk.io -->

Controllo del Rendering #

Per impostazione predefinita, Clerk.js rende qualsiasi elemento che ha la classe clerk, indipendentemente dal fatto che venga inserito durante il caricamento iniziale della pagina o quando il DOM muta. Puoi controllare il tempo di rendering 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, segui 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 Content con i tuoi selettori personalizzati dopo la prima volta che lo rendi.

Impatto sulla 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 è solo di 37,5kb di dimensione, 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 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.

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 semplicemente 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 minimizzare le 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 (insieme a Clerk.io) è utilizzata da Google Analytics, Facebook, Trustpilot e molti altri.

Impatto CLS #

Il Cumulative Layout Shift (CLS) può avere un impatto negativo sulla SEO e sull’esperienza utente quando il contenuto iniettato dinamicamente sposta gli 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 prevenire lo spostamento del contenuto, è necessario riservare un segnaposto per le raccomandazioni Clerk prima che Clerk.js le inietti. Per fare ciò, 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 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 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 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 referenziato in data-id-product, e la quantità prodotto è referenziata in .data-minimal_quantity.

Questi valori devono essere sostituiti con tag Liquid nel Design in modo che gli ID prodotto e le quantità 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 risolvere problemi.

Cliccando sul link dell’errore otterrai maggiori 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à mostrato 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 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 gli ID prodotto sono interi, devono essere tali 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 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 non corretta #

Questo errore verrà mostrato 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 oltre al negozio online stesso, 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 il CRUD API 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 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 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 loro 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",
    "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",
    "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 Designs.

Qui puoi definire una funzione che prende il tuo dizionario prezzi come argomento e restituisce il prezzo per una specifica valuta, in base alla 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 in base a 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.

Esempio di 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 in base a 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 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 fare questo:

<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 pertinente
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 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"
  }
});

Recuperare il Prezzo #

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

Fallo scrivendo una funzione che recupera il prezzo dal gruppo cliente specifico come chiave nel dizionario prezzi in base all’ID customer_group.

Aggiungi questo nella configurazione di Clerk.js. Di seguito è 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 è utilizzata sui siti di staging per evitare visitatori indesiderati.

Questo, in molti casi, bloccherà anche l’importatore di Clerk e tipicamente mostrerà 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 dell’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 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 esaminato controllando 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. Clicca 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 dell’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 dell’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 del testo invece di puro JSON: "products":\[\\"id"\\:\\"123-m"\\\].

Argomento mancante X #

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 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 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 di 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 con successo le vendite 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. Clicca 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 dell’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 dei 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 controllare 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 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 delle vendite per utilizzare gli ID prodotto corretti.

Cambiamenti negli ID Visitatori #

Clerk.io utilizza un ID visitatore per identificare ciascuna sessione individuale, inclusi i prodotti su cui cliccano e acquistano. A causa di questo, gli ID dovrebbero rimanere gli stessi per almeno 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 cambiarli accidentalmente.

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

1. Apri le tue Impostazioni 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. Sulla pagina di Successo dell’Ordine, controlla di nuovo le tue Impostazioni 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.

Aggiornamento 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 completare con successo l’aggiornamento.

Le due principali differenze in Clerk.js 2 sono:

• I Designs 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 Designs #

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

Puoi creare i tuoi Designs Clerk.js 2 sia ripetendoli nell’ Editor di Design, sia convertendo il tuo vecchio codice Designs in Liquid, come spiega la guida sottostante. Di seguito è riportata una descrizione su come convertire i tuoi vecchi Designs in codice in Liquid.

Opzione 1: Design Editor Designs #

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 nome, immagine, 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 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 linguaggio di template più flessibile Liquid, è necessario 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. 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 dentro il for-loop, il tuo vecchio Container Code 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 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 container 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>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>

// 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>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 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 farà sì che temporaneamente non vengano visualizzati nel tuo webshop, fino a quando non avrai completato il 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 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 visualizzati slider o risultati di ricerca. Quando ciò accade, verrà visualizzato il seguente errore nella 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 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.