FAQ

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

Dimensioni immagini #

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

Se il tuo design richiede 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 immagine predefinita configurata):

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

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

Conversione valuta #

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

Per impostazione predefinita, 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 #

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

Questo esempio utilizza il nostro linguaggio template standard qui.

Quando utilizzi conversioni valuta e simboli, Clerk.js rileva impostazioni come lingua, valuta e country code.

Gli esempi seguenti mostrano come funzionano i componenti diversi.

Editor del Design #

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

Soluzione API personalizzata #

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

Questa è la documentazione della soluzione frontend in Github.

Questa sezione copre come ottenere dati contestuali in tempo reale da mostrare all’interno del contenuto restituito dall’API di Clerk.io.

Il pattern di design è composto dalle seguenti parti:

• Una collection contenente tutti i prodotti.
• Un layout alternativo per mostrare informazioni sulla 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 dato risultato e li inserisce in un div nel template.

Crea la collection #

Per assicurarti di avere una collection con tutti i possibili prodotti, crea una collection con una condizione valida per tutti i prodotti.

La collection dovrebbe chiamarsi Clerk api, così riceverà il percorso /collection/clerk-api frontend.

La condizione per la collection può essere ad esempio price > -1000000.

Crea layout alternativo #

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

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

Nella sezione Templates a sinistra, premi Add new Template.

Nel popup, seleziona collection per il tipo di risorsa.

Seleziona liquid per il tipo di file.

Scrivi json nel campo più 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 trovato nella cartella liquid per questo progetto.

Sentiti libero di aggiungere campi al prodotto in questo template secondo necessità.

Aggiungi classe JS #

Per acquisire i dati dalla collection e prepararli, inserisci tutto il contenuto di index.js nella cartella class di questo progetto, dentro il tag script contenente Clerk.js che hai inserito in theme.liquid.

Dovrebbe essere simile a questo:

<script>
  // Codice di iniezione Clerk.js
  // Clerk Config con Key e Formatter
  // Classe da questo progetto
  clerk_shopify_api.init()
  // Infine init() per la classe per assicurarsi che venga eseguita al caricamento della pagina.
</script>

Questa classe invalida i dati in base a timestamp e valute, senza che sia necessario modificare il codice.

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

Qualsiasi cambiamento nel contesto valuta invalida anche i dati.

Aggiungi funzione template #

Includi il template.js nel template design utilizzato.

La funzione acquisisce 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 hai bisogno di utilizzare campi diversi da price e list_price, aggiungili in collection.json.liquid e poi modifica sia template.html che template.js per consumare anche quei campi. Non dovresti mai aver bisogno di modificare la Classe descritta nel passaggio 3.

Trovare i file tema #

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

Ogni tema funziona allo 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 offre un campo di ricerca per trovare facilmente e velocemente il file tema che stai cercando.

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

Ad esempio, se stai cercando il file che contiene il codice per la pagina di ricerca, probabilmente il suo nome contiene ‘search’.

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

Puoi farlo su Google Chrome facendo clic con il tasto destro su qualsiasi sezione della pagina e selezionando ‘Ispeziona’.

Potrai ispezionare l’HTML nella pagina e verificare se la classe/ID degli elementi coincide nel file e nella pagina.

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

Raccomandazioni 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 modi diversi sui vari temi Shopify. È progettata specificamente per temi dove il carrello è parte del DOM su ogni pagina ma resta nascosto fino a quando l’utente non lo apre.

Mostrare Clerk.io Recommendations nel carrello a scomparsa su Shopify è un ottimo modo per mostrare prodotti aggiuntivi ai clienti 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 carrello a scomparsa (di solito chiamato cart-drawer.liquid o simile).
3. Inserisci uno snippet Clerk.io Recommendations 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 rendere le Clerk.io Recommendations quando l’utente apre il carrello. Un approccio è utilizzare un MutationObserver. Lo script seguente include tutti questi elementi, dandoti un esempio di come gestirlo:

<script>
    // Seleziona il nodo che sarà osservato per 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’osservatore (quali mutazioni osservare)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funzione per ottenere 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’istanza observer collegata alla callback
    const clerk_observer = new MutationObserver(callback);

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

Salva il file carrello a scomparsa aggiornato e verifica che le raccomandazioni Clerk appaiano quando un prodotto viene aggiunto al carrello.

Autenticazione HTTP #

L’autenticazione HTTP viene spesso utilizzata su siti di staging per evitare visitatori indesiderati.

Questo bloccherà l’importatore Clerk.io e visualizzerà un errore 401 Unauthorized nel log di sincronizzazione.

Puoi risolvere questo inserendo le informazioni di autenticazione nell’URL di importazione.

In my.clerk.io > Data > Configuration, aggiorna il tuo URL di import come segue:

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

Errori comuni di sincronizzazione #

Quando importi i dati con l’integrazione Shopify, il server del tuo webshop è responsabile di inviare dati di prodotto, categoria e vendita a Clerk.io.

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

Di seguito trovi un elenco 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’URL di importazione:

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

Errore di permessi #

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

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 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 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 accade, apparirà il seguente errore nella console:

Uncaught ReferenceError: Clerk is not defined

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

Inclusione in Require.js #

Il modo migliore è provare a far riconoscere Clerk.io a Require.js.

Inserisci require(['clerk'], function() {}); in fondo allo script di tracciamento.

Ignora Require.js #

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

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

Dopo aver usato uno di questi approcci, Require.js sarà 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 installare Clerk.io su qualsiasi webshop.

Tuttavia, 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 Liquid templating language, ma possono essere creati facilmente anche tramite il Design Editor.
• Lo script deve essere inserito subito prima del tag </head> nel template del tuo webshop.

Crea design #

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

Puoi creare i tuoi Designs Clerk.js 2 in uno dei seguenti 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 tuo Design (consigliamo di aggiungere “V2” così è evidente che stai usando Clerk.js 2).
3. Scegli il Tipo di Design.
4. Clicca Publish Design quando hai finito e vai su Step 2 della guida.
5. Nell’Editor del Design, clicca su ognuno degli elementi esistenti come nome, immagine, bottone, ecc. per modificarli, o aggiungi nuovi elementi al Design per aggiungere più informazioni sui prodotti.
6. Premi Publish. Questo temporaneamente potrebbe non mostrare i Design nel tuo webshop fino al completamento di Step 2. Scegli il nuovo Design per tutti gli Elements da aggiornare.
7. Vai su Recommendations/Search > Elements e modifica il tuo Element Clerk.io per usare il nuovo Design.

Ora sei pronto a passare a Clerk.js 2.

Sostituisci lo script #

1. Individua il file template che viene utilizzato per mostrare tutte le pagine del webshop, dove si trova lo script originale Clerk.js verso il fondo.

2. Rimuovi il vecchio script dal file:

3. Vai su my.clerk.io > Developers > Clerk.js.. Ora questa pagina contiene il nuovo tracking code di 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 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 i pixel Shopify, potremmo richiedere 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 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ì possiamo verificare che il tracking degli ordini funzioni correttamente.