FAQ

Hai problemi con la tua integrazione Shopify? Questa FAQ copre i problemi più comuni e le loro soluzioni, dalla conversione di valuta alle posizioni dei file tema.

Conversione valuta #

La Conversione Valuta integrata di Shopify rende semplice leggere il simbolo e il tasso di cambio dal webshop.

Di default, Clerk.js per Shopify viene fornito con un formatter che funziona purché la tua app di terze parti utilizzi l’oggetto valuta integrato di Shopify.

Soluzione standard #

Devi utilizzare un formatter nei tuoi Designs per convertire i prezzi.

Questo esempio usa il nostro linguaggio di template standard qui.

Quando si utilizzano conversioni di valuta e simboli, Clerk.js rileva impostazioni come lingua, valuta e codice paese.

I seguenti esempi mostrano come funzionano i diversi componenti.

Editor design #

1. Crea un componente Text dove vuoi mostrare il prezzo.

2. Aggiungi il seguente codice Liquid per mostrare il prezzo basato sul currency converter all’interno del componente testo:

{{ currency_symbol }}{{ item.price | currency_converter }}

Modalità codice #

1. In my.clerk.io, vai su Search/Recommendations > Designs e clicca su Edit Design per il tuo design.

2. Sostituisci il formatter money o money_eu esistente per i prezzi con currency_converter.

3. Clicca su Update Design.

4. Ora sarai in grado di vedere i prezzi convertiti e il simbolo valuta nel tuo design:

Soluzione API personalizzata #

Avviso: Questa è una soluzione molto personalizzata per ottenere conversioni di prezzo se non ci sono dati dalla Shopify API. Usala solo se hai una configurazione specifica e personalizzata per conversioni prezzi basate su cambiamenti geo-IP.

Questa è la documentazione della soluzione frontend su Github.

Questa sezione spiega come ottenere dati contestuali in tempo reale da mostrare all’interno dei contenuti restituiti dalla Clerk API.

Il pattern di design è composto dalle seguenti parti:

• Una collezione contenente tutti i prodotti.

• Un layout alternativo per renderizzare le informazioni collezione come JSON.

• Una Classe JavaScript che raccoglie i dati resi disponibili nella collezione.

• Uno Snippet JavaScript che consuma i dati per gli ID prodotto rilevanti in un dato risultato e li posiziona in un div nel template.

Crea collezione #

Per assicurarti di avere una collezione con tutti i possibili prodotti, crea una collezione con una condizione soddisfatta da tutti i prodotti.

La collezione deve essere chiamata Clerk api, questo farà sì che riceva il percorso /collection/clerk-api frontend.

La condizione per la collezione dovrebbe essere qualcosa come price > -1000000.

Crea layout alternativo #

Crea un layout alternativo per mostrare i tuoi dati utilizzando la collezione.

Per farlo, modifica innanzitutto il codice tema per il tema che vuoi utilizzare.

Nella sezione template a sinistra, premi Add new Template.

Nel popup, seleziona collection per il resource type.

Seleziona liquid per il file type.

Scrivi json nel campo più in basso, in modo che il nome del template creato sia collection.json.liquid.

Il contenuto di questo file deve essere il file collection.json.liquid che si trova nella cartella liquid per questo progetto.

Puoi aggiungere campi al prodotto in questo template come necessario.

Aggiungi classe JS #

Per prelevare i dati dalla tua collezione e prepararli all’uso, posiziona il contenuto di index.js nella cartella class di questo progetto, all’interno del tag script contenente Clerk.js che hai posizionato in theme.liquid.

Dovrebbe apparire così:

<script>
  // Clerk.js Injection Code
  // Clerk Config with Key and Formatters
  // Class from this project
  clerk_shopify_api.init()
  // Finalmente, init() della classe per assicurarsi che venga eseguita quando la pagina si carica.
</script>

Questa classe invaliderà i dati in base a timestamp e valute, senza necessità di modificare il codice.

Il tempo prima della invalidazione è di 12 ore dall’ultimo aggiornamento dati.

Qualsiasi cambiamento nel contesto valuta invalida i dati.

Aggiungi funzione template #

Includi il template.js nel template di design utilizzato.

La funzione preleva i dati disponibili e li posiziona in elementi figli specifici all’interno di ogni tile prodotto.

