Qualsiasi (webshop)

FAQ

Risposte alle domande frequenti per integrazioni personalizzate

Avete problemi con la vostra integrazione personalizzata? Questo FAQ copre i problemi più comuni e le relative soluzioni, dalle app a pagina singola al tracciamento delle vendite.

App a pagina singola #

Queste sono anche chiamate Progressive Web Apps (PWA) e in genere caricano il sito come una pagina unica, invece di caricare pagine individuali come di norma.

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

Tuttavia, per le app a pagina singola che utilizzano framework come vue.js o next.js, le pagine vengono renderizzate con JavaScript anziché con un normale caricamento della pagina.

A causa di ciò, è necessario controllare il rendering con Clerk.js per allinearlo a come carichi le pagine nell’app.

Include Clerk.js #

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

Dopo questo, la libreria sarà disponibile per l’intera sessione.

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

Controllare il rendering #

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

Puoi controllare i tempi inserendo l’elemento quando è pronto per essere renderizzato.

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

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

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

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

Questo serve a garantire che Clerk.js non veda lo snippet come già renderizzato, causando problemi di 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 automatically initialize Content con i tuoi selettori personalizzati dopo la prima volta che lo renderizzi.

Impatto su PageSpeed #

Aggiungere uno strumento esterno come Clerk.js aumenterà il tempo necessario per caricare il tuo sito, ma è negligibile rispetto alle ulteriori conversioni che fornirà.

Di seguito puoi vedere come influisce sulle prestazioni del tuo sito.

Prestazioni #

La libreria Clerk.js ha solo 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 renderizza il contenuto.

Un aumento del tempo di caricamento di una pagina deriva spesso dal caricamento di più immagini rispetto al passato, poiché i risultati di search results e le recommendations funzionano meglio quando sono visivamente attraenti.

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

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

Google Page Speed #

Se usi 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 estremamente semplice inserire i risultati di Clerk in qualsiasi sito web.

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

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

La 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à perché tutti abbiano accesso alle ultime funzionalità.

La cosa importante è che gli utenti finali devono 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 farà un controllo 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 e quindi la richiesta verrà effettuata una sola volta per sessione.

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

Impatto CLS #

Il Cumulative Layout Shift (CLS) può influire negativamente su SEO ed esperienza utente quando contenuti dinamici spostano gli elementi su una pagina.

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

Puoi leggere di più su CLS qui.

Segui questa linea guida solo nel caso in cui il tuo punteggio CLS sia superiore a 0,2 e gli elementi Clerk siano al di sopra della piega.

Per evitare che il contenuto si sposti, è necessario riservare un segnaposto per le Recommendations prima che Clerk.js li inserisca.

Per fare ciò, bisogna aggiungere un’altezza minima basata sull’altezza prevista del contenuto.

Esempio di codice:

.clerk-slider-wrapper {
    min-height: 300px; /* Adjust based on expected content height */
    width: 100%;
}

Chiamate API #

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

Questa funzione prende 3 argomenti:

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

Richieste #

Di seguito un esempio di script che richiede i 10 prodotti più popolari e registra la risposta sulla 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 funzioni di callback per gestire la risposta come ritieni opportuno.

Le funzioni prendono l’argomento response che contiene tutti i dati restituiti dall’API.

Di seguito è riportato un esempio che crea una lista di elementi HTML che collegano alle categorie corrispondenti 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 Add-to-cart #

Questi pulsanti funzionano in modo diverso per ogni piattaforma e la funzionalità può variare a seconda dei plugin che usi.

Poiché i layout di Clerk consistono in HTML & CSS, di solito puoi aggiungere questa funzionalità se capisci come funziona sul tuo sito.

Approccio generale #

Alcuni pulsanti Add-to-cart richiedono JavaScript per funzionare.

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

Controlla come fare in questa documentazione per sviluppatori.

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

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

Copia l’HTML completo del pulsante.

