Qualsiasi (webshop)

FAQ

Risposte alle domande frequenti per integrazioni personalizzate

Problemi con la tua integrazione personalizzata? Questa FAQ copre i problemi più comuni e le relative soluzioni, dalle single-page app al tracciamento delle vendite.

Single-page app #

Queste vengono anche chiamate 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 avvia automaticamente una funzione per rendere tutti i blocchi Element su quella pagina.

Tuttavia, per le single-page app che utilizzano framework come vue.js o next.js, le pagine vengono rese con JavaScript invece che con un normale caricamento della pagina.

Per questo motivo, è necessario controllare il rendering con Clerk.js per adattarlo a come vengono caricate 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 durante tutta la sessione.

Inseriscilo subito prima di </head> nel tuo HTML:

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

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

Controllo del rendering #

Per impostazione predefinita, Clerk.js renderizza tutti gli elementi che hanno la classe clerk, indipendentemente dal fatto che sia stato inserito durante il caricamento iniziale della pagina o quando il DOM viene mutato.

Puoi controllare il momento inserendo l’elemento quando è pronto per essere renderizzato.

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

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

Aggiungi lo snippet Clerk all’HTML con un selettore univoco che puoi targettizzare.
Esegui Clerk("content", "SELECTOR") per renderizzarlo.

Quando il visitatore lascia la pagina, distruggi lo snippet e renderizzalo di nuovo se il visitatore ritorna sulla stessa pagina.

Questo serve per assicurare che Clerk.js non consideri lo snippet come già renderizzato, facendo sì che non venga visualizzato.

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 gli Element con i tuoi selettori personalizzati dopo la prima volta che lo rendi.

Impatto su Pagespeed #

L’aggiunta di uno strumento esterno come Clerk.js aumenterà il tempo necessario per caricare il sito, ma è trascurabile rispetto alle conversioni aggiuntive che offrirà.

Di seguito puoi vedere come influisce sulle prestazioni del sito.

Performance #

La libreria Clerk.js pesa solo 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 renderizza i contenuti.

Un aumento del tempo di caricamento di una pagina deriva spesso dal caricamento di più immagini del solito, poiché i risultati di search e recommendations di Clerk funzionano meglio se sono visivamente accattivanti.

Per ridurre il tempo di caricamento extra, consigliamo di usare immagini in formato webp che abbiano una risoluzione uguale alle dimensioni con cui sono visualizzate negli elementi Clerk.

Per esempio, se le immagini nelle recommendations hanno una risoluzione di 400x400px in visualizzazione 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 sito, potresti vedere Clerk.js elencato sotto Leverage browser caching.

Lo scopo di Clerk.js è rendere estremamente semplice inserire i risultati di Clerk 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 miglioriamo quelle esistenti, vengono incluse in Clerk.js e devono essere scaricate dall’utente finale per poterle utilizzare.

Impostando una scadenza della cache di 60 minuti, quando rilasciamo nuove funzionalità saranno disponibili per tutti entro un massimo di 60 minuti.

Più lungo è il tempo di cache, più tempo ci vorrà perché tutti possano accedere alle nuove funzionalità.

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

La scadenza di 60 minuti della cache significa semplicemente che il browser dell’utente finale controllerà con Clerk ogni 60 minuti.

Se non sono stati apportati cambiamenti a Clerk.js, non verrà scaricato nulla.

Il tempo di scadenza della cache di 60 minuti è quindi un compromesso tra la minimizzazione delle richieste web e la visualizzazione di nuove funzionalità e miglioramenti.

La maggior parte delle sessioni dura meno 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) è usata anche da Google Analytics, Facebook, Trustpilot e molti altri.

Impatto CLS #

Il Cumulative Layout Shift (CLS) può influire negativamente sulla SEO e sull’esperienza utente quando i contenuti iniettati dinamicamente spostano gli elementi su una pagina.

In alcuni casi, tra i vari 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 above the fold.

Per evitare che i contenuti causino spostamenti, bisogna riservare uno spazio a recommendations di Clerk prima che Clerk.js li inietti.

Per farlo, va aggiunta un’altezza minima in base all’altezza prevista del contenuto.

Esempio di codice:

.clerk-slider-wrapper {
    min-height: 300px; /* Da adattare in base all’altezza prevista */
    width: 100%;
}

