FAQ

Hai riscontrato problemi con la tua integrazione Magento 2? Questa FAQ copre i problemi più comuni e le relative soluzioni, dalle dimensioni delle immagini agli errori di sincronizzazione.

Dimensioni delle immagini #

Per impostazione predefinita, l’estensione utilizza le dimensioni originali delle immagini che sono impostate in Magento 2.

Queste possono essere modificate se necessario.

Per iniziare, accedi al backend di Magento 2 e vai su:

Sotto Synchronization > Image type, scegli la risoluzione dell’immagine che vuoi inviare a Clerk.

Dopodiché, clicca su Save Config.

Ora devi semplicemente eseguire una nuova Sync in my.clerk.io e le nuove dimensioni delle immagini saranno importate.

Utilizzo dei formattatori #

Clerk.js ti permette di scrivere funzioni JavaScript personalizzate che aggiungono nuove funzionalità ai tuoi Designs.

I formattatori possono essere aggiunti in due modi:

• Tramite my.clerk.io > Developers > Formatters, dove ogni Formatter può essere creato come voce separata.

• Come configuration per Clerk.js, nello tracking-script che viene inserito su tutte le pagine, dove si possono aggiungere più formattatori contemporaneamente.

Per Magento 2, questo file contiene lo tracking-script:

vendor->view->frontend->templates->tracking.phtml

Esempio di formatter #

Un esempio è visibile qui sotto. Si prega di notare che questo vale per Clerk V2 (ultima versione):

    Clerk('config', {
      key: 'O7UITkJIXqXibeQF9ONobiGGKYYKtbvh',
      formatters: {
             log_price: function(price) {
             console.log(price);
    }
          }
      });

Più formattatori #

Puoi scrivere qualsiasi numero di Formatters separati da una virgola:

formatters: {
   log_price: function(price) {
      console.log(price);
   },
  calculate_discount: function(price, special_price) {
    return price - special_price;
   },
   substring: function(text) {
    var short_string = text.substring(0, 20);
      return short_string;
   }
}

Utilizzo nei designs #

Dopo aver creato i tuoi Formatter, puoi usarli nei tuoi Designs con questa sintassi:

{% raw %}{{ price | log_price }} {{ price | calculate_discount | special_price }}{% endraw %}

Questo ti permette di creare qualsiasi funzionalità nei tuoi Designs di cui hai bisogno.

Aggiunta al carrello con Form Key #

Magento 2 utilizza un form_key per la protezione CSRF. Quando crei bottoni Add to Cart nei designs Clerk, devi includere questo form_key affinché la funzionalità del carrello funzioni.

Lo script Clerk.js per Magento 2 include una variabile globale formkey integrata che contiene automaticamente il valore form_key dalla pagina.

Utilizzo nel tuo design #

Nel tuo design Clerk, includi il form_key come input nascosto all’interno del tuo form Add to Cart usando {{ formkey }}:

<form action="{{ product.url }}checkout/cart/add/product/{{ product.id }}" method="post">
    <input name="form_key" type="hidden" value="{{ formkey }}">
    <input type="hidden" name="product" value="{{ product.id }}">
    <input type="hidden" name="qty" value="1">
    <button type="submit" class="clerk-add-to-cart">Add to Cart</button>
</form>

Il globale {{ formkey }} è preconfigurato nell’estensione Magento 2, quindi non è necessaria alcuna configurazione aggiuntiva.

Autenticazione HTTP #

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

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

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

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

http://USER:PASS@magento2.clerk.io/

Errori comuni di sincronizzazione #

Nota: Si consiglia sempre di aggiornare l’estensione all’ultima versione per ottenere tutte le funzioni aggiornate di Clerk.

Quando si importano dati con l’estensione Magento 2 di Clerk, il server del tuo webshop è responsabile per l’invio dei dati di prodotto, categoria e vendite a Clerk.

Tuttavia, in alcuni casi, la configurazione del server può impedire l’importazione di accedere ai dati, causando un errore nella 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 di sviluppo richiede HTTP authentication per accedervi.

Può essere risolto inserendo Username e Password come parte dell’URL di importazione:

http://username:password@magento2.clerk.io

403 Forbidden #

Questo errore di solito si verifica per uno di questi motivi:

• Il server blocca l’importatore dall’accesso. Nella maggior parte dei casi, è sufficiente whitelistare l’indirizzo IP dell’importatore per dargli accesso. L’ultimo indirizzo IP può essere trovato qui.

• Potresti avere una public key, private key e/o import URL errati all’interno dello store in my.clerk.io.

• Stai usando Storeviews con URL nascosti, come mywebshop.com?__store=b2b. A volte, questi URL possono anche contenere 3 underscores, come: mywebshop.com?___store=b2b.

Se il tuo storeview utilizza un URL nascosto, includi il parametro __store nell’URL di importazione sotto Data > Configuration.

E se ho già whitelistato ma l’errore persiste comunque?

Ci sono alcuni casi in cui hai whitelistato l’indirizzo IP dell’importatore e l’errore persiste.

In questi casi, si consiglia di verificare quanto segue:

• La parte di autenticazione del corpo potrebbe essere rimossa dalla richiesta dal server del negozio.

• Limite di frequenza per il server in relazione a Cloudflare.

404 Not Found #

Questo errore si verifica se l’importatore non è riuscito ad accedere al link che invia i dati dal webshop.

Nella maggior parte dei casi, ciò accade perché l’estensione è:

• Non installata affatto

• Una cache impedisce l’inizializzazione del link