Copia e incolla questo codice nel tuo Design.

Ora devi identificare le variabili nel codice.

Spesso devi trovare dove il codice usa:

Product ID
Product quantity

Sostituisci i valori per l’ID prodotto con le variabili Liquid per questi 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 Design e testalo per assicurarti che funzioni.

Esempio #

Il pulsante Add-to-cart qui 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 si trova subito dopo &id_product=.

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

Questi valori dovrebbero essere sostituiti con tag Liquid nel Design in modo che gli ID prodotto e le quantità corretti siano usati nell’output HTML.

Con queste modifiche, il pulsante finale Add-to-cart avrà l’aspetto seguente:

<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 della console #

Clerk.js registra molti errori nella console, che puoi usare per eseguire il debug delle problematiche.

Cliccando sul link di errore otterrai ulteriori informazioni su cosa è andato storto, che puoi usare per risolvere l’errore da solo o inviarlo al nostro team di supporto che ti aiuterà.

Di seguito trovi un elenco dei errori più comuni.

Contenuto sconosciuto #

Questo errore si verifica se lo snippet inserito fa riferimento a un Content che non esiste, nell’attributo data-template.

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

Puoi cliccare Edit Content per qualsiasi Content, per vedere quale dovrebbe essere il riferimento.

Endpoint API non valido #

Questo errore si verifica se hai usato la classe clerk nel tuo HTML in qualche punto.

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

Per risolverlo, assicurati di rinominare la classe in qualcosa come clerk-product.

Argomento prodotto non valido #

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

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

Ricorda anche le parentesi intorno 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 errati.

Nella maggior parte dei casi, accade se il placeholder nel codice embed 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 lo snippet manualmente, assicurati di selezionare il tuo sistema negozio nel Choose your platform a discesa prima di copiare lo snippet.

Poi userà la logica della tua piattaforma per selezionare l’ID corretto della categoria.

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

Chiave API non corretta #

Questo errore verrà mostrato se la chiave API pubblica fornita non corrisponde ad alcun account in Clerk.

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

Qui puoi trovare la Public API Key che puoi poi aggiungere allo script di tracciamento Clerk.js direttamente nel codice, oppure nelle impostazioni della tua integrazione, a seconda della tua piattaforma.

Dati vendita POS/ERP #

Per alcuni webshop è rilevante caricare i dati di vendita provenienti da altri sistemi rispetto al webshop effettivo.

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

Clerk non distingue tra ordini provenienti da diverse fonti — fintanto che tu possa fornire un ID, un timestamp e un elenco di prodotti acquistati, possono essere caricati su Clerk.

Il metodo consigliato è utilizzare l’ CRUD API in quanto ti permette di automatizzare completamente l’operazione.

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

Semplicemente crea una chiamata POST all’endpoint /orders nel tuo sistema ERP o webshop, esegui il job a intervalli regolari, es. una volta al mese, e sarai in grado di utilizzare ordini offline per aumentare le tue recommendations online e i tuoi search results.

In alternativa, puoi caricare manualmente un file CSV, senza dover scrivere codice.

Puoi leggere di più sui CSV files here.

Conversione valuta #

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

Un modo semplice per farlo funzionare è descritto di seguito.

Inviare oggetti prezzo #

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

Il modo più semplice per farlo è inviarli come un string-encoded JSON object 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,
    // String-encoded JSON examples
    "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,
    // String-encoded JSON example
    "prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}",
    "list_prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}"
  }
]

Create 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 price-dict come argomento e restituisce il prezzo per una specifica currency, sulla base della logica frontend che scegli.

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

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

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

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

Questo metodo è utilizzabile se puoi cercare i prezzi dal tuo server, direttamente da una funzione JavaScript nel frontend basata su un product ID e un customer ID.

Per mostrare prezzi individuali per cliente, il codice dovrebbe essere eseguito subito dopo la risposta.