L’esempio include i campi list_price e price.

Da notare: Se devi utilizzare campi che sono diversi da price e list_price, aggiungili in collection.json.liquid e poi modifica template.html e template.js per utilizzarli. Non dovresti mai aver bisogno di modificare la Classe descritta al passo 3.

Più valute #

Nota: Questa funzione è deprecata. Lo script pixel tracking la sostituisce. Segui i passi 4 e 5 dalla Guida introduttiva a Shopify.

Quando usi più valute nel tuo webshop Shopify, è importante che gli ordini vengano convertiti in una sola valuta, così che la tua performance relativa alle entrate sia precisa in Clerk.

Nelle dashboard di Clerk, la performance verrà sempre riportata in una sola valuta.

Ad esempio, se usi sia GBP che DKK nel tuo negozio, le dashboard riporteranno la performance tutta in GBP oppure tutta in DKK.

Ecco perché convertire tutto in un’unica valuta è importante—dopotutto, non vorresti che un acquisto da 600 GBP fosse letto da Clerk come 600 DKK!

Per assicurarti che le tue Dashboard Clerk mostrino i dati di vendita in un’unica valuta comune, questo può essere regolato all’interno del codice di Sales Tracking che hai aggiunto al tuo store quando hai installato Clerk.

Vai su Settings > Checkout > Additional Scripts nel backend Shopify e modifica il codice Sales Tracking da questo:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script>
  (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: 'yourPublicKey'
  });
  let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
  document.addEventListener('DOMContentLoaded', (e)=> {
      clerk_order_id = window.Shopify.checkout.order_id
  });
  if ( isNaN( clerk_order_id ) ) {
      if(window.Shopify){
          clerk_order_id = window.Shopify.checkout.order_id
      }
  }
  let log_sale_retry = setInterval(() => {
      if( ! isNaN( clerk_order_id ) ){
          Clerk('call', 'log/sale/shopify', {
              sale: clerk_order_id
          });
          clearInterval(log_sale_retry);
      }
  }, 100);
  </script>
  <!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

A questo:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script>
    (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);
    let clerkLocale = Shopify.locale;
    let publicKey;
    switch (clerkLocale) {
        case 'en':
            publicKey = 'yourPublicKeyEN';
            break;
        case 'fr':
            publicKey = 'yourPublicKeyFR';
            break;
        case 'de':
            publicKey = 'yourPublicKeyDE';
            break;
        // Aggiungi altri casi se necessario
    }
    Clerk('config', {
        key: publicKey
    });
    let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
    document.addEventListener('DOMContentLoaded', (e) => {
        clerk_order_id = window.Shopify.checkout.order_id
    });
    if (isNaN(clerk_order_id)) {
        if (window.Shopify) {
            clerk_order_id = window.Shopify.checkout.order_id
        }
    }
    let log_sale_retry = setInterval(() => {
        if (!isNaN(clerk_order_id)) {
            Clerk('call', 'log/sale/shopify', {
                sale: clerk_order_id
            });
            clearInterval(log_sale_retry);
        }
    }, 100);
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Assicurati di mantenere uguale lo script di Visitor Tracking—si trova appena sotto il codice di Sales Tracking.

I tuoi ordini ora dovrebbero apparire nelle dashboard Clerk in un’unica valuta.

Trovare file tema #

Shopify offre oltre 100 temi diversi per stilizzare e personalizzare il tuo webshop.

Ogni tema funziona nello stesso modo—personalizzi i file tema per ottenere un certo risultato nel tuo negozio.

Tuttavia, i nomi dei file tema cambiano da tema a tema.

Shopify ti fornisce un campo di ricerca per trovare facilmente e rapidamente il file tema che stai cercando.

Se non conosci il nome del file che cerchi, puoi usare il campo di ricerca per aiutarti a trovarlo.

Per esempio, se cerchi il file relativo alla pagina search, probabilmente il nome del file conterà ‘search’.

Se non sei sicuro di aver trovato il file corretto, puoi confrontare l’HTML nel file tema con l’HTML della pagina rilevante per verificare se coincidono.

Questo può essere fatto in Google Chrome cliccando con il tasto destro su qualsiasi sezione della pagina e selezionando “Ispeziona”.

