FAQ

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

Conversione di valuta #

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

Di default, Clerk.js per Shopify è 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 di template standard qui.

Quando usi 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 desideri mostrare il prezzo.

2. Aggiungi il seguente codice Liquid per mostrare il prezzo in base al convertitore di 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 potrai vedere i prezzi convertiti ed il simbolo della valuta nel tuo design.

Soluzione Custom API #

Disclaimer: Questa è una soluzione molto personalizzata per ottenere la conversione dei prezzi se non ci sono dati disponibili dall’API Shopify. Usala solo se hai una configurazione specifica e customizzata per la conversione dei prezzi basata su modifiche geo-IP.

Questa è la documentazione della soluzione frontend su Github.

Questa sezione spiega come ottenere dati contestuali in tempo reale per mostrarli all’interno dei contenuti restituiti dalla Clerk API.

Il pattern di design è composto dalle seguenti parti:

• Una raccolta contenente tutti i prodotti.

• Un layout alternativo per rendere le informazioni della raccolta in formato JSON.

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

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

Crea raccolta #

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

La raccolta deve chiamarsi Clerk api, così verrà assegnato il percorso /collection/clerk-api sul frontend.

La condizione della raccolta dovrebbe essere qualcosa come price > -1000000.

Crea layout alternativo #

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

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

Nella 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 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 che si trova nella cartella liquid di questo progetto.

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

Aggiungi classe JS #

Per recuperare i dati dalla raccolta e prepararli per l’utilizzo, inserisci l’intero contenuto di index.js nella cartella class di questo progetto, all’interno del tag script con Clerk.js che hai inserito in theme.liquid.

Dovrebbe apparire in questo modo:

<script>
  // Clerk.js Injection Code
  // Clerk Config with Key and Formatters
  // Classe da questo progetto
  clerk_shopify_api.init()
  // Alla fine init() per la classe per assicurarsi che venga eseguita al caricamento della pagina.
</script>

Questa classe invalida i dati in base ai timestamps e alle valute, senza che tu debba modificare il codice.

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

Qualsiasi cambiamento nel contesto di valuta invalida anche i dati.

Aggiungi funzione template #

Includi template.js nel template di design utilizzato.

La funzione recupera 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 usare campi diversi da price e list_price, aggiungili in collection.json.liquid ed edita poi anche template.html e template.js per consumare tali campi. Non dovresti mai dover modificare la Classe descritta nello step 3.

Trovare i file tema #

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

Ogni tema funziona nello stesso modo: personalizzi i file tema per ottenere un risultato specifico 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 di cui hai bisogno.

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

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

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

Questo può essere fatto su Google Chrome cliccando con il destro su una sezione della pagina e selezionando “Ispeziona”.

Puoi quindi esaminare l’HTML della pagina e controllare se la classe/l’ID degli elementi corrispondono nel file e sulla pagina.

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

Consigli nel cassetto carrello #

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

Questa guida illustra una soluzione molto personalizzata che può comportarsi in modo diverso con i vari temi Shopify. È specificamente progettata per i temi in cui il carrello fa parte del DOM su ogni pagina ma rimane nascosto finché l’utente non lo apre.

Mostrare i consigli di Clerk nel cassetto del carrello su Shopify è un ottimo modo per mostrare ulteriori prodotti agli utenti prima del checkout.

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

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

3. Inserisci uno snippet di Clerk Recommendations da Recommendations > Elements.

4. Rinomina la classe da clerk a controlla 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 qui sopra, includi uno script per rendere visibili le Clerk Recommendations quando l’utente apre il carrello. Una strategia può essere usare MutationObserver. Lo script qui sotto include tutti questi elementi, fornendo un esempio di approccio:

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

    // Tutte le classi del cassetto carrello, quando è aperto
    const targetNodeClasses = "drawer animate active";

    // Opzioni per l’observer (quali mutazioni osservare)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funzione che preleva 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 rilevate 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 observer collegato alla funzione callback
    const clerk_observer = new MutationObserver(callback);

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

Il file del tuo cassetto carrello dovrebbe apparire così:

Autenticazione HTTP #

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

Questo blocca l’importatore Clerk e mostra un errore 401 Unauthorized nel log di sincronizzazione.

Puoi risolvere inserendo le credenziali 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 negozio è responsabile della trasmissione dei dati di prodotti, categorie e vendite a Clerk.

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

Di seguito i più comuni errori e come risolverli.

401 Unauthorized #

Questo errore si verifica se il tuo negozio o ambiente di sviluppo 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 si verifica generalmente se non hai concesso 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 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 seleziona Read access:

4. Scorri in cima alla pagina e clicca Save.

Gestione di require.js #

Questa guida è valida solo per l’uso di Clerk.js 1.

In alcune configurazioni, Require.js impedisce il caricamento di Clerk.js, per cui non vengono visualizzati slider o risultati della ricerca.

Quando accade, viene mostrato questo errore nella console:

Uncaught ReferenceError: Clerk is not defined

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

Inclusione in Require.js #

Il miglior approccio è tentare di far riconoscere Clerk da Require.js.

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

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

Upgrade a Clerk.js 2 #

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

Rende più facile installare Clerk su qualsiasi negozio online.

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

Le principali differenze in Clerk.js 2 sono:

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

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

Crea i design #

Dato che 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 crearne di nuovi, come descritto nei passaggi seguenti.

• Converti i tuoi vecchi Designs. Segui questa guida per sapere 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” per evidenziare che stai usando Clerk.js 2).

3. Scegli il tipo di Design.

4. Clicca 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 modificarli, oppure aggiungi nuovi elementi al Design per inserire altre informazioni sui prodotti.

6. Clicca Publish. Questo causerà temporaneamente la mancata visualizzazione sul tuo shop finché non completi Step 2. Scegli il nuovo Design per tutti gli Elements che devono essere aggiornati.

7. Vai su 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. Individua il file template usato per mostrare tutte le pagine dello shop, dove si trova lo script originale di Clerk.js vicino al fondo.

2. Rimuovi lo script vecchio dal file:

3. Vai su my.clerk.io > Developers > Tracking Code.. Ora troverai il codice tracking per Clerk.js 2.

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

5. Salva il template.

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

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

Concedere l’accesso Clerk agli Eventi Cliente #

Quando ti aiutiamo a configurare o risolvere problemi di tracciamento ordini tramite pixel Shopify, potremmo richiedere l’accesso alla sezione eventi cliente nella tua area admin Shopify.

Segui questi passaggi per concedere i permessi necessari:

1. In Shopify, vai su Settings > Users and permissions.
2. Clicca il membro staff chiamato Clerk.io (o l’utente staff che vuoi aggiornare).
3. Scorri fino a Store settings e attiva:
   • 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 di gestire il pixel Clerk così possiamo verificare che il tracciamento ordini funzioni correttamente.