Effettuare chiamate API #

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

Questa funzione accetta 3 argomenti:

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

Requests #

Di seguito uno script di esempio 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]
  }
);

Callbacks #

Quando effettui chiamate API puoi usare le funzioni callback per gestire la risposta come preferisci.

Le funzioni ricevono response come argomento che contiene tutti i dati restituiti dall’API.

Di seguito un esempio che crea una lista di elementi HTML con link alle categorie che corrispondono alla query “men”.

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 = 'Related Categories';
          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 su ogni piattaforma e la funzionalità può cambiare in base ai plugin che usi.

Poiché i design di Clerk sono composti da HTML & CSS, di solito puoi aggiungere questa funzionalità se capisci come funziona sul tuo sito.

Approccio generale #

Alcuni pulsanti add-to-cart richiedono l’esecuzione di JavaScript per funzionare.

In questi casi, puoi aggiungere la funzionalità al metodo cart esistente di Clerk.

Scopri come farlo nei nostri developer docs qui.

Ispeziona il pulsante add-to-cart per identificare il codice associato, per esempio su una pagina categoria.

Il codice sarà solitamente un elemento <div> o button.

Copia tutto l’HTML del pulsante.

Copia e incolla questo codice nel tuo Design.

Ora devi identificare le variabili nel codice.

Il più delle volte, devi trovare dove il codice usa:

ID prodotto
Quantità prodotto

Sostituisci i valori relativi all’ID prodotto con le variabili Liquid per questi dati.

L’ID sarà sempre {{ product.id }} e la quantità può variare a seconda di come invii i dati.

Per questo esempio potrebbe essere {{ product.qty }}.

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

Esempio #

Il pulsante add-to-cart sotto è un <div> che ha la classe button-container:

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

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

Questi valori vanno sostituiti con i tag Liquid nel Design affinché siano usati correttamente gli ID prodotto e le quantità nell’output HTML.

Con queste modifiche, il pulsante add-to-cart finale sarà 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="Add to Cart" 
    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 console #

Clerk.js registra molti errori nella console, che puoi utilizzare per effettuare il debug dei problemi.

Cliccando sul link dell’errore avrai ulteriori informazioni su cosa non ha funzionato, che potrai usare per risolvere il problema da solo o per inviarle al nostro support team che ti aiuterà.

Qui sotto trovi una lista degli errori più comuni.

Contenuto sconosciuto #

Questo errore viene visualizzato se lo snippet inserito fa riferimento a un Element che non esiste, nell’attributo data-template.

Per risolvere, assicurati che il nome nel codice di embed corrisponda a un blocco Element che hai creato in my.clerk.io.

Puoi cliccare su Edit Element per ogni Element per vedere quale deve essere il riferimento.

Endpoint API non valido #

Questo errore viene fuori se hai utilizzato la classe clerk nel tuo HTML da qualche parte.

Questa classe è riservata all’uso con i nostri snippet, poiché Clerk.js usa questa classe per identificare gli elementi da renderizzare.

Per risolverlo, assicurati di dare un altro nome alla classe, come clerk-product.

Argomento prodotto non valido #

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

Ad esempio, se i tuoi ID prodotto sono interi, devono esserlo anche nel codice di embed.

Ricorda anche le parentesi attorno all’ID, per renderlo una lista.

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

Argomento categoria non valido #

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

Di solito succede se il placeholder nel codice embed categoria non è stato sostituito da un vero ID:

<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 lo snippet manualmente, assicurati di selezionare il sistema shop nel menu a discesa Choose your platform prima di copiare lo snippet.

Così cambierà per includere la logica del tuo sistema per selezionare l’ID categoria corretto.

Se la tua piattaforma non è inclusa, dovrai aggiungere manualmente la logica per selezionare l’ID corretto categorie in base alla funzionalità del tuo shop online.

API key errata #

Questo errore verrà mostrato se la public API key fornita non corrisponde ad alcun account su Clerk.

Per risolvere, accedi a my.clerk.io e vai su Developers > API Keys.

Qui troverai la Public API Key che puoi poi aggiungere al tuo script di tracking Clerk.js direttamente nel codice oppure nelle impostazioni per la tua integrazione, a seconda della piattaforma.

Dati vendite da POS/ERP #

