FAQ

Hai problemi con l’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 impostate in Magento 2.

Queste possono essere modificate se necessario.

Inizia accedendo al backend di Magento 2 e vai su:

Sotto Synchronization > Image type, puoi scegliere esattamente quale risoluzione inviare per le immagini:

Successivamente, clicca su Save Config.

Ora ti basta eseguire una nuova Sync in my.clerk.io e le nuove dimensioni delle immagini verranno importate.

Utilizzo dei formattatori #

Clerk.js ti consente 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 inserito in tutte le pagine, dove possono essere aggiunti più formattatori contemporaneamente.

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

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

Esempio di formatter #

Un esempio può essere visto di seguito. Nota che è 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 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 design #

Dopo aver creato i tuoi Formatters, puoi utilizzarli nei tuoi Designs usando 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 una form_key per la protezione CSRF. Quando crei pulsanti “Aggiungi al carrello” nei design Clerk, è necessario includere questa form_key affinché la funzionalità del carrello funzioni.

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

Utilizzo nel tuo design #

Nel tuo design Clerk, includi la form_key come input hidden 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>

La variabile globale {{ formkey }} è preconfigurata nell’estensione Magento 2, quindi non è necessaria alcuna configurazione aggiuntiva.

Autenticazione HTTP #

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

Questo bloccherà l’importatore Clerk e mostrerà un errore 401 Unauthorized nel registro 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 in questo modo:

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

Errori comuni di sincronizzazione #

Nota: Si consiglia di aggiornare sempre l’estensione all’ultima versione per usufruire di tutte le nuove funzionalità di Clerk.

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

Tuttavia, in alcuni casi, la configurazione del server potrebbe bloccare l’importazione impedendo l’accesso ai dati, causando un errore in 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 autenticazione HTTP per accedervi.

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

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

403 Forbidden #

Questo errore spesso si verifica per uno dei seguenti motivi:

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

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

• Stai utilizzando Storeviews con URL nascosti, come mywebshop.com?__store=b2b. A volte questi URL possono anche contenere 3 trattini bassi, ad esempio: mywebshop.com?___store=b2b.

Se questo è il caso, includi semplicemente il parametro __store nell’URL in Data:

Cosa fare se ho già fatto la whitelist ma si verifica ancora lo stesso errore?

A volte, anche avendo whitelistato l’indirizzo IP dell’importatore, 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 dello shop.

• Limitazione di frequenza del server in relazione a Cloudflare.

404 Not Found #

Questo errore si verifica se l’importatore non ha potuto accedere al link che invia i dati dal webshop.

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

• Non installata affatto

• Una cache fa sì che il link non venga inizializzato

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

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

429 Too Many Requests #

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

Puoi risolverlo impostando un valore più alto per il request limit sul tuo server oppure aumentando il valore di Page Size in my.clerk.io > Data > Configuration, facendo sì che l’importatore effettui richieste meno frequenti ma più grandi:

Se utilizzi il provider hypernode.com/nl, l’importatore di solito restituisce questo errore a causa del loro rate limiter. In questo caso, contatta hypernode.com/nl e chiedi 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 è verificato.

In questi casi, controlla il Server Log per identificare quale processo è andato in crash e perché.

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

503 Service Unavailable #

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

Riprova più tardi.

Se il problema continua a persistere, potrebbe significa che il server è sovraccarico di processi e vicino alla massima capacità.

Controlla il carico del server per verificare se è così.

Risposta non valida #

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

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

Se è questo il caso, è sufficiente utilizzare l’URL completo durante l’importazione in my.clerk.io:

Importazione stock MSI #

Se il tuo store Magento 2 utilizza MSI (Multi-Source Inventory), puoi importare lo stock totale da tutte le fonti in Clerk aggiungendo il codice attributo qui sotto ai Campi Aggiuntivi dell’estensione.

1. Nel tuo admin 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 la somma delle quantità di tutte le fonti MSI.

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

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 qualsiasi webshop.

Tuttavia, dato che 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 che i Designs in my.clerk.io utilizzano il linguaggio di template Liquid, ma possono essere creati anche facilmente tramite il Design Editor.

Creazione dei design #

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

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

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

• 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, assegna un Nome al tuo Design (si consiglia di aggiungere “V2” in modo che sia evidente che stai usando Clerk.js 2).

3. Seleziona Design Type.

4. Nell’Design Editor, fai clic su uno qualsiasi degli elementi esistenti come nome, immagine, bottone ecc. per modificarlo, oppure aggiungi nuovi elementi al Design per aggiungere più informazioni sui prodotti.

5. Clicca su Publish quando hai terminato e vai su Step 2 della guida.

6. Vai su Recommendations/Search > Elements e cambia il tuo Clerk Element affinché utilizzi il nuovo Design.

7. Clicca su Update Element. Questo farà sì che, temporaneamente, non venga visualizzato sul tuo webshop finché non avrai terminato lo Step 2. Scegli il nuovo Design per tutti gli Element che devono essere aggiornati.

Ora sei pronto a passare a Clerk.js 2.

Aggiornamento dell’estensione #

ATTENZIONE: ricordati di eseguire il backup di tutti i file modificati, perché verranno sovrascritti.

L’aggiornamento dell’estensione Magento 2 si effettua tramite linea di comando.

Ecco come fare:

1. Accedi al server tramite linea di comando.

2. Naviga nella cartella webroot (di solito _/var/www/your_domain/public_html_).

3. Abilita Root Access digitando su e inserisci 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 che il processo termini.

Magento 2 è ora aggiornato all’ultima versione.

Hai ora l’ultima versione di Clerk per Magento 2 installata e Clerk.js 2 è attivo nel tuo webshop!

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

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

Gestione di require.js #

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

In alcune configurazioni, Require.js impedisce il caricamento di Clerk.js; di conseguenza, non vengono mostrati né slider né risultati di ricerca.

Quando ciò accade, nel tuo console apparirà questo errore:

Uncaught ReferenceError: Clerk is not defined

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

È possibile farlo nel seguente file:

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

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

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