FAQ

Problemi con l’integrazione Shopify? Questa FAQ copre i problemi più comuni e le loro soluzioni, dalla conversione di valuta alla posizione dei file del tema.

Conversione di valuta #

La Conversione di valuta integrata di Shopify rende facile leggere il simbolo della valuta e il tasso di cambio dal webshop.

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

Soluzione standard #

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

Questo esempio utilizza il nostro linguaggio di template standard qui.

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

Gli esempi seguenti mostrano come funzionano i diversi componenti.

Editor di Design #

1. Crea un componente Text dove vuoi che venga visualizzato il prezzo.

2. Inserisci il seguente codice Liquid per mostrare il prezzo in base al currency converter all’interno del componente di 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 dovresti poter vedere i prezzi convertiti e il simbolo di valuta nel tuo design.

Soluzione API custom #

Disclaimer: Questa è una soluzione molto personalizzata per ottenere conversioni di prezzo se non ci sono dati dall’API Shopify. Utilizzala solo se stai usando una configurazione specifica e personalizzata per le conversioni di prezzo basate sui cambiamenti geo-IP.

Questa è la documentazione per la soluzione frontend in Github.

Questa sezione spiega come ottenere dati contestuali in tempo reale da visualizzare nei contenuti restituiti dall’API di Clerk.

Il pattern di design è composto dalle seguenti parti:

• Una collection contenente tutti i prodotti.

• Un layout alternativo per visualizzare le informazioni della collection come JSON.

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

• Uno Snippet JavaScript che utilizza i dati per gli ID prodotto rilevanti in un determinato risultato e li inserisce all’interno di una div nel template.

Creare una collection #

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

La collection dovrebbe essere chiamata Clerk api, in modo da ricevere la route /collection/clerk-api frontend.

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

Creare un layout alternativo #

Crea un layout alternativo per mostrare i tuoi dati usando la collection.

Per farlo, modifica il codice del tema che desideri utilizzare.

Nella sezione template sulla sinistra, premi Add new Template.

Nella finestra pop-up, seleziona collection come tipo di risorsa.

Seleziona liquid come tipo di file.

Scrivi json nel campo in basso, così che il nome del template creato sia collection.json.liquid.

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

Puoi aggiungere campi al prodotto in questo template come necessario.

Aggiungere la classe JS #

Per recuperare i dati dalla tua collection e prepararli per l’uso, inserisci tutto il contenuto di index.js nella cartella class di questo progetto, dentro il tag script che contiene Clerk.js che hai inserito in theme.liquid.

Dovrebbe assomigliare a questo:

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

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

Il tempo prima dell’invalidazione è di 12 ore dall’ultima generazione dei dati.

Qualsiasi cambiamento nel contesto della valuta invalida anche i dati.

Aggiungere la funzione template #

Includi il file template.js nel template di design utilizzato.

La funzione recupera i dati quando disponibili e li colloca in specifici elementi figli all’interno di ciascuna tile prodotto.

L’esempio include i campi list_price e price.

Nota: Se hai bisogno di usare campi diversi da price e list_price, li aggiungi in collection.json.liquid e poi modifichi template.html e template.js perché utilizzino anche quei campi. Non dovresti mai dover modificare la Classe descritta nello step 3.

Valute multiple #

Nota: Questa funzione è deprecata. Lo script di tracking pixel la sostituisce. Segui i passi 4 e 5 della Guida all’avvio di Shopify.

Quando utilizzi più valute nel tuo webshop Shopify, è importante che gli ordini vengano convertiti in un’unica valuta per garantire un’accurata performance di revenue in Clerk.

Nei dashboard di Clerk, la tua performance verrà sempre riportata in un’unica valuta.

Per esempio, se utilizzi sia GBP che DKK nel tuo webshop, i dashboard riporteranno le performance tutte in GBP o tutte in DKK.

Ecco perché è importante tradurre in una sola valuta—dopotutto, non vorresti che un acquisto da 600 GBP fosse letto da Clerk come 600 DKK!

Per assicurarti che i tuoi dashboard Clerk mostrino i dati di vendita in una valuta comune, puoi modificarlo all’interno del codice di Sales Tracking aggiunto al tuo store durante l’installazione di Clerk.

Accedi a Settings > Checkout > Additional Scripts nel backend di Shopify, e cambia il codice di 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;
        // Add more cases as needed
    }
    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 -->

Ricorda di mantenere invariato lo script di Visitor Tracking—lo trovi subito sotto il codice di Sales Tracking.

Ora i tuoi ordini dovrebbero arrivare nei dashboard Clerk in una sola valuta.

Trovare i file del tema #

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

Ogni tema funziona allo stesso modo—personalizzi i file del tema per ottenere il risultato desiderato sul tuo store.

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

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

Se non conosci il nome del file che ti serve, puoi usare il campo di ricerca per individuarlo.

Per esempio, se cerchi il file contenente il codice della pagina di ricerca, probabilmente conterrà ‘search’ nel nome del file.