Di seguito un esempio di un semplice evento.

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

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

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

Prezzi per singolo cliente #

Se hai bisogno di mostrare prezzi completamente unici in base al cliente loggato, devi impostare un Event che inserisce il prezzo corretto dopo che i prodotti sono stati renderizzati.

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

Questo approccio presuppone che tu possa cercare i prezzi dal tuo server con una chiamata AJAX nel frontend basata su un e.g. un product ID e un customer ID.

Il modo migliore è innanzitutto creare un contenitore di prezzo segnaposto nel tuo Design, per poi sostituirlo con il prezzo restituito dalla tua chiamata AJAX.

Un esempio:

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

Poi puoi usare l’evento Clerk per attendere che i prodotti siano renderizzati, fare una richiesta al tuo server di prezzi usando l’ID prodotto e l’ID del cliente, prima di sostituirlo nell’HTML.

Qui un esempio di come farlo:

<script>
  var customer_id = INSERT_CUSTOMER_ID;
  Clerk("on", "rendered", function(content, data){
    for (i = 0; i < data.product_data.length; i++) {
        var product = data.product_data[i];
          var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
          let price_container = document.querySelector(`[data-clerk-product-id='${product.id}'] .clerk-price`);
          price_container.innerText = custom_price;
      }
  })
  </script>

Il codice sopra presuppone che tu possa identificare un cliente loggato 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 usato per mirare al giusto prodotto 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, “Loading price…” in questo esempio, con il prezzo restituito dalla tua chiamata AJAX.

Prezzi per gruppo di clienti #

L’impostazione di customer group prices consiste in 4 passaggi:

Includi i vari prezzi nel data feed.
Includi una variabile che recupera l’attuale customer group ID.
Crea una function per recuperare il prezzo rilevante.
Mostra il prezzo nel Design.

Includi oggetti prezzo #

Inizia aggiungendo un attributo a tutti i prodotti che contenga tutte le varie opzioni di prezzo, assicurandoti di correlare ogni prezzo a un determinato gruppo di clienti.

Questo dovrebbe essere inviato come un oggetto JSON string-encoded. Per esempio:

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

Customer ID variabile #

Aggiungi una dinamica global variable a Clerk.js che recupera l’customer-group ID del cliente corrente e lo aggiunge come valore.

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

Per esempio, un utente che dovrebbe vedere il prezzo per il gruppo 2, quindi l’ID dovrebbe essere “GROUP2”.

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

Recupera prezzo #

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

Fai questo scrivendo una funzione che recupera il prezzo dal specifico customer group come chiave nel price-dict basato sull’ID del customer_group.

Aggiungilo nel config 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;
    }
    }
  }
});

Mostra prezzo #

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

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

Autenticazione HTTP #

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

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

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

In my.clerk.io > Data > Configuration, aggiorna l’URL di importazione come segue:

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

Nessun ordine tracciato #

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

Clerk deve monitorare continuamente le vendite dal webshop per mantenere i risultati aggiornati rispetto 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 quando si utilizza una configurazione 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 Sales-tracking sulla tua Pagina di conferma ordine.

Questi sono necessari per tracciare le vendite in generale quando si usa una configurazione 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 della chiamata di vendita inviata a Clerk dopo un acquisto.

Per debuggarlo, dovrai effettuare un test order.

Tuttavia, in alcuni casi potrebbe essere correlato allo script di sales tracking stesso e può essere debugged guardando i log in my.clerk.io > Developers > Logs.

Se il sales-tracking sta fallendo a causa di un errore nel tuo script, spesso potrai vedere l’errore in questa pagina.

Clicca su Details per vedere di più.

Se non riesci a vedere errori nei log, il modo più semplice per identificare altri problemi di sales-tracking è effettuare un test order.

Debugging di un test order #

In questo esempio utilizziamo Chrome per mostrare come debuggare il tracciamento delle vendite con un test order, ma altri browser hanno funzionalità simili.