Per alcuni shop online, può essere utile caricare dati di vendita da altri sistemi diversi dall’e-commerce.

Ad esempio, se vuoi ottimizzare l’algoritmo sulla base delle vendite di un negozio fisico o negozio B2B.

Clerk non distingue tra ordini provenienti da varie fonti: se puoi fornire un ID, timestamp e una lista di prodotti acquistati, possono essere inviati a Clerk.

L’approccio consigliato è usare la CRUD API perché permette di automatizzare completamente il compito.

Implementando queste chiamate API, puoi inviare i dati ordini direttamente nel tuo Store su Clerk.

Crea semplicemente una chiamata POST allo /orders endpoint nel tuo sistema ERP o shop online, esegui il job a intervalli regolari, ad esempio una volta al mese, e potrai usare ordini offline per potenziare recommendations e search online.

In alternativa, puoi caricare un file CSV manualmente, senza la necessità di scrivere codice.

Leggi di più sui file CSV qui.

Conversione valuta #

Esistono diversi modi per lavorare con la conversione valuta in Clerk.

Un modo semplice è illustrato qui sotto.

Traduzione valute #

Se i visitatori utilizzano Google Translate sul tuo shop online, i valori dei prezzi possono essere tradotti in modo che la formattazione si rompa o che la valuta venga cambiata.

Per evitarlo, racchiudi l’output prezzo in elementi che non dovranno essere tradotti.

Markup consigliato #

Usa entrambi gli attributi translate="no" e la classe notranslate sull’elemento del prezzo:

<span class="clerk-price notranslate" translate="no">
  {{ product.price | money }}
</span>

Se mostri prezzo di listino e prezzo in saldo, applica lo stesso schema a ciascun valore prezzo:

<span class="clerk-old-price notranslate" translate="no">
  {{ product.list_price | money }}
</span>
<span class="clerk-new-price notranslate" translate="no">
  {{ product.price | money }}
</span>

Dove applicare #

Nel tuo Design Clerk dove vengono resi i prezzi.
In qualsiasi wrapper HTML personalizzato che mostra valori prezzi.

In questo modo il resto della pagina rimarrà traducibile mantenendo però la formattazione di prezzo e valuta intatta.

Invia oggetti prezzo #

Clerk deve conoscere i prezzi di ciascun prodotto nelle diverse valute.

Il modo più semplice è inviarli come oggetto JSON codificato come stringa dei prezzi formattati, con la ISO della valuta come chiave, nel tuo Data Feed.

"products": [
  {
    "id": 1,
    "name": "Cheese",
    "description": "A nice piece of cheese.",
    "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 codificato come 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": "A pound of nuts",
    "description": "That's a lot of nuts!",
    "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 come stringa
    "prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}",
    "list_prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}"
  }
]

Crea formatter #

In Clerk.js puoi definire funzioni JavaScript da usare con i tuoi Design.

Qui puoi definire una funzione che prende il tuo price-dict come argomento e restituisce il prezzo per una valuta specifica, in base alla logica frontend desiderata.

Assicurati di sostituire currency con la valuta attualmente selezionata 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];
      }
  }
});

Usa il formatter #

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

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

Prezzi specifici per cliente #

Per mostrare prezzi completamente unici in base al cliente loggato, crea un Event in Clerk che inserisce il prezzo corretto prima che i prodotti siano visualizzati.

Events sono funzioni JavaScript eseguite prima o dopo che Clerk mostra i prodotti.

Questo metodo è possibile solo se riesci a recuperare i prezzi dal server, direttamente da una funzione JavaScript in frontend sulla base di un product ID e un customer ID.

Per visualizzare prezzi individuali, il codice deve girare immediatamente dopo la risposta.

Un esempio di event semplice:

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

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

La funzione prende come argomento data, che è l’intera response che Clerk restituisce dall’API.

Prezzi individuali per cliente #

Se devi visualizzare prezzi completamente unici per ogni cliente loggato, dovrai configurare un Event che inserisce il prezzo corretto dopo che i prodotti sono visualizzati.

Gli Event sono funzioni JavaScript eseguite prima o dopo che Clerk mostra i prodotti.

Questo approccio presume che tu riesca a recuperare i prezzi dal tuo server tramite una chiamata AJAX frontend, sulla base per esempio di product ID e customer ID.

