FAQ

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

Dimensioni immagini #

Gli URL delle immagini Shopify possono includere dimensioni fisse dalla sincronizzazione, per esempio _600x600.

Se il tuo design necessita di una dimensione diversa dell’immagine a seconda della posizione, puoi rimuovere la dimensione fissa sincronizzata e richiedere una nuova larghezza nell’URL.

Esempio (sostituisci 600x600 con la dimensione predefinita delle immagini che hai configurato):

{{ product.image
  | replace '_600x600.' '.'
  | replace '?v=' '?width=350&v=' }}

Questo è utile quando uno stesso design usa più formati di immagine (ad esempio le schede prodotto e i grandi spazi hero) e vuoi evitare di sincronizzare più attributi immagine.

Conversione valuta #

La Conversione Valuta integrata di Shopify permette di leggere facilmente il simbolo della valuta e il tasso di cambio dal webshop.

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

Soluzione standard #

È necessario utilizzare un formatter nei tuoi Designs per convertire i prezzi.

Questo esempio utilizza il nostro linguaggio template standard qui.

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

Gli esempi seguenti mostrano come funzionano i diversi componenti.

Editor Design #

1. Crea un componente Text nel punto in cui desideri mostrare il prezzo.
2. Aggiungi il seguente codice Liquid per mostrare il prezzo usando il convertitore di valuta 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 esistente money o money_eu nei prezzi con currency_converter.
3. Clicca su Update Design.
4. Ora potrai vedere i prezzi convertiti e il simbolo della valuta nel tuo design.

Soluzione API personalizzata #

Disclaimer: Questa è una soluzione molto personalizzata per ottenere conversioni dei prezzi nel caso in cui non ci siano dati dall’API Shopify. Usala solo se utilizzi una configurazione specifica e personalizzata per le conversioni basate su cambi geo-IP.

La documentazione della soluzione frontend è disponibile su Github.

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

Il design pattern è composto dalle seguenti parti:

• Una collection che contiene tutti i prodotti.
• Un layout alternativo per mostrare le informazioni della collection in formato JSON.
• Una JavaScript Class che raccoglie i dati disponibili nella collection.
• Un frammento JavaScript che consuma i dati per gli ID prodotto rilevanti in un risultato e li inserisce in un div nel template.

Crea collection #

Per assicurarti di avere una collection con tutti i prodotti possibili, crea una collection con una condizione applicabile a tutti i prodotti.

La collection deve essere chiamata Clerk api, così le verrà assegnato il percorso /collection/clerk-api nel frontend.

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

Crea layout alternativo #

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

Per farlo, modifica prima il codice del tema che desideri usare.

Nella sezione dei template sulla sinistra, premi Add new Template.

Nel popup, seleziona collection come tipo di risorsa.

Seleziona liquid come tipo di file.

Scrivi json nel campo in basso, così il nome del template sarà collection.json.liquid.

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

Se necessario, puoi aggiungere campi al prodotto in questo template.

Aggiungi la classe JS #

Per recuperare i dati dalla tua collection e prepararli, inserisci l’intero contenuto di index.js dalla cartella class di questo progetto, dentro il tag script che contiene Clerk.js che hai messo 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()
  // Finally init() for the class to make sure it runs when the page loads.
</script>

Questa classe invalida i dati in base ai timestamp e alle valute, senza che tu debba cambiare codice.

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

Qualsiasi cambiamento nel contesto della valuta invalida anche i dati.

Aggiungi funzione di template #

Includi template.js nel template di design usato.

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

L’esempio include i campi list_price e price.

Nota: Se hai bisogno di usare campi diversi da price e list_price, aggiungili in collection.json.liquid e poi modifica template.html e template.js per usare anche quei campi. Non dovresti mai dover modificare la Class descritta al punto 3.

Trovare i file del tema #

Shopify ospita oltre 100 diversi temi per personalizzare lo stile del tuo webshop.

Ogni tema funziona nello stesso modo: personalizzi i file del tema per ottenere il risultato desiderato nel tuo store.

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

Shopify ti fornisce un campo di ricerca per trovare rapidamente il file che ti interessa.

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

Ad esempio, se cerchi il file con il codice della pagina Search è probabile che abbia ‘search’ nel nome file.

Se non sei sicuro di aver trovato il file corretto, puoi confrontare l’HTML nel file tema con quello della pagina corrispondente per vedere se corrispondono.

Questo può essere fatto su Google Chrome cliccando col tasto destro su qualunque sezione della pagina e selezionando ‘Ispeziona’.

Puoi così ispezionare l’HTML della pagina e verificare se la classe/l’ID degli elementi nel file è lo stesso presente sulla pagina.

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

Consigli del carrello #

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

Questa guida descrive una soluzione altamente personalizzata che può funzionare in modo diverso tra i vari temi Shopify. È specificamente pensata per temi in cui il carrello fa parte del DOM in ogni pagina ma resta nascosto fino a che l’utente non lo apre.

