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 loro soluzioni, dalle single-page app al tracciamento delle vendite.

Single-page app #

Sono anche chiamate Progressive Web App (PWA) e generalmente caricano il sito come una singola pagina, invece di caricare pagine individuali come normalmente avviene.

Quando una pagina viene caricata per la prima volta, la libreria Clerk.js avvia automaticamente una funzione per renderizzare 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 renderizzate con JavaScript piuttosto che con un normale caricamento di pagina.

Per questo motivo, è necessario controllare il rendering con Clerk.js in modo che corrisponda al modo in cui carichi le pagine nell’app.

Includi Clerk.js #

Clerk.js deve essere caricato solo una volta, quando il sito viene inizialmente caricato.

Dopo di ciò, la libreria sarà disponibile per tutta la sessione.

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

Controlla il rendering #

Di default, Clerk.js renderizza qualsiasi elemento che abbia la classe clerk, indipendentemente dal fatto che sia inserito durante il caricamento iniziale della pagina o quando il DOM viene modificato.

Puoi controllare il momento di rendering inserendo l’elemento quando è pronto per essere visualizzato.

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 ritorna sulla stessa pagina.

Questo per garantire che Clerk.js non consideri lo snippet come precedentemente renderizzato, impedendone la 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 gli Elementi con i tuoi selettori personalizzati dopo la prima volta che lo rendi.

Impatto sulla velocità delle pagine #

L’aggiunta di 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 viene caricato mentre Clerk.js renderizza il contenuto.

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

Per ridurre al minimo il tempo di caricamento aggiuntivo, 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 recommendations hanno una risoluzione di 400x400px nella 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 tuo sito, potresti vedere Clerk.js elencato sotto Leverage browser caching.

Lo scopo di Clerk.js è rendere super semplice inserire i risultati di Clerk in qualsiasi sito web.

Clerk.js contiene molte funzionalità per gestire tracciamento e componenti UI come Instant Search, slider, popup e altro.

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

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

Più lungo è il tempo di cache, più tempo ci vorrà affinché tutti abbiano accesso alle funzionalità più recenti.

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

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

Se non sono state apportate modifiche a Clerk.js, non verrà scaricato nulla.

Il tempo di scadenza della cache di 60 minuti è quindi un compromesso tra minimizzare le richieste web e vedere nuove funzionalità e miglioramenti.

La maggior parte delle sessioni dura meno di 60 minuti, quindi la richiesta verrà effettuata solo una volta per sessione.

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

Impatto CLS #

Il Cumulative Layout Shift (CLS) può avere un impatto negativo su SEO ed esperienza utente quando i contenuti iniettati in modo dinamico spostano elementi in una pagina.

In alcuni casi, tra altri fattori, Clerk può contribuire al punteggio CLS.

Puoi leggere di più sul CLS qui.

Segui questa linea guida solo se il tuo punteggio CLS è superiore a 0.2 e gli elementi Clerk sono above the fold.

Per prevenire lo spostamento del contenuto, occorre riservare uno spazio come segnaposto per le recommendations di Clerk prima che Clerk.js le inietti.

Per farlo, è necessario aggiungere un’altezza minima basata sull’altezza del contenuto atteso.

Esempio di codice:

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

Effettuare chiamate API #

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

Questa funzione accetta 3 argomenti:

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

Richieste #

Segue 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]
  }
);

Callback #

Quando effettui chiamate API, puoi utilizzare funzioni callback per gestire la risposta come preferisci.

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

Qui sotto 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 diversamente per ciascuna piattaforma e la funzionalità può cambiare a seconda dei plugin che utilizzi.

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

Approccio generale #

Alcuni pulsanti aggiungi al carrello richiedono l’esecuzione di JavaScript per funzionare.

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

Guarda come fare nei nostri developer docs qui.

Analizza il pulsante aggiungi al carrello per identificare il codice associato, ad esempio in una pagina categoria.

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

Copia l’intero HTML del pulsante.

Copia e incolla questo codice nel tuo Design.

Ora devi identificare le variabili nel codice.

Più spesso, occorre trovare dove il codice utilizza:

Product ID
Quantità del 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> con la classe button-container:

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

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