Il modo migliore è prima creare un placeholder nel design che conterrà il prezzo, poi sostituirlo con il prezzo restituito dalla chiamata AJAX.

Un esempio:

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

Puoi poi usare l’evento Clerk per attendere che i prodotti siano renderizzati, fare una richiesta al server prezzo usando l’ID prodotto e l’ID cliente, prima di sostituirlo nell’HTML.

Ecco un esempio di come fare:

<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 riesca a identificare un cliente loggato con INSERT_CUSTOMER_ID e che abbia una funzione tipo FETCH_PRICE_FROM_SERVER che restituisce il prezzo per il prodotto in base al cliente.

price_container viene usato per targetizzare il prodotto corretto grazie all’ID disponibile in data-clerk-product-id, che viene aggiunto da Clerk.js a tutti i prodotti.

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

Prezzi per gruppi cliente #

La configurazione dei prezzi gruppo cliente consiste in 4 passaggi:

Includere i prezzi nel data feed.
Includere una variabile globale che recupera il customer group ID.
Creare una funzione per recuperare il prezzo rilevante.
Visualizzare il prezzo nel Design.

Includi oggetti prezzo #

Per prima cosa aggiungi un attributo a tutti i prodotti con tutte le varie opzioni di prezzo, associando ogni prezzo al gruppo cliente.

Questo deve essere inviato come oggetto JSON. Per esempio:

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

Variabile ID cliente #

Aggiungi una variabile globale dinamica a Clerk.js che recupera il customer-group ID dell’attuale cliente e lo assegna come valore.

Il valore del Customer Group ID deve essere equivalente alla chiave del prezzo nel Data Feed.

Per esempio, uno user che deve vedere il prezzo del gruppo 2, allora l’ID deve 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 relativo.

Fallo scrivendo una funzione che prende la chiave customer_group nell’oggetto prezzi come chiave.

Inseriscilo nella configurazione Clerk.js. Qui sotto l’esempio chiamato getPrice:

Clerk('config', {
  globals: {
    customer_group: "GROUP2"
  },
  formatters: {
    getPrice: function (prices, customer_group) {
      return prices[customer_group];
    }
  }
});

Visualizza prezzo #

Quando il formatter getPrice è stato creato, puoi nominarlo direttamente nel tuo design, insieme alla lista customer_group_prices creata al punto 1:

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

Autenticazione HTTP #

L’autenticazione HTTP viene spesso usata sui siti di staging per evitare visitatori indesiderati.

Questo, in molti casi, bloccherà anche l’importer di Clerk e di solito mostra un errore 401 Unauthorized nel log di sincronizzazione.

Puoi risolvere inserendo le informazioni di autenticazione nell’URL di importazione.

In my.clerk.io > Data > Configuration, aggiorna il tuo import URL così:

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

Nessun ordine tracciato #

In my.clerk.io, Tracked Orders e Order Details sono stati uniti in una singola pagina Orders.

Clerk deve tracciare continuamente le vendite dallo shop online per mantenere i risultati aggiornati sul comportamento dei tuoi clienti.

Tuttavia, alcune impostazioni nel sito possono causare il fallimento del tracciamento delle vendite.

Sotto puoi vedere come effettuare il debug del tracciamento delle vendite usando una configurazione Clerk.js e scoprire quali sono i problemi e soluzioni più comuni.

Prima di cominciare #

Assicurati di aver installato:

Lo script tracking Clerk.js su tutte le pagine.
Lo script Sales-tracking sulla tua Pagina di conferma ordine.

Sono richiesti per tracciare le vendite quando usi una configurazione Clerk.js.

Controlla i log #

Nella maggior parte dei casi, il tracciamento delle vendite fallisce per errori nei visitor IDs o nei product IDs della chiamata sale inviata a Clerk dopo il completamento dell’acquisto.

Per fare debug, dovrai effettuare un ordine di test.

A volte il problema può riguardare lo script di sales tracking stesso ed essere visibile guardando i log su my.clerk.io > Developers > Logs.

Se il tracciamento delle vendite fallisce a causa di un errore nello script, spesso lo vedrai in questa pagina.

Clicca su Details per saperne di più.

Se non trovi errori nei log, il modo più semplice per identificare altri problemi di tracciamento vendite è fare un ordine di test.

