FAQ

Hai problemi con l’integrazione Shopify? Questa FAQ copre i problemi più comuni e le loro soluzioni, dalla conversione 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 diversa dimensione di output per posizionamento, puoi rimuovere la dimensione fissa sincronizzata e richiedere una nuova larghezza nell’URL.

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

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

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

Conversione valuta #

La Conversione Valuta integrata di Shopify semplifica la lettura di simbolo di valuta e 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 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 e simboli valuta, 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 dove vuoi che venga mostrato il prezzo.

2. Aggiungi il seguente codice Liquid per mostrare il prezzo tramite il convertitore valuta 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 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 ci sono dati dall’API Shopify. Usala solo se utilizzi una configurazione specifica e personalizzata per le conversioni di prezzo basate su variazioni geo-IP.

Questa è la documentazione della soluzione frontend in Github.

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

Il modello di design è composto dalle seguenti parti:

• Una collezione contenente tutti i prodotti.

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

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

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

Crea collezione #

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

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

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

Crea layout alternativo #

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

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

Sotto la sezione templates sulla 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, in modo che il nome del template creato sia collection.json.liquid.

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

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

Aggiungi classe JS #

Per raccogliere i dati dalla collezione e prepararli per l’utilizzo, inserisci l’intero 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 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 eseguito quando la pagina si carica.
</script>

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

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

Qualsiasi variazione nel contesto valuta invalida anche i dati.

Aggiungi funzione template #

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

La funzione raccoglie i dati quando disponibili e li inserisce in specifici elementi figli in 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, devi aggiungerli in collection.json.liquid e poi modificare anche template.html e template.js per consumare quei campi. Non dovresti mai dover modificare la Classe descritta al punto 3.

Trovare i file tema #

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

Ogni tema funziona allo stesso modo: personalizzi i file tema per ottenere un determinato risultato sul tuo store.

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

Shopify ti fornisce un campo ricerca per trovare in modo facile e veloce il file tema che stai cercando.

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

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

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

Questo può essere fatto su Google Chrome facendo clic col tasto destro su una sezione della pagina e selezionando ‘Inspect’.

Puoi quindi ispezionare l’HTML sulla pagina e controllare se class/ID degli elementi sono gli stessi sia nel file che sulla pagina.

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

Raccomandazioni nel carrello a scomparsa #

Si raccomanda fortemente l’installazione tramite uno sviluppatore Shopify.

Questa guida illustra una soluzione altamente personalizzata che può comportarsi diversamente a seconda del tema Shopify utilizzato. È pensata specificamente per temi dove il carrello fa parte del DOM in ogni pagina ma resta nascosto finché non viene aperto dall’utente.

Mostrare le Recommendations 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 tema Shopify in Online Store > Themes > Edit code.

2. Trova il file dove si trova il template del drawer del carrello (solitamente chiamato cart-drawer.liquid o simile).

3. Inserisci uno snippet Recommendations 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. Insieme allo snippet sopra, includi uno script per effettuare il rendering Recommendations Clerk quando l’utente apre il carrello. Un modo è utilizzare un MutationObserver. Lo script seguente include tutti questi elementi, fornendoti un esempio di approccio:

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

    // Aggiungi tutti i nomi classe del cart drawer, quando è 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 delle 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 di observer collegata alla callback
    const clerk_observer = new MutationObserver(callback);

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

Il tuo file drawer del carrello dovrebbe apparire così:

Autenticazione HTTP #

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

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

Puoi risolvere 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 tramite l’integrazione Shopify, il server del tuo webshop è responsabile di inviare dati di prodotto, categoria e vendita a Clerk.

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

Qui sotto trovi un elenco degli errori più comuni e le relative soluzioni.

401 Unauthorized #

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

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

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

Errore di permessi #

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

Per risolvere:

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

2. Scorri su Admin API Permissions e clicca su Review disabled Admin API permissions.

3. Cerca Store content like articles, blogs, comments, pages and redirects e scegli Read access:

4. Scorri in alto e clicca su Save.

Gestione di require.js #

Questa guida si applica solo quando usi 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 ciò accade, nel console verrà mostrato il seguente errore:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi richiedono di modificare lo script di tracciamento, normalmente inserito in index.liquid.

Includere in Require.js #

L’approccio migliore è cercare di far riconoscere Clerk a Require.js.

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

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 tracciamento:

Dopo aver utilizzato 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 l’installazione di Clerk su qualunque webshop.

Tuttavia, poiché le due versioni funzionano in modo leggermente diverso, è necessario seguire questi passaggi per aggiornare con successo.

Le due principali differenze in Clerk.js 2 sono:

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

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

Crea designs #

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

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

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

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

Opzione Design Editor #

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

2. Nella schermata successiva, assegna un Nome al tuo Design (consigliamo di aggiungere “V2” così sarà evidente che stai usando Clerk.js 2).

3. Scegli il Tipo di Design.

4. Clicca su Publish Design al termine, e vai al Passo 2 della guida.

5. Nell’Editor Design, clicca su uno degli elementi esistenti come nome, immagine, pulsante, ecc. per modificarlo, oppure aggiungi nuovi elementi per inserire più informazioni sui prodotti.

6. Clicca Publish. Questo farà sì che temporaneamente non vengano mostrati sul tuo webshop fino al completamento del Passo 2. Scegli il nuovo Design per tutti gli Elementi che devono essere aggiornati.

7. Vai su Recommendations/Search > Elements e modifica il tuo Element Clerk in modo che usi il nuovo Design.

Ora sei pronto a passare a Clerk.js 2.

Sostituire lo script #

1. Trova il template file che viene usato per mostrare tutte le pagine del webshop, dove si trova lo script Clerk.js originale vicino al fondo della pagina.

2. Rimuovi il vecchio script dal file:

3. Vai su my.clerk.io > Developers > Tracking Code.. Questa pagina ora mostra il tuo tracking code per Clerk.js 2.

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

5. Salva il template.

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

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

Accesso Customer Events #

Quando ti aiutiamo a configurare o risolvere problemi di tracciamento ordini tramite pixel Shopify, potremmo chiederti di accedere all’area eventi clienti 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 del personale chiamato Clerk.io (oppure sull’utente del personale che vuoi aggiornare).
3. Scorri su Store settings e abilita:
   • View customer events
   • Manage and add custom pixels
4. Clicca Save.

Questi permessi permettono al nostro team di visualizzare la sezione Customer events e gestire il pixel Clerk così possiamo verificare che il tracciamento ordini funzioni correttamente.