Questi valori devono essere sostituiti con tag Liquid nel Design affinché vengano utilizzati gli ID prodotto e le quantità appropriate nell’output HTML.

Dopo queste modifiche, il pulsante aggiungi al carrello finale apparirà così:

<div class="button-container">
  <a 
    class="button ajax_add_to_cart_button btn btn-default" 
    style="position: relative;" 
    href="https://www.examplelinktocart.com/cart?add={{ product.qty }}&amp;id_product={{ product.id }}&amp;" 
    rel="nofollow" 
    title="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 usare per risolvere problemi.

Cliccando sul link dell’errore otterrai più informazioni su cosa è andato storto, che puoi usare per debug o da inviare al nostro team di supporto che ti aiuterà.

Qui sotto troverai una lista degli errori più comuni.

Contenuto sconosciuto #

Questo errore compare 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 Modifica Elemento per qualsiasi Element, per vedere quale riferimento è corretto.

Endpoint API non valido #

Questo errore si verifica se hai utilizzato la classe clerk da qualche parte nel tuo HTML.

Questa classe è riservata per l’uso con i nostri snippet, poiché Clerk.js usa questa classe per identificare quali elementi rendere.

Per risolvere, 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 un tipo o una sintassi errata.

Ad esempio, se i tuoi ID prodotto sono interi serve che lo siano 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 un tipo o una sintassi errata.

Nella maggior parte dei casi capita se il placeholder nel codice di embed della 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 nella tendina Choose your platform prima di copiare lo snippet.

Così cambierà per includere la logica della tua piattaforma per selezionare il corretto ID categoria.

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

Chiave API errata #

Questo errore comparirà se la public API key fornita non corrisponde a nessun account in Clerk.

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

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

Dati vendite POS/ERP #

Per alcuni e-commerce, è utile caricare dati di vendita provenienti da sistemi diversi dal sito stesso.

Ad esempio, se vuoi ottimizzare l’algoritmo in base alle vendite di un negozio fisico o di uno shop B2B.

Clerk non distingue tra ordini da varie fonti—finché puoi fornire un ID, una data e una lista di prodotti acquistati, possono essere caricati su Clerk.

L’approccio raccomandato è utilizzare la API CRUD perché consente di automatizzare completamente il compito.

Implementando queste chiamate API, puoi inviare i dati ordine direttamente al tuo Store in Clerk.

Crea semplicemente una chiamata POST all’endpoint /orders nel tuo sistema ERP o nel webshop, esegui il job a intervalli regolari, es. una volta al mese, e potrai usare gli ordini offline per aumentare le recommendations online e i risultati search.

In alternativa, puoi caricare manualmente un file CSV, senza bisogno di programmare nulla.

Puoi leggere di più sui file CSV qui.

Conversione valuta #

Ci sono vari modi per lavorare con la conversione valuta in Clerk.

Di seguito è illustrato un metodo semplice per farlo funzionare.

Tradurre le valute #

Se i visitatori usano Google Translate sul tuo webshop, i valori prezzo possono venire tradotti in modo tale da rompere il formato o cambiare la visualizzazione della valuta.

Per evitare ciò, avvolgi l’output del prezzo in elementi che non devono essere tradotti.

Markup consigliato #

Usa sia translate="no" che la classe notranslate sull’elemento del prezzo:

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

Se mostri il prezzo di listino e quello scontato, 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 visualizzati i prezzi.
In qualsiasi wrapper HTML personalizzato che visualizza valori di prezzo.

Questo mantiene il resto della pagina traducibile pur preservando il formato corretto di prezzo e valuta.

Inviare oggetti prezzo #

Clerk ha bisogno di conoscere i prezzi di ogni prodotto nelle diverse valute.

Il modo più semplice per farlo è inviarli come oggetti JSON in formato stringa di prezzi formattati, con la valuta ISO 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 in formato 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 in formato stringa
    "prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}",
    "list_prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}"
  }
]

Crea un formatter #

In Clerk.js puoi definire funzioni JavaScript, che possono essere usate nei tuoi Design.

Qui puoi definire una funzione che accetta come argomento il tuo dizionario prezzi e restituisce il prezzo per una specifica valuta, in base alla logica frontend che preferisci.

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 usato nel tuo design con la seguente sintassi:

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