Debug ordine di test #

In questo esempio utilizziamo Chrome per mostrare come effettuare il debug del tracciamento delle vendite con un ordine di test, ma altri browser hanno funzioni simili.

Metti più prodotti nel carrello del sito ecommerce.
Procedi al Checkout.
Prima di inviare l’ordine, apri la Console del browser.
Trova Network e cerca “clerk”.
Effettua l’ordine, in modo da vedere la pagina di conferma ordine.
Clicca sulla chiamata che inizia con sale (di solito sale?key=…).

Qui vedrai i dati inviati e ricevuti dall’endpoint API sales-tracking.

Clicca su Preview per identificare eventuali errori che possono causare la mancata tracciabilità degli ordini.

Qui sotto alcuni degli errori più comuni.

Sintassi prodotti non valida #

Questo errore si verifica se invii product IDs con sintassi errata.

Gli errori più comuni sono:

I product-IDs sono string-encoded nel sales-tracking ma usi interi in Clerk o viceversa.
L’elenco degli IDs contiene caratteri di formattazione testo invece di puro JSON: "products":\[\\"id"\\:\\"123-m"\\\].

Argomento mancante #

Questo succede se non invii tutti i dati necessari a Clerk per tracciare la vendita.

Assicurati di includere tutti gli attributi richiesti nella chiamata sales-tracking.

Nessuna chiamata effettuata #

Se non vedi la chiamata sale anche con entrambi gli script installati, qualcosa ha causato il caricamento errato di Clerk.js.

Verifica seguendo questi passi:

Apri la Console nel browser.
Scrivi “Clerk”.
Se Clerk.js non è stato caricato correttamente, vedrai un ReferenceError:

Uncaught ReferenceError: Clerk is not defined

Se è così, controlla la configurazione di Clerk.js:

Assicurati che Clerk.js sia installato su tutte le pagine.
Assicurati che non sia bloccato da altri script JavaScript.

Blocco da parte di Iubenda #

Se usi iubenda per la cookie consent (specialmente con Automatic blocking) e un visitatore rifiuta i cookie, iubenda può bloccare gli script o le richieste di Clerk.

Tipicamente significa che:

La richiesta sale non viene mai inviata, dunque l’ordine non viene tracciato oppure non è attribuito a Clerk.
Gli elementi Clerk potrebbero non essere renderizzati affatto, o Clerk.js potrebbe loggare un errore console su caricamento multiplo dello script (perché iubenda riscrive/pospone gli script).

Soluzione: inserire Clerk.io tra i consentiti su iubenda #

Su iubenda, aggiungi Clerk alla allowlist così da non bloccarlo se il visitatore rifiuta i cookie.

Assicurati almeno che questi domini siano nella allowlist:

cdn.clerk.io (Clerk.js)
api.clerk.io (richieste tracking e sales)

Le etichette UI variano su iubenda, ma solitamente sono nelle impostazioni Cookie Solution alla voce Automatic blocking (whitelist/allowlist/lista ignorati).

Per la guida di iubenda, vedi l’articolo sul blocco eccessivo: https://www.iubenda.com/en/help/153445-what-to-do-when-the-automatic-blocking-mode-is-blocking-too-much/.

Verifica la soluzione #

Dopo aver aggiornato le impostazioni di iubenda:

Carica lo shop online, rifiuta i cookie e apri la console del browser.
Conferma che Clerk.js sia disponibile (per esempio, typeof Clerk non deve essere "undefined").
Esegui Clerk("debug"), effettua un ordine di test e conferma che una richiesta sale venga inviata a Clerk e ritorni status: "ok".

Nessun impatto Clerk #

Se le vendite compaiono tracciate in my.clerk.io ma nessuna è mostrata come influenzata da Clerk, potresti avere un errore nella configurazione di visitor-tracking / click-tracking.

Per prima cosa, assicurati che il visitor-tracking funzioni seguendo questi passaggi:

Clicca su un qualsiasi prodotto tramite la Search o le Recommendations di Clerk.
Procedi a completare un ordine contenente quel prodotto.
Accedi a my.clerk.io e vai su Orders.
Attendi che l’ordine venga visualizzato.

Se il visitor-tracking funziona, vedrai il valore aggiunto da Clerk nei dettagli ordine sulla pagina Orders:

