FAQ

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

Dimensioni delle immagini #

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

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

Esempio (sostituisci 600x600 con la dimensione dell’immagine predefinita configurata):

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

Questo è utile quando un design utilizza più formati di immagine (ad esempio, schede prodotto e grandi banner hero) e desideri evitare di sincronizzare più attributi di immagine.

Conversione della valuta #

La funzione di Conversione Valuta incorporata di Shopify facilita la lettura del simbolo della valuta 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 utilizza il nostro linguaggio template standard qui.

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

Gli esempi seguenti mostrano come funzionano i vari componenti.

Editor del Design #

1. Crea un componente Text dove vuoi che venga mostrato il prezzo.
2. Aggiungi 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 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 Custom API #

Disclaimer: Questa è una soluzione molto personalizzata per ottenere le conversioni di prezzo se non sono presenti dati dalla API Shopify. Usala solo se disponi di una configurazione specifica e personalizzata delle conversioni di prezzo basate sui cambiamenti geo-IP.

La documentazione della soluzione frontend è disponibile su Github.

Questa sezione mostra come ottenere dati contestuali in tempo reale da mostrare nei contenuti restituiti dalla API Clerk.io.

Il pattern di design è composto dai seguenti elementi:

• Una collection contenente tutti i prodotti.
• Un layout alternativo per renderizzare le informazioni della collection come JSON.
• Una classe JavaScript che raccoglie i dati disponibili nella collection.
• Uno snippet JavaScript che consuma i dati per gli ID prodotto rilevanti in un risultato e li colloca in un div del template.

Crea la 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 deve essere chiamata Clerk api, così riceverà la route /collection/clerk-api in frontend.

La condizione della collection può essere qualcosa come price > -1000000.

Crea il layout alternativo #

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

Per fare ciò, prima modifica il codice del tema che vuoi utilizzare.

Nella sezione template a sinistra, premi Add new Template.

Nel popup, seleziona collection come tipo di risorsa.

Seleziona liquid come tipo di file.

Scrivi json nel campo più in basso, in modo che il nome del nuovo template sia 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.

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

Aggiungi la classe JS #

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

Dovrebbe risultare simile 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 quando la pagina si carica.
</script>

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

Il tempo prima dell’invalidamento è di 12 ore dall’ultimo aggiornamento.

Qualsiasi cambiamento nel contesto di valuta invalida anche i dati.

Aggiungi la funzione di template #

Includi template.js nel template utilizzato.

La funzione recupera i dati quando disponibili e li inserisce nei child element specifici 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 tali campi. Non dovrebbe mai essere necessario modificare la classe descritta al punto 3.

Trovare i file del tema #

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

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

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

Shopify mette a disposizione un campo di ricerca per trovare facilmente e velocemente il file tema che cerchi.

Se non conosci il nome del file che stai cercando, puoi usare il campo di ricerca per aiutarti a localizzarlo.

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

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

Questo si può fare su Google Chrome facendo clic destro su una qualsiasi sezione della pagina e selezionando ‘Inspect’.

Poi puoi ispezionare l’HTML sulla pagina e verificare se la classe/l’ID degli elementi è la stessa che trovi nel file.

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

Recommendations nel carrello (cart drawer) #

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

Questa guida illustra una soluzione altamente personalizzata che può comportarsi in modo diverso su vari temi Shopify. È pensata specificamente per temi in cui il carrello fa parte del DOM in ogni pagina ma resta nascosto fino all’apertura da parte dell’utente.

Mostrare nel carrello le Recommendations di Clerk.io su Shopify è un ottimo modo per mostrare prodotti aggiuntivi ai clienti prima che inizino il processo di checkout.

1. Modifica il codice del tema Shopify in Online Store > Themes > Edit code.
2. Trova il file che contiene il template del carrello (di solito chiamato cart-drawer.liquid o simile).
3. Inserisci uno snippet Recommendations di Clerk.io da Recommendations > Elements.
4. Rinomina la classe da clerk a 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. Assieme allo snippet sopra, includi uno script per rendere visibili le Recommendations di Clerk.io quando l’utente apre il carrello. Un approccio è usare un MutationObserver. Lo script qui sotto include tutti questi elementi ed è un esempio di come procedere:

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

    // Aggiungi tutti i nomi delle classi del carrello, quando viene aperto
    const targetNodeClasses = "drawer animate active";

    // Opzioni per l'osservatore (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 si osservano 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 osservatore collegato alla funzione di callback
    const clerk_observer = new MutationObserver(callback);

    // Inizia ad osservare il nodo target per le mutazioni configurate
    clerk_observer.observe(targetNode, config);