Prezzi specifici per cliente #

Clerk supporta la visualizzazione di prezzi diversi in base al cliente loggato, sia recuperando i prezzi individuali al momento del rendering sia pre-memorizzando i prezzi per gruppo nei dati prodotto.

Questo è trattato in dettaglio nell’articolo dedicato Customer Pricing.

Autenticazione HTTP #

L’autenticazione HTTP è spesso utilizzata su siti di staging per evitare visitatori indesiderati.

Questo può, in molti casi, bloccare anche l’importatore Clerk e mostrare tipicamente un errore 401 Unauthorized nel registro di sincronizzazione.

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

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

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

Nessun ordine tracciato #

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

Clerk deve tracciare continuamente le vendite dal webshop per mantenere aggiornati i risultati in base al comportamento dei tuoi clienti.

Tuttavia, alcune impostazioni in un webshop possono causare il fallimento del tracciamento delle vendite.

Di seguito, puoi scoprire come fare il debug del tracciamento delle vendite con un setup Clerk.js e vedere i problemi e le soluzioni più comuni.

Prima di iniziare #

Assicurati di aver installato:

Lo script di tracking Clerk.js su tutte le pagine.
Lo script di tracciamento vendite sulla tua pagina di conferma ordine.

Questi sono necessari per tracciare le vendite in generale quando usi un setup Clerk.js.

Controlla i log #

Nella maggior parte dei casi, il tracciamento delle vendite fallisce a causa di errori negli ID visitatore o negli ID prodotto nella chiamata di vendita inviata a Clerk dopo il completamento di un acquisto.

Per eseguire il debug, dovrai fare un ordine di test.

Tuttavia, in alcuni casi può essere collegato direttamente allo script di tracciamento vendite e può essere risolto esaminando i log in my.clerk.io > Developers > Logs.

Se il tracciamento delle vendite fallisce a causa di un errore nel tuo script, spesso potrai vederne la causa in questa pagina.

Clicca su Details per maggiori dettagli.

Se non vedi errori nei log, il modo più semplice per identificare altri tipi di problemi di tracking vendite è effettuare un ordine di test.

Debugging ordine di test #

In questo esempio si usa Chrome per mostrare come effettuare il debug del tracciamento vendite con un ordine di test, ma altri browser hanno funzionalità simili.

Sul tuo webshop, aggiungi un paio di prodotti al carrello.
Procedi al Checkout.
Prima di completare l’ordine, apri la Console del browser.
Vai su Network e cerca “clerk”.
Completa l’ordine accedendo alla pagina di conferma ordine.
Clicca sulla chiamata che inizia con sale (normalmente sale?key=…).

Qui vedrai i dati inviati e ricevuti dall’endpoint API di tracciamento vendite.

Clicca su Preview per identificare eventuali errori che possono causare il mancato tracciamento delle vendite.

Di seguito gli errori più comuni del tracking vendite.

Sintassi prodotti non valida #

Errore se gli ID prodotti inviati hanno una sintassi errata.

Gli errori più comuni sono:

Gli ID prodotto sono string-encoded nel tracciamento vendite ma usi Interi in Clerk o viceversa.
L’elenco prodotti contiene caratteri di formattazione testuale invece di puro JSON: "products":\[\\"id"\\:\\"123-m"\\\].

Argomenti mancanti #

Significa che non stai inviando tutti i dati che Clerk necessita per tracciare la vendita.

Assicurati di includere tutti i dati richiesti nello script vendite.

Nessuna chiamata effettuata #

Se non vedi la chiamata a sale anche con entrambi gli script installati, significa che qualcosa ha impedito il corretto caricamento dello script Clerk.js.

Testalo così:

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

Uncaught ReferenceError: Clerk is not defined

Se questo è il caso, controlla il tuo setup Clerk.js:

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

Blocco di Iubenda #

Se usi iubenda per la gestione cookie (soprattutto con blocco automatico) e un visitatore rifiuta i cookie, iubenda può bloccare gli script o le richieste di Clerk.

Di solito significa che:

La richiesta sale non viene inviata, quindi l’ordine non è tracciato o non è attribuito in Clerk.
Gli elementi Clerk potrebbero non renderizzarsi per niente, o Clerk.js può segnalare un errore console per caricamento multiplo (perché iubenda riscrive/posticipa gli script).