Puoi quindi ispezionare l’HTML sulla pagina e vedere se class/ID degli elementi coincidono tra file e pagina.

Se hai bisogno di ulteriore assistenza, puoi anche contattare il nostro team supporto.

Cart drawer recommendations #

Si raccomanda vivamente l’installazione da parte di uno sviluppatore Shopify.

Questa guida descrive una soluzione molto personalizzata che può comportarsi diversamente su vari temi Shopify. È progettata specificatamente per temi dove il carrello fa parte del DOM in ogni pagina ma rimane nascosto fino all’apertura da parte dell’utente.

Mostrare le Clerk Recommendations nel carrello a scomparsa su Shopify è un ottimo modo per proporre prodotti aggiuntivi agli acquirenti prima che inizino il processo di checkout.

1. Modifica il codice del tuo tema Shopify in Online Store > Themes > Edit code.

2. Trova il file del template carrello drawer (di solito chiamato cart-drawer.liquid o simili).

3. Inserisci uno snippet Clerk Recommendations da Recommendations > Content.

4. Rinomina la classe da clerk per controllare il rendering. Ad esempio chiamandola clerk_m:

<span class="clerk_m" data-template="@cart-others-also-bought" data-products="[{% for line_item in cart.items %}{% if forloop.index0 > 0 %}, {% endif %}{{ line_item.product.id }}{% endfor %}]"></span>

5. Assieme allo snippet sopra, includi uno script per renderizzare le Clerk Recommendations quando l’utente apre il carrello. Un approccio è usare MutationObserver. Lo script qui sotto include tutti questi elementi, dandoti un esempio di come fare:

<script>
    // Seleziona il nodo da osservare per le mutazioni
    const targetNode = document.querySelector("cart-drawer.drawer");

    // Tutti i nomi delle classi del cart drawer, quando è aperto
    const targetNodeClasses = "drawer animate active";

    // Opzioni per l’osservatore (quali mutazioni osservare)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funzione per ottenere dati dal carrello
    async function fetchCartData() {
        const response = await fetch("/cart.js");
        const data = await response.json();
        let itemsID = [];
        let cartItems = data.items;
        for (var i = 0; i < cartItems.length; i++) {
            itemsID.push(cartItems[i].product_id);
        }
        return itemsID;
    }

    // Callback da eseguire quando vengono osservate mutazioni
    const callback = async (mutationList, observer) => {
        for (const mutation of mutationList) {
            if (mutation.type === "attributes") {
                if (targetNode.className == targetNodeClasses && !cartFetched) {
                    cartFetched = true;
                    try {
                        const itemsID = await fetchCartData();
                          if (JSON.stringify(previousitemsID) != JSON.stringify(itemsID)) {
                            await Clerk('content', '.clerk_m', 'param', { products: itemsID })
                            previousitemsID = itemsID
                          }
                    } catch (error) {
                        console.error(error);
                    } finally {
                        cartFetched = false;
                    }
                }

            }
        }
    };

    // Crea un’istanza observer collegata alla funzione di callback
    const clerk_observer = new MutationObserver(callback);

    // Avvia l’osservazione delle mutazioni configurate sul nodo target
    clerk_observer.observe(targetNode, config);
</script>

Il tuo file cart drawer dovrebbe apparire così:

Autenticazione HTTP #

L’autenticazione HTTP è usata spesso su siti di staging per evitare visite indesiderate.

Questo bloccherà l’importatore Clerk e mostrerà un errore 401 Unauthorized nel registro di sync.

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

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

https://USER:PASS@www.ewoksRus.com

Errori comuni di sincronizzazione #

Quando importi dati con l’integrazione Shopify, il server del tuo webshop è responsabile di inviare a Clerk i dati relativi a prodotti, categorie e vendite.

Tuttavia, in alcuni casi, la configurazione del server può impedire all’Importer di accedere, causando un errore in Data Sync.

Qui sotto trovi una lista degli errori più comuni e come risolverli.

401 Unauthorized #

Questo errore si verifica se il tuo webshop o ambiente di sviluppo richiede autenticazione HTTP.

Si risolve inserendo Username e Password come parte dell’Import URL:

http://username:password@awesomeshop.myshopify.com

Errore permessi #

