FAQ

Conversione della valuta frontend #

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

Di default, Clerk.js per Shopify viene fornito con un formatter che funzionerà finché la tua app di terze parti utilizza l’oggetto valuta integrato di Shopify.

Soluzione standard #

Devi utilizzare un formatter nei tuoi Design per convertire i prezzi. Questo è un esempio dal nostro linguaggio di template standard qui. Tuttavia, quando si utilizzano conversioni di valuta e simboli, Clerk.js rileva queste impostazioni come lingua, valuta e codice paese. I seguenti esempi ti daranno una panoramica di come funzionano i diversi componenti.

Nell’Editor di Design

1. Crea un componente Text dove desideri che venga visualizzato il prezzo

2. Aggiungi il seguente codice Liquid per mostrare il prezzo basato sul convertitore di valuta all’interno del componente di testo:

{{ currency_symbol }}{{ item.price | currency_converter }}

Nel design HTML/CSS (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 Aggiorna Design.

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

Soluzioni Shopify-frontend-api #

Dichiarazione: Questa è una soluzione molto personalizzata per ottenere conversioni di prezzo se non ci sono dati dall’API di Shopify. Utilizzala solo se stai utilizzando un’impostazione specifica e personalizzata per le conversioni di prezzo basate su cambiamenti geo-ip.

Questa è la documentazione della soluzione frontend in Github.

Ottenere Dati Contestuali JIT

Questa sezione tratta di come ottenere dati contestuali in tempo reale per mostrarli all’interno dei contenuti restituiti dall’API di Clerk.io.

I modelli di design sono composti dalle seguenti parti:

• Una collezione contenente tutti i prodotti.
• Un layout alternativo per il rendering delle informazioni sulla collezione come JSON.
• Una Classe Javascript che raccoglie i dati resi disponibili nella collezione.
• Uno Snippet Javascript che consuma i dati per gli ID dei prodotti rilevanti in un dato risultato e li posiziona all’interno di un div nel template.

1. La Collezione

Per garantire di avere una collezione con tutti i prodotti possibili, ti consiglio di creare una collezione con una condizione soddisfatta da tutti i prodotti. La collezione dovrebbe essere chiamata Clerk api, poiché questo porterà a ricevere il percorso /collection/clerk-api frontend.

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

2. Il Layout Alternativo per le Collezioni

In secondo luogo, dobbiamo creare un layout alternativo per mostrare i nostri dati utilizzando la collezione.

Per fare ciò, prima modifichiamo il codice del tema per il tema che desideriamo utilizzare. Nella sezione dei template sul lato sinistro, 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 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.

Sei libero di aggiungere campi al prodotto in questo template come richiesto.

3. La Classe JS che gestisce i dati dal nostro nuovo endpoint.

Per raccogliere i dati dalla nostra collezione e prepararli per l’uso, dobbiamo posizionare l’intero contenuto di index.js nella nostra cartella class in questo progetto, all’interno del tag script contenente Clerk.js che hai posizionato in theme.liquid.

Dovrebbe apparire qualcosa del genere:

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

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

Qualsiasi cambiamento nel contesto della valuta invalida anche i dati.

4. La funzione JS che carica i dati rilevanti nel template.

Infine, dovresti includere il template.js nel template di design utilizzato. La funzione raccoglie i dati quando disponibili e li posiziona in elementi figli specifici all’interno di ogni riquadro prodotto.

L’esempio include i campi list_price e price.

Cose da notare: Se hai bisogno di utilizzare campi che sono diversi da price e list_price, dovresti aggiungerli in collection.json.liquid e poi modificare template.html e template.js per consumare anche quei campi. Non dovresti mai dover modificare la Classe descritta nel passaggio 3.

Monitoraggio di più valute in 1 Negozio #

Questo è deprecato. Lo script di tracciamento pixel lo sostituisce. Segui i passaggi 4 e 5 della guida per iniziare con Shopify.

Quando si utilizzano più valute nel tuo webshop Shopify, è importante che gli ordini siano tradotti in una valuta per garantire che le tue prestazioni legate al fatturato siano accurate in Clerk.io.

Nei dashboard di Clerk.io, le tue prestazioni saranno sempre riportate in una valuta. Ad esempio, se utilizzi sia GBP che DKK nel tuo negozio online, i tuoi dashboard riporteranno le prestazioni tutte in GBP o tutte in DKK. Questo è il motivo per cui tradurre in una valuta è importante: dopotutto, non vorresti che un acquisto di 600 GBP venga letto da Clerk.io come 600 DKK!

Per assicurarti che i tuoi dashboard di Clerk.io mostrino i tuoi dati di vendita come un’unica valuta comune, questo può essere regolato all’interno del codice di tracciamento delle vendite che hai aggiunto al tuo negozio quando hai installato originariamente Clerk.io.

Vai su Impostazioni > Checkout > Script aggiuntivi nel backend di Shopify e modifica il codice di tracciamento delle vendite da questo:

<!-- Inizio dello strumento di personalizzazione e-commerce di Clerk.io - www.clerk.io -->
<script>
  (function (w, d) {
      var e = d.createElement('script'); e.type = 'text/javascript'; e.async = true;
      e.src = 'https://cdn.clerk.io/clerk.js';
      var s = d.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
      w.__clerk_q = w.__clerk_q || []; w.Clerk = w.Clerk || function () { w.__clerk_q.push(arguments) };
  })(window, document);
  Clerk('config', {
      key: 'yourPublicKey'
  });
  let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
  document.addEventListener('DOMContentLoaded', (e)=> {
      clerk_order_id = window.Shopify.checkout.order_id
  });
  if ( isNaN( clerk_order_id ) ) {
      if(window.Shopify){
          clerk_order_id = window.Shopify.checkout.order_id
      }
  }
  let log_sale_retry = setInterval(() => {
      if( ! isNaN( clerk_order_id ) ){
          Clerk('call', 'log/sale/shopify', {
              sale: clerk_order_id
          });
          clearInterval(log_sale_retry);
      }
  }, 100);
  </script>
  <!-- Fine dello strumento di personalizzazione e-commerce di Clerk.io - www.clerk.io -->

A questo:

<!-- Inizio dello strumento di personalizzazione e-commerce di Clerk.io - www.clerk.io -->
<script>
    (function (w, d) {
        var e = d.createElement('script'); e.type = 'text/javascript'; e.async = true;
        e.src = 'https://cdn.clerk.io/clerk.js';
        var s = d.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
        w.__clerk_q = w.__clerk_q || []; w.Clerk = w.Clerk || function () { w.__clerk_q.push(arguments) };
    })(window, document);
    let clerkLocale = Shopify.locale;
    let publicKey;
    switch (clerkLocale) {
        case 'en':
            publicKey = 'yourPublicKeyEN';
            break;
        case 'fr':
            publicKey = 'yourPublicKeyFR';
            break;
        case 'de':
            publicKey = 'yourPublicKeyDE';
            break;
        // Aggiungi più casi se necessario
    }
    Clerk('config', {
        key: publicKey
    });
    let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
    document.addEventListener('DOMContentLoaded', (e) => {
        clerk_order_id = window.Shopify.checkout.order_id
    });
    if (isNaN(clerk_order_id)) {
        if (window.Shopify) {
            clerk_order_id = window.Shopify.checkout.order_id
        }
    }
    let log_sale_retry = setInterval(() => {
        if (!isNaN(clerk_order_id)) {
            Clerk('call', 'log/sale/shopify', {
                sale: clerk_order_id
            });
            clearInterval(log_sale_retry);
        }
    }, 100);
</script>
<!-- Fine dello strumento di personalizzazione e-commerce di Clerk.io - www.clerk.io -->

Assicurati di mantenere lo stesso script di tracciamento dei visitatori– questo si trova appena sotto il codice di tracciamento delle vendite. I tuoi ordini ora dovrebbero fluire nei dashboard di Clerk.io come un’unica valuta.

Trovare file di tema comuni #

Shopify ospita oltre 100 temi diversi per stilizzare e personalizzare il tuo webshop. Ogni tema funziona allo stesso modo, in cui personalizzi i file del tema per ottenere un dato risultato nel tuo negozio, tuttavia, i nomi dei file del tema 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 stai cercando, 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, è probabile che contenga ‘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 sulla pagina pertinente per vedere se corrispondono.

Questo può essere fatto su Google Chrome facendo clic con il tasto destro su qualsiasi sezione della pagina e selezionando ‘Ispeziona’.

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

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

Raccomandazioni del cassetto del carrello #

L’installazione da parte di uno sviluppatore Shopify è fortemente raccomandata. Questa guida delinea una soluzione altamente personalizzata che potrebbe comportarsi in modo diverso attraverso vari temi Shopify. È specificamente progettata per temi in cui il carrello fa parte del DOM in ogni pagina ma rimane nascosto fino a quando non viene aperto dall’utente.

Mostrare le Raccomandazioni di 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 tuo tema Shopify in Online Store > Themes > Edit code.
2. Trova il file in cui si trova il template del cassetto del carrello (di solito chiamato cart-drawer.liquid o simile).
3. Inserisci uno snippet di Raccomandazioni di Clerk da Recommendations > Content. 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>

4. Insieme allo snippet sopra, includi uno script per rendere le Raccomandazioni di Clerk quando l’utente apre il carrello. Un approccio è utilizzare un MutationObserver. Lo script sottostante include tutti questi elementi, offrendoti un esempio di come affrontarlo. Ad esempio:

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

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

    // 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'osservatore collegata alla funzione di callback
    const clerk_observer = new MutationObserver(callback);

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

Il tuo file del cassetto del carrello dovrebbe apparire così:

Sincronizzazione con HTTP Auth #

Spesso l’autenticazione HTTP viene utilizzata sui siti di staging per evitare visitatori indesiderati.

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

Puoi facilmente verificare l’importatore inserendo le informazioni di autenticazione nell’URL di importazione come di seguito, in Data Sync su my.clerk.io:

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

Errori di sincronizzazione comuni #

Quando si importano dati con l’integrazione di Shopify, il server del webshop è responsabile dell’invio dei dati sui prodotti, categorie e vendite a Clerk.io.

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

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

Errore del server 401: Non autorizzato #

Questo errore si verifica se il tuo webshop/ambiente di sviluppo richiede autenticazione HTTP per accedervi.

Questo si risolve semplicemente inserendo il Nome utente e la Password come parte dell’URL di importazione:

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

Errore di autorizzazione di Shopify: Questa azione richiede l’approvazione del commerciante per l’ambito read_content. #

Questo errore si verifica solitamente se non hai dato Accesso in lettura a Contenuto del negozio come articoli, blog, commenti, pagine e reindirizzamenti nella tua App Privata.

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 fino a Autorizzazioni API Admin, e clicca su Review disabled Admin API permissions.

3. Trova Contenuto del negozio come articoli, blog, commenti, pagine e reindirizzamenti e scegli Accesso in lettura:

4. Poi scorri fino in cima alla pagina e clicca su Salva.

Gestire require.js #

Questa guida si applica solo quando si utilizza Clerk JS1.

In alcune configurazioni, Require.js impedisce a Clerk.js di caricarsi, il che significa che non verranno mostrati slider o risultati di ricerca.

Quando ciò accade, verrà mostrato il seguente errore nella tua console:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi gli approcci richiedono di apportare modifiche allo script di tracciamento, che di solito viene inserito in index.liquid.

Includere “clerk” in Require.js #

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

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;

nella parte superiore dello script di tracciamento:

Dopo aver utilizzato uno di questi approcci, Require.js sarà ora compatibile con Clerk.io.

Aggiornamento a Clerk.js 2 #

Clerk.js 2 è una versione più veloce e molto più flessibile della nostra libreria JavaScript che rende l’installazione di Clerk.io su qualsiasi webshop un gioco da ragazzi.

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

Le due principali differenze in Clerk.js 2 sono:

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

• Lo script deve essere inserito appena prima del nel template del tuo webshop.

Passo 1: Convertire i Design #

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

Puoi creare i tuoi Design Clerk.js 2 in uno dei due modi:

• 1. Usa l’intuitivo Editor di Design per creare nuovi Design, come descritto nei punti seguenti.
• 2. Converti i tuoi vecchi Design. Segui questa guida per vedere come farlo.

1.1 Inizia andando su my.clerk.io -> Recommendations / Search -> Designs e clicca su New Design:

1.2 Nella schermata successiva, dai al tuo Design un Nome (ti consigliamo di aggiungere " V2" in modo che sia ovvio che stai utilizzando Clerk.js2).

1.3. Scegli il Tipo di Design.

1.4. Clicca su Publish Design quando hai finito, e vai al Passo 2 nella guida.

1.5. Nell’Editor di Design, clicca su uno degli elementi esistenti come il nome, l’immagine, il pulsante, ecc. per modificarlo, o aggiungi nuovi elementi al Design per aggiungere più informazioni sui prodotti.

1.6. Clicca su Publish Questo causerà temporaneamente che non vengano visualizzati nel tuo webshop fino a quando non avrai finito con il Passo 2. Scegli il nuovo Design per tutto il Contenuto che dovrebbe essere aggiornato. 1.7. Infine, vai su Recommendations / Search -> Content e cambia il tuo Clerk.io Contenuto per utilizzare il tuo nuovo Design.

1.7. Ecco! Ora sei pronto per passare a Clerk.js 2.

Passo 2: Sostituire lo script #

2.1. Inizia localizzando il file di template utilizzato per mostrare tutte le pagine del webshop, e dove si trova lo script originale di Clerk.js vicino al fondo.

2.2. Rimuovi il vecchio script dal file:

2.3. Successivamente vai su my.clerk.io -> Settings -> Tracking Code. Questa pagina ora contiene il tuo codice di tracciamento Clerk.js 2.

2.4. Copia questo codice e inseriscilo appena prima del nel template:

2.5. Salva il tuo template.

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

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