FAQ

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

Dimensioni delle immagini #

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

Se il tuo design necessita di una dimensione di output diversa per ogni collocazione, puoi rimuovere la dimensione fissa sincronizzata e richiedere una nuova larghezza nell’URL.

Esempio (sostituisci 600x600 con la dimensione immagini predefinita configurata):

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

Questo è utile quando un design utilizza più formati di immagine (per esempio, card prodotto e grandi hero) e vuoi evitare di sincronizzare più attributi immagine.

Conversione della valuta #

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

Per impostazione predefinita, Clerk.js per Shopify include un formatter che funziona fintanto che la tua app di terze parti usa l’oggetto valuta integrato di Shopify.

Soluzione standard #

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

Questo esempio utilizza il nostro linguaggio template standard qui.

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

Gli esempi seguenti mostrano come funzionano i diversi componenti.

Design Editor #

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. Su my.clerk.io, vai a Search/Recommendations > Designs e clicca su Edit Design per il tuo design.

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

3. Clicca su Update Design.

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

Soluzione API personalizzata #

Disclaimer: Questa è una soluzione molto personalizzata per ottenere conversioni di prezzo se non sono presenti dati dall’API di Shopify. Usala solo se usi una configurazione specifica e personalizzata per le conversioni di prezzo basate su cambi geo-IP.

Questa è la documentazione della soluzione frontend su Github.

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

Il pattern di design è composto dalle seguenti parti:

• Una collezione che contiene tutti i prodotti.

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

• Una classe JavaScript che raccoglie i dati messi a disposizione nella collezione.

• Uno snippet JavaScript che consuma i dati per gli ID prodotto rilevanti in un dato risultato e li posiziona all’interno di un div nel template.

Creare una collezione #

Per assicurarti di avere una collezione con tutti i prodotti possibili, crea una collezione con una condizione che tutti i prodotti soddisfino.

La collezione dovrebbe chiamarsi Clerk api, poiché ciò farà sì che riceva il percorso /collection/clerk-api frontend.

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

Creare un layout alternativo #

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

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

Nella sezione templates sulla sinistra, premi Add new Template.

Nel popup, seleziona collection come tipo di risorsa.

Seleziona liquid come tipo di file.

Scrivi json nell’ultimo campo 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 trovato nella cartella liquid di questo progetto.

Puoi aggiungere campi al prodotto in questo template secondo necessità.

Aggiungi la classe JS #

Per recuperare i dati dalla tua collezione e prepararli all’uso, inserisci tutto il contenuto di index.js nella cartella class di questo progetto, all’interno del tag script contenente Clerk.js che hai inserito 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 al caricamento della pagina.
</script>

Questa classe invaliderà i dati in base a timestamp e valute, senza che tu debba modificare il codice.

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

Qualsiasi cambiamento nel contesto della valuta invalida anche i dati.

Aggiungi funzione template #

Includi il template.js nel template di design utilizzato.

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

L’esempio include i campi list_price e price.

Nota: Se devi usare campi diversi da price e list_price, aggiungili in collection.json.liquid e modifica poi anche template.html e template.js per consumarli. Non dovresti mai dover modificare la Classe descritta allo step 3.

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 un dato risultato nel tuo store.

Tuttavia, i nomi dei file dei temi 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 aiutarti a localizzarlo.

Ad esempio, se cerchi il file che contiene il codice per la pagina di ricerca, probabilmente avrà ‘search’ nel nome del file.

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

Puoi farlo su Google Chrome facendo clic destro su qualsiasi sezione della pagina e selezionando ‘Inspect’.

Puoi quindi ispezionare l’HTML nella pagina e controllare se la classe/l’ID degli elementi coincida nel file e nella pagina.

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

Consigli nel carrello a scomparsa #

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

Questa guida illustra una soluzione altamente personalizzata che può comportarsi in modo diverso nei vari temi Shopify. È progettata specificatamente per temi dove il carrello fa parte del DOM su ogni pagina ma rimane nascosto fino a quando l’utente lo apre.

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

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

2. Trova il file in cui si trova il template del carrello a scomparsa (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. Per 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, include uno script per renderizzare le Recommendations di Clerk quando l’utente apre il carrello. Un approccio è usare un MutationObserver. Lo script qui sotto include tutti questi elementi come esempio:

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

    // Aggiungi tutti i nomi delle classi del carrello a scomparsa, 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;
    }

    // Funzione di 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 dell’observer e collegala alla funzione di callback
    const clerk_observer = new MutationObserver(callback);

    // Avvia l’osservazione del nodo di destinazione per le mutazioni
    clerk_observer.observe(targetNode, config);
</script>

Il tuo file del carrello a scomparsa dovrebbe apparire così:

Autenticazione HTTP #

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

Questo blocca l’importatore Clerk e mostra un errore 401 Unauthorized nel log della 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ì:

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.

Tuttavia, in alcuni casi la configurazione del server può impedire all’Importer di accedere ai dati, 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 essere accessibile.

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

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

Errore di Permessi #

Questo errore solitamente si verifica se non sono stati concessi i permessi di Read Access per Store content like articles, blogs, comments, pages and redirects nella tua App Privata.

Per risolvere:

1. Accedi a Shopify e vai a Apps > Manage Private Apps > Clerk.io (o il nome che hai assegnato 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.

Gestire require.js #

Questa guida si applica solo se utilizzi 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 succede, vedrai il seguente errore nella console:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi richiedono di modificare il tracking-script, solitamente inserito in index.liquid.

Inclusione in Require.js #

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

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; nella parte superiore dello script di tracking:

Dopo aver applicato 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ù semplice installare Clerk su qualsiasi webshop.

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

Le due principali differenze in Clerk.js 2 sono:

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

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

Crea i designs #

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

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

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

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

Opzione Design Editor #

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

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

3. Scegli il Tipo di Design.

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

5. Nel Design Editor, clicca su uno qualsiasi degli elementi esistenti come nome, immagine, bottone, ecc. per modificarli, o aggiungi nuovi elementi al Design per aggiungere ulteriori informazioni sui prodotti.

6. Clicca su Publish. Questo farà sì che temporaneamente non vengano mostrati sul tuo webshop fino a quando non avrai completato Step 2. Scegli il nuovo Design per tutti gli Element che devono essere aggiornati.

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

Ora sei pronto per passare a Clerk.js 2.

Sostituisci lo script #

1. Trova il file template utilizzato per mostrare tutte le pagine del webshop, e dove si trova lo script originale di Clerk.js in fondo.

2. Rimuovi il vecchio script dal file:

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

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

5. Salva il template.

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

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

Accesso agli Eventi Cliente #

Quando ti aiutiamo con la configurazione o la risoluzione dei problemi di tracciamento ordini tramite i pixel Shopify, potremmo chiederti l’accesso all’area eventi cliente nel tuo pannello admin Shopify.

Segui questi passaggi per concedere i permessi necessari:

1. In Shopify, vai a Settings > Users and permissions.
2. Clicca sul membro del personale chiamato Clerk.io (o sull’utente staff che desideri 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 degli ordini funzioni correttamente.