Se non vedi alcun valore aggiunto nell’ordine effettuato, le sezioni seguenti illustrano gli errori più frequenti.

Configurazione API #

Se hai configurato Clerk con una integrazione personalizzata diretta con l’API, devi attivare manualmente il visitor-tracking.

Leggi come fare in questo articolo API.

IDs prodotto errati #

Perché il visitor-tracking funzioni, il click-tracking e il sales-tracking devono usare i medesimi product IDs di quelli ricevuti dall’importer.

Di solito se non funziona è perché stai tracciando i variant IDs anziché parent IDs oppure SKU al posto dell’ID.

Per verificare se questo è il problema fai così:

In my.clerk.io, vai su Data > Orders e clicca sull’ID di un ordine effettuato.
Se Clerk non riesce a identificare il prodotto, vedrai un placeholder di ID e image.
Vai su Data > Products e cerca il nome del prodotto che hai aggiunto. Qui potrai vedere l’ID previsto per il prodotto.

Usa questo per configurare il tuo monitoraggio delle vendite utilizzando gli ID prodotto corretti.

Modifiche all’ID visitatore #

Clerk utilizza un visitor ID per identificare ogni singola sessione, inclusi i prodotti che cliccano e acquistano.

Per questo motivo, gli ID dovrebbero rimanere invariati almeno per tutta la durata della sessione, e preferibilmente anche tra più sessioni.

Questo visitor ID viene creato automaticamente utilizzando Clerk.js per la configurazione, ma se usi una configurazione API, o personalizzi i tuoi visitor ID, potresti cambiarlo accidentalmente.

Questo errore è raro, ma puoi controllare il visitor ID seguendo questi passaggi:

Apri le impostazioni di Network nel browser e restringi i risultati a “clerk”.
Inizia controllando una delle chiamate undefined che sono correlate a search o recommendations.
In payload puoi verificare l’attuale Visitor ID. Potrai farlo per tutte le chiamate associate a Clerk.
Procedi cliccando sul prodotto e effettua un ordine con quel prodotto.
Nella pagina di Order Success, controlla di nuovo la Network e trova la chiamata a sale?.
Assicurati che visitor in payload corrisponda al Visitor ID visto nel passaggio 3.

Se gli ID visitor non corrispondono, devi scoprire perché cambiano.

Una causa comune della variazione degli ID visitatore potrebbe essere la rigenerazione degli ID a ogni nuovo caricamento di pagina.

Aggiorna il tuo codice per utilizzare lo stesso visitor ID su ogni pagina.

Nascondere slider con pochi prodotti #

Se una categoria ha pochissimi prodotti, uno slider può sembrare vuoto o ripetitivo.

Ci sono due modi per gestire questa situazione:

Clerk Design condizionale #

Utilizza una condizione intorno al markup dello slider in modo che venga visualizzato solo quando sono restituiti abbastanza prodotti.

{% if products.length >= 6 %}
  <div class="clerk-slider">
    {% for product in products %}
      <!-- product card -->
    {% endfor %}
  </div>
{% endif %}

Questa soluzione è veloce da implementare, ma si basa comunque sulla risposta di Clerk per decidere se mostrare o meno lo slider. Significa che comunque effettui una chiamata all’API anche quando lo slider non viene mostrato.

Condizione lato server #

Se la tua piattaforma conosce già il conteggio prodotti della categoria, decidi nel tuo template se mostrare il codice embed di Clerk.

{% if category.product_count >= 6 %}
  <span class="clerk" data-template="@category-page-slider"></span>
{% endif %}

Questo approccio è preferibile perché lo slider viene inizializzato solo quando ci sono abbastanza prodotti, e il comportamento rimane perfettamente allineato con la logica di conteggio categorie del tuo webshop.

Aggiorna a Clerk.js 2 #

Clerk.js 2 è una versione più veloce e flessibile della nostra libreria JavaScript.

Rende più semplice installare Clerk su qualsiasi webshop.

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

Le due principali differenze di Clerk.js 2 sono:

I Design in my.clerk.io utilizzano il Liquid, ma possono essere facilmente creati anche con il Design Editor.
Lo script deve essere inserito subito prima del tag </head> nel template del tuo webshop.

Crea design #