Questo errore di solito si verifica se non hai concesso il Read Access a Store content like articles, blogs, comments, pages and redirects nella tua App privata.

Per risolverlo:

1. Accedi a Shopify e vai su Apps > Manage Private Apps > Clerk.io (o il nome che hai dato all’App).

2. Scorri fino a Admin API Permissions e clicca su Review disabled Admin API permissions.

3. Trova Store content like articles, blogs, comments, pages and redirects e scegli Read access:

4. Scorri in cima alla pagina e clicca su Save.

Gestione require.js #

Questa guida si applica solo se si usa Clerk.js 1.

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

Quando ciò accade, verrà mostrato questo errore nella console:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi richiedono modifiche al tracking-script, che normalmente viene inserito in index.liquid.

Includere in Require.js #

Il modo migliore è tentare di far riconoscere Clerk da Require.js.

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

Ignora Require.js #

Se la soluzione precedente non funziona, è possibile ignorare Require.js.

Puoi farlo inserendo window.__clerk_ignore_requirejs = true; in cima allo script di tracking:

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

Aggiornamento 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, dovrai seguire questi passaggi per aggiornare con successo.

Le due differenze principali in Clerk.js 2 sono:

• I Designs in my.clerk.io usano il linguaggio di template Liquid, ma possono essere creati facilmente anche usando il Design Editor.

• Lo script deve essere inserito appena prima del tag </head> nel template del tuo webshop.

Crea i designs #

Poiché Clerk.js 2 utilizza un approccio diverso ai Designs, sarà necessario crearne di nuovi.

Puoi creare i tuoi Designs Clerk.js 2 in due modi:

• Usa l’intuitivo Design Editor per creare nuovi Designs, come descritto nei punti seguenti.

• Converti i tuoi vecchi Designs. Segui questa guida per vedere come farlo.

Opzione Design Editor #

1. Vai su my.clerk.io > Recommendations/Search > Designs > New Design.

2. Nella schermata seguente, dai un Nome al Design (consigliamo di aggiungere “V2” per rendere evidente che si tratta di Clerk.js 2).

3. Scegli il Tipo di Design.

4. Clicca su Publish Design quando hai terminato e passa allo Step 2 della guida.

5. Nel Design Editor, clicca su uno degli elementi esistenti come nome, immagine, bottone, ecc. per modificarlo, o aggiungi nuovi elementi per fornire più informazioni sui prodotti.

6. Clicca su Publish. Questo temporaneamente causerà la scomparsa dai webshop finché non avrai completato lo Step 2. Scegli il nuovo Design per tutti i Content che dovrebbero essere aggiornati.

7. Vai su Recommendations/Search > Content e modifica il tuo Clerk Content per usare il nuovo Design.

Ora sei pronto per passare a Clerk.js 2.

Sostituisci script #

1. Trova il file template che viene usato per mostrare tutte le pagine del webshop, dove si trova l’originale script Clerk.js vicino al fondo.

2. Rimuovi il vecchio script dal file:

3. Vai su my.clerk.io > Developers > Tracking Code.. Questa pagina ora contiene il tuo codice di tracking Clerk.js 2.

4. Copia questo codice e inseriscilo appena prima del tag </head> nel template:

5. Salva il template.

Complimenti! Ora stai usando la configurazione molto migliorata di Clerk.js 2!

Puoi vedere la documentazione completa di Clerk.js 2 qui: https://docs.clerk.io/docs/clerkjs-quick-start

Concedi a Clerk l’accesso agli Eventi Clienti #

Quando ti aiutiamo a configurare o risolvere problemi di tracciamento ordini tramite i pixel Shopify, potremmo chiederti l’accesso alla sezione eventi cliente nell’admin Shopify.

Segui questi passaggi per concedere i permessi necessari:

1. In Shopify, vai su Settings > Users and permissions.
2. Clicca sul membro staff chiamato Clerk.io (o sullo staff user che vuoi aggiornare).
3. Scorri fino a Store settings e abilita:
   • View customer events
   • Manage and add custom pixels
4. Clicca su Save.

Questi permessi consentono al nostro team di visualizzare la sezione eventi cliente e gestire il pixel Clerk così possiamo verificare che il tracciamento ordini funzioni correttamente.