Soluzione: Allowlist Clerk.io in iubenda #

In iubenda, allowlista Clerk affinché non venga bloccato quando il visitatore rifiuta i cookie.

Al minimo, assicurati che siano allowlistati questi domini:

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

Le etichette UI esatte variano in iubenda, ma si trovano solitamente nelle impostazioni Cookie Solution del tuo progetto iubenda per Automatic blocking (allowlist/whitelist/ignore list).

Per la guida di iubenda ufficiale: https://www.iubenda.com/en/help/153445-what-to-do-when-the-automatic-blocking-mode-is-blocking-too-much/.

Verifica della soluzione #

Dopo aver aggiornato le impostazioni di iubenda:

Carica il webshop, rifiuta i cookie e apri la console browser.
Conferma che Clerk.js sia disponibile (ad esempio, typeof Clerk non dovrebbe essere "undefined").
Esegui Clerk("debug"), effettua un ordine di test e conferma che una richiesta sale sia inviata a Clerk e ritorni status: "ok".

Nessun impatto Clerk #

Se tracci le vendite con successo in my.clerk.io ma nessuna viene mostrata come impattata da Clerk, potresti avere un errore nel tracciamento visitatore/click.

Inizia verificando che il tracciamento visitatore funzioni seguendo questi passaggi:

Clicca su un prodotto tramite la Search o le Recommendations di Clerk.
Procedi ad effettuare un ordine che contenga questo prodotto.
Accedi a my.clerk.io e vai su Orders.
Attendi la visualizzazione dell’ordine.

Se il tracciamento visitatore funziona, vedrai il valore aggiunto da Clerk nei dettagli ordine nella pagina Orders:

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

Setup API #

Se configuri Clerk con una integrazione personalizzata diretta tramite API, devi abilitare attivamente il tracciamento visitatore.

Leggi come fare in questo articolo API.

ID prodotto errati #

Affinché il tracciamento visitatore funzioni, il click- e sales-tracking devono tracciare gli stessi ID prodotto che riceviamo nell’importatore.

Il malfunzionamento è solitamente dovuto al tracciamento di ID varianti invece degli ID principali o di SKU invece di ID.

Per verificare se è questo il problema:

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

Usa queste info per configurare il tracking vendite sull’utilizzo dei corretti ID prodotto.

Cambio ID visitatore #

Clerk utilizza un visitor ID per identificare ogni sessione individuale, compresi i prodotti cliccati e acquistati.

Per questo motivo, gli ID dovrebbero restare gli stessi almeno durante tutta la sessione, e preferibilmente anche tra più sessioni.

Questo visitor ID viene creato automaticamente quando si usa Clerk.js per la configurazione, ma se utilizzi una setup API o personalizzi i visitor ID potresti cambiarlo accidentalmente.

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

Apri le impostazioni Network nel browser e filtra i risultati per “clerk”.
Inizia controllando una delle chiamate undefined relative a search o recommendations.
In payload puoi verificare l’attuale visitor ID. Potrai farlo per tutte le chiamate associate a Clerk.
Procedi a cliccare il prodotto e completa un ordine con quel prodotto.
Sulla Order Success page, controlla nuovamente la Network e trova la chiamata a sale?.
Controlla che il campo visitor in payload corrisponda al visitor ID visto al punto 3.

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

Una causa comune del cambio di ID visitatore può essere la sua rigenerazione ad ogni nuovo caricamento di pagina.

Aggiorna il codice in modo da usare lo stesso visitor ID per ogni pagina.

Nascondere slider con pochi prodotti #

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

Ci sono due modi per gestirlo:

Condizionale nel Design Clerk #

Usa una condizione attorno al markup dello slider per renderizzarlo solo se vengono restituiti abbastanza prodotti.

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

Questo è veloce da implementare, ma si basa comunque sulla risposta di Clerk per decidere la visibilità dello slider. Significa che comunque verrà effettuata una chiamata API anche se lo slider non viene mostrato.

Condizionale lato server #

Se la tua piattaforma già conosce la quantità di prodotti della categoria, decidi direttamente nel template se includere o meno il codice di embed Clerk.

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