Per prima cosa, assicurati di aver installato correttamente l’estensione.

Poi, assicurati di svuotare la cache del tuo webshop prima di provare una nuova importazione.

429 Too Many Requests #

Questo errore si verifica se il server rifiuta l’accesso all’importatore a causa di troppe richieste in arrivo.

Puoi risolverlo aumentando il limite di richieste del server o impostando Page Size a un valore più alto in my.clerk.io > Data > Configuration. Una dimensione pagina maggiore fa sì che l’importatore invii meno richieste, ma più grandi.

Se stai utilizzando il provider hypernode.com/nl, l’importatore restituisce di solito questo errore a causa del loro rate limiter. In questo caso, contatta hypernode.com/nl e chiedi loro di whitelistare lo User-Agent dell’importatore “clerk”.

500 Internal Server Error #

Questo errore significa che il tuo server ha riscontrato un errore interno e non è stato in grado di specificare quale errore si sia verificato.

In questi casi, controlla il Server Log per identificare quale processo si è interrotto e perché.

Nella maggior parte dei casi, è semplicemente dovuto a un prodotto con un attributo non valido, o una funzione chiamata in modo errato nel webshop.

503 Service Unavailable #

Questo errore è solitamente temporaneo ed è causato dal server che è troppo occupato per gestire la richiesta.

Riprova più tardi.

Se il problema persiste, potrebbe significare che il server è sovraccarico di processi e vicino alla capacità massima.

Controlla il carico del server per identificare se questo è il caso.

Risposta non valida #

Questo errore si verifica di solito se il tuo webshop utilizza un sistema di redirect per inviare i clienti a domini diversi.

Ad esempio, andando su “ https://mywebshop.com” potresti essere reindirizzato a “ https://mywebshop.com/it".

Se il tuo webshop reindirizza a un dominio o percorso specifico per la lingua, utilizza quell’intero URL di destinazione come URL di importazione in my.clerk.io.

Importazione stock MSI #

Se il tuo store Magento 2 utilizza l’MSI (Multi-Source Inventory), puoi importare lo stock totale da tutte le fonti in Clerk aggiungendo il codice attributo riportato di seguito ai campi aggiuntivi dell’estensione.

1. Nel tuo admin di Magento, vai su Stores > Configuration > Clerk > Configuration.

2. Sotto Synchronization > Additional Fields, aggiungi: multi_source_stock.

3. Clicca su Save Config e poi esegui una nuova sincronizzazione in my.clerk.io > Data.

Clerk importerà multi_source_stock come somma delle quantità tra tutte le fonti MSI.

Questo è utile quando la fonte di stock predefinita è 0 ma i prodotti sono comunque disponibili in stock su altre fonti.

Aggiornamento a Clerk.js 2 #

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

Rende più semplice installare Clerk su qualsiasi webshop.

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

Le due principali differenze in Clerk.js 2 sono che i Designs in my.clerk.io utilizzano il linguaggio di templating Liquid, ma possono anche essere creati facilmente utilizzando il Design Editor.

Crea designs #

Poiché Clerk.js 2 adotta un approccio diverso per i Designs, è necessario crearne di nuovi.

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

• Utilizza l’intuitivo 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 (si consiglia di aggiungere “V2” così sarà chiaro che utilizzi Clerk.js 2).

3. Scegli il Tipo di Design.

4. Nel Design Editor, clicca su uno degli elementi esistenti come nome, immagine, pulsante, ecc. per modificarlo, oppure aggiungi nuovi elementi al Design per aggiungere più informazioni sui prodotti.

5. Fai click su Publish al termine e vai al Passo 2 della guida.

6. Vai su Recommendations/Search > Elements e cambia il tuo Clerk Element per usare il nuovo Design.

7. Clicca su Update Element. Temporaneamente, non saranno visualizzati sul tuo webshop finché non avrai terminato il Passo 2. Scegli il nuovo Design per tutti gli Element che devono essere aggiornati.

Ora sei pronto per passare a Clerk.js 2.

Aggiornamento dell’estensione #

ATTENZIONE: Ricorda di effettuare il backup di tutti i file modificati, poiché verranno sovrascritti.

L’aggiornamento dell’estensione Magento 2 si effettua tramite command line.

Si procede seguendo questi passi:

1. Accedi al tuo server tramite command line.

2. Vai nella cartella root del web (di solito _/var/www/your_domain/public_html_).

3. Abilita Root Access digitando su e inserendo la password.

4. Digita i seguenti comandi in ordine:

composer update clerk/magento2
php bin/magento setup:upgrade
php bin/magento setup:di:compile

5. Attendi il completamento dell’estensione.

Il tuo Magento 2 ora è aggiornato all’ultima versione.

Ora hai installato l’ultima versione di Clerk per Magento 2 e Clerk.js 2 è in esecuzione sul tuo webshop!

La documentazione completa di Clerk.js 2 è disponibile qui:

https://docs.clerk.io/docs/clerkjs-quick-start

Gestione di require.js #

Questa guida si applica solo se utilizzi fino alla versione 2.8.3 dell’estensione Clerk per Magento 2.

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 tuo console verrà visualizzato il seguente errore:

Uncaught ReferenceError: Clerk is not defined

L’estensione Magento 2 gestisce già Require.js, ma in alcuni casi è necessario che ignori Clerk.js.

Puoi farlo nel seguente file:

vendor->clerk->magento2->templates->tracking.phtml

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

Dopo aver utilizzato questo approccio, Require.js sarà ora compatibile con Clerk.