Se non sei sicuro di aver trovato il file giusto, puoi confrontare l’HTML del file tema con l’HTML della pagina corrispondente e verificare se combaciano.

Puoi farlo su Google Chrome cliccando col tasto destro su qualsiasi sezione della pagina e selezionando ‘Ispeziona’.

Puoi quindi ispezionare l’HTML della pagina e verificare se class/ID degli elementi coincidono tra il file e la pagina.

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

Raccomandazioni nel cassetto del carrello #

L’installazione da parte di uno sviluppatore Shopify è fortemente raccomandata.

Questa guida illustra una soluzione altamente personalizzata che può comportarsi diversamente sui vari temi Shopify. È studiata specificamente per i temi in cui il carrello è parte del DOM su ogni pagina ma rimane nascosto finché l’utente non lo apre.

Visualizzare le Recommendations di Clerk nel cassetto del carrello su Shopify è un ottimo modo per mostrare 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 dove si trova il template del cassetto carrello (solitamente chiamato cart-drawer.liquid o simile).

3. Inserisci uno snippet Recommendations di Clerk da Recommendations > Elements.

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. Oltre allo snippet sopra, inserisci uno script per renderizzare le Recommendations di Clerk quando l’utente apre il carrello. Un approccio possibile prevede l’uso di MutationObserver. Lo script qui sotto include tutti questi elementi, dandoti un esempio di come approcciare la soluzione:

<script>
    // Seleziona il nodo che sarà osservato per le mutazioni
    const targetNode = document.querySelector("cart-drawer.drawer");

    // Aggiungi tutti i nomi di classe del carrello quando viene aperto
    const targetNodeClasses = "drawer animate active";

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

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funzione per recuperare i dati del 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 observer collegato al callback
    const clerk_observer = new MutationObserver(callback);

    // Avvia l’osservazione del target node per le mutazioni configurate
    clerk_observer.observe(targetNode, config);
</script>

Il tuo file del cassetto carrello dovrebbe apparire così:

Autenticazione HTTP #

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

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

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

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

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

Errori comuni di sincronizzazione #

Durante l’importazione dei dati con l’integrazione Shopify, il server del tuo webshop è responsabile dell’invio dei dati di prodotto, categoria e vendite a Clerk.

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

Di seguito una lista degli errori più comuni e come risolverli.

401 Unauthorized #

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

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

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

Errore di permessi #

Questo errore di solito si verifica se non hai assegnato i permessi di lettura a Store content like articles, blogs, comments, pages and redirects nella tua Private App.

Come risolverlo:

1. Accedi a Shopify e vai su Apps > Manage Private Apps > Clerk.io (oppure 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 di require.js #

Questa guida si applica solo con Clerk.js 1.

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

Quando ciò accade, otterrai il seguente errore in console:

Uncaught ReferenceError: Clerk is not defined

Sono due i modi per gestire Require.js. Entrambi richiedono di apportare modifiche al tracking-script, normalmente inserito in index.liquid.

Includere in Require.js #

L’approccio migliore è fare in modo che Require.js riconosca Clerk.

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

Ignorare Require.js #

Se la soluzione sopra non funziona, puoi ignorare Require.js.

Per farlo, inserisci window.__clerk_ignore_requirejs = true; in cima al tracking script:

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 l’installazione di Clerk su qualsiasi webshop più semplice.

Tuttavia, poiché le due versioni funzionano in modo leggermente diverso, occorre seguire questi passaggi per l’aggiornamento.

Le due principali differenze di Clerk.js 2 sono:

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

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

Creare i design #

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

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

• Usa l’intuitivo Design Editor per creare nuovi Design, come descritto nei passi successivi.

• Converti i tuoi vecchi Design. Segui questa guida per vedere come fare.

Opzione Design Editor #

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

2. Nella schermata successiva, dai al Design un Nome (si consiglia di aggiungere “V2” per evidenziare che stai usando Clerk.js 2).

3. Scegli il tipo di Design.

4. Clicca Publish Design quando hai finito, e vai a Step 2 nella guida.

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

6. Clicca su Publish. Questo temporaneamente farà si che non vengano mostrati sul tuo webshop fino a che non avrai completato lo Step 2. Scegli il nuovo Design per tutti gli Element che desideri aggiornare.

7. Vai su Recommendations/Search > Elements e cambia il tuo Clerk Element per usare il nuovo Design.

Sei ora pronto a passare a Clerk.js 2.

Sostituire lo script #

1. Individua il file template usato per mostrare tutte le pagine del webshop, e dove trovi lo script Clerk.js originale quasi in fondo al file.

2. Rimuovi il vecchio script dal file:

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

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

5. Salva il template.

Complimenti! Ora stai usando il nuovo setup migliorato 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 Cliente #

Quando ti aiutiamo a configurare o risolvere problemi di tracking degli ordini tramite Shopify pixels, potremmo chiedere l’accesso all’area eventi cliente nell’admin di 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 l’utente staff 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 permettono al nostro team di visualizzare la sezione Customer events e di gestire il pixel di Clerk così da poter verificare che il tracking degli ordini funzioni correttamente.