Poiché Clerk.js 2 utilizza un approccio differente ai Design, devi crearne di nuovi.

Puoi creare i tuoi Design Clerk.js 2 rifacendoli nel Design Editor, oppure convertendo i tuoi vecchi Design di codice in Liquid, come spiegato nella guida qui sotto.

Qui di seguito una descrizione di come convertire i tuoi vecchi Design di codice in Liquid.

Opzione Design Editor #

Vai su my.clerk.io > Recommendations/Search > Designs > New Design.
Seleziona un tipo di design diverso da Blank e assegnagli un nome. Consigliamo di aggiungere “V2” così è evidente che stai usando i design di Clerk.js 2.
Nel Design Editor, clicca uno degli elementi esistenti come nome, immagine, pulsante, ecc per modificarlo, o aggiungi nuovi elementi al Design.
Clicca Publish Design quando hai terminato, e vai a Step 2 della guida.
Vai su Recommendations/Search > Elements e cambia il tuo Clerk Element per usare il nuovo Design, poi clicca Update Element.
Questo farà sì che temporaneamente non verranno mostrati sul tuo webshop, fino all’inserimento di Clerk.js 2 come descritto più avanti in questa guida.

Conversione dei design #

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

Vai su my.clerk.io > Recommendations/Search > Designs > New Design.
Seleziona Blank > Code e assegnagli un nome. Consigliamo di aggiungere “V2” così è evidente che utilizzi i design di Clerk.js 2.
Clicca Create Design.
Otterrai così un design vuoto con Product HTML e CSS pronto per l’uso.
Torna alla panoramica dei design e clicca Edit Design sul tuo Design Clerk.js 1. Si consiglia di farlo in una nuova tab per copiare facilmente il codice.
Copia il vecchio Design Clerk.js 1 nel tuo nuovo Design di Clerk.js 2.
- Noterai che nel nuovo non c’è Container Code.
- Questo perché Liquid usa i for loop per mostrare tutti i prodotti.
- Copia il vecchio Product HTML all’interno del for-loop, il vecchio Container Code intorno e il CSS.
Converti il Design nella sintassi di Liquid. La differenza principale è che i vecchi Design usavano la sintassi {{ formatter attribute }} mentre la sintassi della v2 è {{ product.attribute | formatter }}.
Controlla tutti i tuoi attributi e cambiali al nuovo formato.
Se utilizzi istruzioni {{#if}} o {{#is}}, dovrai convertirle. Usa la sintassi {% if product.attribute %} {% else %} {% endif %}.
Elimina id="{{ $id }}" e la classe :target dal container code nella versione Clerk.js 2, perché non sono più supportati.
Di seguito un esempio di design Clerk.js 1, e la versione completamente convertita:

Clerk.js 1 Design #

// 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>

<!-- This code creates the slider by its ID. -->
<script type="text/javascript">
    Clerk.ui.slider("{{ id }}").init();
</script>

Clerk.js 2 Design #

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

Clicca Update Design per salvare le modifiche.
Vai su Recommendations/Search > Elements e cambia il tuo blocco Element per usare il nuovo Design.
Clicca Update Element. Questo farà sì che temporaneamente non vengano mostrati nel tuo webshop, fino al completamento di Step 2. Scegli il nuovo Design per tutti gli Element che devono essere aggiornati.

Sostituisci lo script #

Individua il file di template utilizzato per mostrare tutte le pagine del webshop, dove si trova lo script Clerk.js originale nella parte inferiore.
Rimuovi il vecchio script Clerk.js dal file. Avrà un aspetto simile a questo:

<!-- Start of Clerk.io E-commerce Personalisation tool - 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>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Vai su my.clerk.io > Developers > Tracking Code. Qui troverai il codice di Clerk.js 2.
Copia questo codice, inseriscilo subito prima del tag </head> nel template e salva.

Congratulazioni! Ora stai usando la configurazione Clerk.js 2, molto migliorata!

Puoi leggere la documentazione completa su 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, con il risultato che nessuno slider o risultato di ricerca viene mostrato.

Quando accade, comparirà il seguente errore nella console:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi richiedono di modificare il tracking-script che hai inserito in fondo a tutte le pagine.

Inclusione in Require.js #

Il metodo migliore è cercare che Require.js riconosca Clerk.

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

Ignora 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 tracking:

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

Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.