Questo è l’approccio preferito, perché lo slider viene inizializzato solo quando ci sono abbastanza prodotti e il comportamento resta totalmente allineato alla logica del conteggio prodotti della tua piattaforma.

Aggiornamento 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 effettuare con successo l’upgrade.

Le due principali differenze di Clerk.js 2 sono:

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

Creare i design #

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

Puoi creare i tuoi Design Clerk.js 2 rifacendoli nel Design Editor o convertendo i tuoi vecchi code Design in Liquid, come mostrato nella guida qui sotto.

Ecco come convertire i tuoi vecchi code Design in Liquid.

Opzione Design Editor #

Vai a my.clerk.io > Recommendations/Search > Designs > New Design.
Seleziona un tipo di design che non sia Blank e dagli un nome. Si consiglia di aggiungere “V2” per rendere chiaro che stai usando design per Clerk.js 2.
Nel Design Editor, clicca sugli elementi esistenti (nome, immagine, bottone, ecc.) per modificarli, o aggiungi nuovi elementi al Design.
Clicca su Publish Design quando hai finito, poi vai al Passaggio 2 della guida.
Vai su Recommendations/Search > Elements e modifica il tuo Clerk Element per usare il nuovo Design, poi clicca su Update Element.
Questo causerà temporaneamente la mancata visualizzazione su webshop finché non hai inserito Clerk.js 2 come descritto più avanti.

Conversione design #

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

Vai su my.clerk.io > Recommendations/Search > Designs > New Design.
Seleziona Blank > Code e dai un nome. Si raccomanda di aggiungere “V2” per riconoscere i design per Clerk.js 2.
Clicca su Create Design.
Questo ti darà un design vuoto con Product HTML e CSS che puoi utilizzare.
Torna alla panoramica del design e clicca su Modifica Design per il tuo Clerk.js 1 Design. Ti consigliamo di farlo in una nuova scheda in modo da poter copiare facilmente il codice.
Copia il vecchio Clerk.js 1 Design nel tuo nuovo Clerk.js 2 Design.
- Noterai che non c’è Container Code nel nuovo.
- Questo perché Liquid utilizza for loops per mostrare tutti i prodotti.
- Copia il tuo vecchio Product HTML dentro il for-loop, il tuo vecchio Container Code attorno ad esso e copia anche 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 versione 2 è {{ product.attribute | formatter }}.
Passa in rassegna tutti i tuoi attributi e cambiali nel nuovo formato.
Se usi istruzioni {{#if}} o {{#is}}, anche queste devono essere convertite. Usa la sintassi {% if product.attribute %} {% else %} {% endif %}.
Elimina id="{{ $id }}" e la classe :target dal container code nella versione Clerk.js 2 in quanto non sono più supportati.
Qui sotto trovi un esempio di un Clerk.js 1 design 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 su Aggiorna Design per salvare le modifiche.
Vai su Recommendations/Search > Elements e cambia il tuo blocco Element per usare il nuovo Design.
Clicca su Aggiorna Elemento. Questo farà sì che temporaneamente non appaiano sul tuo webshop, finché non avrai completato il Passo 2. Scegli il nuovo Design per tutti gli Elements che devono essere aggiornati.

Sostituisci lo script #

Trova il file template che viene usato per mostrare tutte le pagine del webshop e dove lo script originale di Clerk.js si trova verso il fondo.
Rimuovi il vecchio script Clerk.js dal file. Apparirà 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, poi salva.

Congratulazioni! Ora stai utilizzando la versione molto migliorata Clerk.js 2!

Puoi vedere la documentazione completa di Clerk.js 2 qui.

Gestione di require.js #

Questa sezione si applica solo se stai usando Clerk.js 1.

In alcune configurazioni, Require.js impedisce il caricamento di Clerk.js, il che significa che non verranno mostrati slider o risultati di ricerca.

Quando accade, verrà mostrato il seguente errore nella console:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambe le soluzioni richiedono di apportare modifiche al tracking-script che hai inserito in fondo a tutte le pagine.

Includere in Require.js #

Il modo migliore è cercare di far riconoscere Clerk a Require.js.

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; all’inizio dello script di tracking:

Dopo aver utilizzato 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.