Mostrare le Recommendations di Clerk.io nel carrello su Shopify è un ottimo modo per proporre altri prodotti ai clienti prima che procedano al 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 carrello (di solito chiamato cart-drawer.liquid o simile).
3. Inserisci una snippet di Recommendations di Clerk.io 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 item in cart.items %}{{ item.product_id }}{% unless forloop.last %}, {% endunless %}{% endfor %}]"
></span>

1. Insieme allo snippet sopra, includi uno script per mostrare le Recommendations di Clerk.io quando l’utente apre il carrello. Un modo è usare un MutationObserver. Lo script sotto include tutti questi elementi, per darti un esempio di come gestirlo:

<script>
    // Select the node that will be observed for mutations
    const targetNode = document.querySelector("cart-drawer.drawer");

    // Add all of the class names of the cart drawer, when it is opened
    const targetNodeClasses = "drawer animate active";

    // Options for the observer (which mutations to observe)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Function to fetch cart data
    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 function to execute when mutations are observed
    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;
                    }
                }

            }
        }
    };

    // Create an observer instance linked to the callback function
    const clerk_observer = new MutationObserver(callback);

    // Start observing the target node for configured mutations
    clerk_observer.observe(targetNode, config);
</script>

Il file del carrello dovrebbe apparire così:

Autenticazione HTTP #

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

Questo bloccherà l’importatore Clerk.io e 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 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 dell’invio dei dati di prodotti, categorie e vendite a Clerk.io.

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

Ecco una lista dei più comuni errori e come risolverli.

401 Unauthorized #

Questo errore avviene se il tuo webshop o l’ambiente di sviluppo richiede HTTP authentication per accedervi.

Si risolve inserendo il Username e la Password come parte dell’URL di importazione:

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

Errore di permessi #

Questo errore di solito avviene se non hai dato Read Access a Store content like articles, blogs, comments, pages and redirects nella tua Private App.

Per risolverlo:

1. Effettua il login su 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:

1. Torna all’inizio della pagina e clicca su Save.

Gestione di require.js #

Questa guida si applica solo quando si utilizza Clerk.js 1.

In alcune configurazioni, Require.js impedisce a Clerk.js di caricarsi, impedendo la visualizzazione di slider o risultati Search.

In questo caso, nel console vedrai l’errore:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi richiedono di modificare il tracking-script, che normalmente si inserisce in index.liquid.

Includere in Require.js #

La soluzione migliore è provare a far riconoscere Clerk.io a Require.js.

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

Ignorare 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 usato uno di questi approcci, Require.js sarà ora compatibile con Clerk.io.

Aggiornamento a Clerk.js 2 #

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

Rende l’installazione di Clerk.io su qualsiasi webshop più semplice.

Poiché le due versioni funzionano in modo leggermente diverso, è necessario seguire questi passaggi per aggiornare correttamente.

Le due principali differenze in Clerk.js 2 sono:

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

Creare i designs #

Dato che Clerk.js 2 utilizza un approccio diverso ai Designs, devi crearne di nuovi.

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

• Usa il pratico Design Editor per creare nuovi Designs, come spiegato nei punti successivi.
• Converti i tuoi vecchi Designs. 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 un Nome al tuo Design (consigliamo di aggiungere “V2” così è chiaro che usi Clerk.js 2).
3. Scegli il tipo di Design.
4. Clicca su Publish Design quando hai finito, e vai a 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 al Design per altre informazioni sui prodotti.
6. Clicca su Publish. Questo causerà temporaneamente la non visualizzazione nello shop fino a che non completi Step 2. Seleziona il nuovo Design per tutti gli Element che devono essere aggiornati.
7. Vai su Recommendations/Search > Elements e cambia il tuo Element Clerk.io per usare il nuovo Design.

Ora sei pronto a passare a Clerk.js 2.

Sostituzione dello script #

1. Trova il file template usato per mostrare tutte le pagine del webshop, dove si trova lo script originale di Clerk.js vicino al fondo.
2. Rimuovi il vecchio script dal file:

1. Vai su my.clerk.io > Developers > Tracking Code.. Ora questa pagina contiene il tuo nuovo codice di tracking di Clerk.js 2.
2. Copia questo codice e inseriscilo immediatamente prima del tag </head> nel template:

1. Salva il template.

Congratulazioni! Ora stai usando il nuovo setup Clerk.js 2!

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

Customer Events Access #

Quando ti aiutiamo a configurare o risolvere problemi di tracciamento ordini tramite pixel Shopify, potremmo chiederti l’accesso alla sezione Customer events nella tua amministrazione Shopify.

Segui questi step 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 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 gestire il pixel Clerk.io così da poter verificare che il tracciamento ordini funzioni correttamente.