</script>

Salva il file aggiornato del carrello e verifica che le Recommendations di Clerk compaiano quando viene aggiunto un prodotto al carrello.

Autenticazione HTTP #

L’autenticazione HTTP viene spesso utilizzata su siti di staging per evitare visite indesiderate.

Questo bloccherà l’importatore Clerk.io e verrà mostrato un errore 401 Unauthorized nel log della sincronizzazione.

Puoi risolvere questo inserendo i dati di autenticazione nell’URL di importazione.

In my.clerk.io > Data > Configuration, aggiorna il tuo URL di importazione in questo modo:

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

Errori comuni di sincronizzazione #

Durante l’importazione dei dati tramite l’integrazione Shopify, il server del tuo webshop si occupa di inviare dati di prodotti, categorie e vendite a Clerk.io.

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

Di seguito è riportato un elenco degli errori più comuni e come risolverli.

401 Unauthorized #

Questo errore si verifica se il tuo webshop o ambiente dev richiede autenticazione HTTP per l’accesso.

Si risolve inserendo Username e Password nell’URL di importazione:

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

Errore di permessi #

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

Per risolvere:

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

2. Scorri su 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 quando si usa Clerk.js 1.

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

Quando ciò accade, viene visualizzato questo errore nella console:

Uncaught ReferenceError: Clerk is not defined

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

Inclusione in Require.js #

Il metodo migliore è far riconoscere Clerk.io a Require.js.

Inserisci require(['clerk'], function() {}); alla fine dello script di tracking.

Ignorare Require.js #

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

Inserisci window.__clerk_ignore_requirejs = true; all’inizio dello script di tracking.

Dopo aver utilizzato uno di questi metodi, 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 più semplice l’installazione di Clerk.io su qualsiasi webshop.

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

Le due principali differenze in Clerk.js 2 sono:

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

Crea i design #

Poiché Clerk.js 2 gestisce i Designs in modo diverso, devi crearne di nuovi.

Puoi creare i Design di Clerk.js 2 in due modi:

• Usa il pratico Design Editor per creare nuovi Designs, come descritto nei punti seguenti.
• 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 Design (consigliamo di aggiungere “V2” per renderlo evidente).
3. Scegli il tipo di Design.
4. Clicca su Publish Design quando hai finito e vai al Step 2 della guida.
5. Nel Design Editor, clicca su qualsiasi elemento esistente come nome, immagine, pulsante, ecc. per modificarlo, oppure aggiungi nuovi elementi per espandere le informazioni sui prodotti.
6. Clicca su Publish. Questo farà sì che temporaneamente non vengano mostrati sul webshop fino al completamento di Step 2. Scegli il nuovo Design per tutti gli Elementi che devono essere aggiornati.
7. Vai su Recommendations/Search > Elements e cambia il tuo Element di Clerk.io per utilizzare il nuovo Design.

Ora sei pronto a passare a Clerk.js 2.

Sostituisci lo script #

1. Trova il file template che mostra tutte le pagine del webshop, e che contiene lo script originale 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 tale codice e inseriscilo subito prima del tag </head> nel template:

5. Salva il template.

Congratulazioni! Ora stai utilizzando la versione migliorata di Clerk.js 2!

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

Accesso agli eventi cliente #

Quando ti aiutiamo a configurare o risolvere problemi di tracking ordini tramite gli Shopify pixel, potremmo chiedere l’accesso all’area degli eventi cliente nel tuo pannello di amministrazione Shopify.

Segui questi passaggi per concedere i permessi necessari:

1. In Shopify, vai su Settings > Users and permissions.
2. Clicca sullo staff chiamato Clerk.io (o sull’utente staff che vuoi aggiornare).
3. Scorri 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 eventi cliente e gestire il pixel Clerk.io così da poter verificare che il tracking degli ordini funzioni correttamente.