Nel tuo webshop, aggiungi un paio di prodotti al carrello.
Procedi a Checkout.
Prima di effettuare l’ordine, apri la Console del tuo browser.
Trova Network, e cerca per “clerk”.
Effettua l’ordine, così vedrai la order confirmation page.
Clicca la chiamata che inizia con sale (di solito sale?key=…).

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

Clicca Preview per identificare eventuali errori che possano causare che le vendite non vengano tracciate.

Di seguito sono comuni errori associati al sales-tracking.

Sintassi prodotti non valida #

Questo errore si verifica se gli product IDs che invii hanno una sintassi errata.

Gli errori più comuni sono:

Gli ID prodotto sono string-encoded nel sales-tracking, ma stai usando Integers in Clerk o vice-versa.
L’elenco degli ID prodotto contiene caratteri di formattazione testuale invece di JSON puro: "products":[\"id\":\"123-m\"].

Argomento mancante #

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

Assicurati di includere tutti i necessari data attributes in the sales-tracking.

Nessuna chiamata effettuata #

Se non riesci a vedere la chiamata a sale anche con entrambi gli script installati, allora qualcosa ha fatto sì che lo script Clerk.js venga caricato in modo incorretto.

Prova seguendo questi passaggi:

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

Uncaught ReferenceError: Clerk is not defined

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

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

Nessun impatto Clerk #

Se riesci a tracciare le vendite in my.clerk.io, ma nessuna di esse viene mostrata come influenzata da Clerk, potresti avere un errore nella tua configurazione di visitor-tracking / click-tracking.

Inizia assicurandoti che visitor-tracking funzioni, facendo quanto segue:

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

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

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

Impostazioni API #

Se imposti Clerk con una integrazione personalizzata direttamente con l’API, devi attivare attivamente il visitor-tracking.

Leggi come farlo in questo API article.

Wrong product IDs #

Per visitor-tracking funzionare, il click- e il sales-tracking devono tracciare gli stessi ID prodotto di quelli che ricevi nell’importer.

Di solito se questo non funziona è perché stai tracciando ID di variante invece di ID genitore o lo SKU invece dell’ID.

Per verificare se questo è il problema fai quanto segue:

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

Usalo per configurare il tuo sales-tracking affinato con i corretti ID prodotto.

Modifiche degli ID visitatore #

Clerk usa un visitor ID per identificare ogni sessione individuale, inclusi i prodotti su cui fanno clic e che acquistano.

Di conseguenza, gli ID dovrebbero rimanere gli stessi per tutta la sessione, e preferibilmente anche tra più sessioni.

Questo ID visitatore è creato automaticamente quando si usa Clerk.js per l’impostazione, ma se usi una configurazione API, o personalizzi i tuoi visitor IDs, potresti cambiarlo accidentalmente.

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

Apri le impostazioni Network nel browser e restringi i risultati a “clerk”.
Inizia controllando eventuali chiamate undefined legate a search o recommendations.
In payload puoi controllare l’attuale Visitor ID. Potrai farlo per tutte le chiamate associate a Clerk.
Procedi a cliccare sul prodotto e a effettuare un ordine con quel prodotto.
Nella pagina Order Success, controlla nuovamente la tua Network e trova la chiamata a sale?.
Assicurati che visitor nel payload corrisponda al Visitor ID visto al passo 3.

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

Una causa comune è la rigenerazione degli ID per ogni nuova pagina caricata.

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

Upgrade a Clerk.js 2 #

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

Rende più facile installare Clerk su qualsiasi webshop.

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

Le due principali differenze in Clerk.js 2 sono:

Le Design in my.clerk.io usano il Liquid, ma possono anche essere create facilmente usando l’Editor di Design.
Lo script deve essere inserito proprio prima del tag </head> nel modello del tuo webshop.

Crea design #

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

È possibile creare i tuoi Clerk.js 2 Designs sia rifacendoli nel Editor di Design, sia convertendo i tuoi vecchi Design del codice in Liquid, come spiegato nella guida qui sotto.

Di seguito è riportata una descrizione su come convertire i tuoi vecchi design del codice in Liquid.

Opzione Editor di Design #

Vai a my.clerk.io > Recommendations/Search > Designs > New Design.
Seleziona un tipo di design diverso da Blank e dagli un nome. Consigliamo di aggiungere “V2” in modo che sia ovvio che stai usando i design Clerk.js 2.
Nell’ Editor di Design, fai clic su uno dei elementi esistenti come nome, immagine, pulsante, ecc. per modificarlo, oppure aggiungi nuovi elementi al Design.
Fai clic su Pubblica Design quando hai finito, e vai alla Fase 2 della guida.
Vai a Recommendations/Search > Elements e modifica il tuo Clerk Content per utilizzare il tuo nuovo Design, quindi clicca Update Content.
Questo farà sì che temporaneamente non compaiano nel tuo negozio online, finché non avrai inserito Clerk.js 2 come descritto più sotto 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 a my.clerk.io > Recommendations/Search > Designs > New Design.
Seleziona Blank > Code e dagli un nome. Consigliamo di aggiungere “V2” in modo che sia chiaro che stai usando i design Clerk.js 2.
Fai clic su Crea Design.
Questo ti darà un design vuoto con HTML del prodotto e CSS che puoi utilizzare.
Torna alla panoramica del design e fai clic su Edit Design per il tuo Design Clerk.js 1. Si consiglia di farlo in una nuova scheda in modo da poter copiare facilmente il codice.
Copia dal tuo vecchio Design Clerk.js 1 al tuo nuovo Design Clerk.js 2.
- Noterai che nel tuo nuovo design non c’è Container Code.
- Questo perché Liquid usa for loops per renderizzare tutti i prodotti.
- Copia il tuo vecchio Product HTML inside the for-loop, il vecchio Container Code around esso e copialo anche il CSS.
Converti il Design nella sintassi Liquid. La differenza principale è che i vecchi Design usavano la sintassi {{ formatter attribute }} mentre la sintassi v2 è {{ product.attribute | formatter }}.
Esamina tutti i tuoi attributi e cambiali nel nuovo formato.
Se stai usando 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 codice contenitore nella versione Clerk.js 2 poiché non sono più supportate.
Di seguito è riportato un esempio di un 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>

Fai clic su Aggiorna Design per salvare le modifiche.
Vai a Recommendations/Search > Elements e cambia il blocco Content per utilizzare il tuo nuovo Design.
Fai clic su Aggiorna Content. Questo farà temporaneamente sì che non compaiano nel tuo negozio online, finché non avrai terminato con Fase 2. Scegli il nuovo Design per tutto il Content che deve essere aggiornato.

Sostituzione script #

Individua il file modello che viene utilizzato per mostrare tutte le pagine del negozio online, e dove si trova vicino al fondo lo script Clerk.js originale.
Rimuovi lo script Clerk.js vecchio 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 a my.clerk.io > Developers > Tracking Code.. Questo contiene il codice Clerk.js 2.
Copia questo codice, inseriscilo appena prima del tag </head> nel template, quindi salvalo.

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

Puoi consultare la documentazione completa per Clerk.js 2 qui.

Gestione di require.js #

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

In alcune configurazioni, Require.js impedisce a Clerk.js di caricarsi, il che significa che nessun slider o risultato di ricerca verrà mostrato.

Quando ciò accade, nel tuo console verrà visualizzato il seguente errore:

Uncaught ReferenceError: Clerk is not defined

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

Includere in Require.js #

Il miglior approccio è far riconoscere Clerk da Require.js.

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

Ignorare Require.js #

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

Puoi farlo inserendo window.__clerk_ignore_requirejs = true; all’inizio dello script di tracciamento:

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.