FAQ

Hai problemi con l’integrazione Magento 1? Questa FAQ copre i problemi più comuni e le relative soluzioni, dalla conversione valuta agli errori di sincronizzazione.

Conversione valuta #

Dalla versione v3.0.3 dell’estensione Magento 1, la conversione valuta è inclusa di default, se si utilizza la funzione standard di conversione di Magento 1.

È aggiunta in my.clerk.io -> Designs, con il formattatore price_in_currency.

L’helper può essere aggiunto al Design nel modo seguente:

{%raw%}
<div class="clerk-product-price">
{{ product.price_final_excl_tax | price_in_currency }}
</div>{%endraw%}

L’helper convertirà automaticamente il prezzo nella valuta della sessione corrente e aggiungerà il simbolo della valuta.

Esempio di output:

Utilizzo dei formattatori #

Clerk.js 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 una configuration per Clerk.js, nello script di tracking inserito in tutte le pagine, dove possono essere aggiunti più formattatori contemporaneamente.

Per Magento 1, questo file contiene lo script di tracking:

app->design->frontend->base->default->template->clerk->tracking.phtml

Esempio di formatter #

Un esempio è riportato di seguito. Tieni presente che si riferisce a Clerk V2 (ultima versione):

Clerk('config', {
  key: 'O7UITkJIXqXibeQF9ONobiGGKYYKtbvh',
  formatters: {
    form_key: function () {
      return '<?php echo $this->getFormKey(); ?>';
    },
    price_in_currency: function(price) {
      price = Math.round(price * 100) / 100;
      var price_converted = Math.round((price * <?php echo (float)$rates[$currentCurrencyCode]; ?>) * 100) / 100;
      var retVal = <?php echo json_encode($currentCurrencySymbol); ?> + ' ' + price_converted.toFixed(2).toString();
      return retVal;
    },
    log_price: function(price) {
      console.log(price);
    }
  }
});

Formattatori multipli #

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;
  }
}

Uso nei design #

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

{%raw%}{{ x formatter | attribute }} {{ x | formatter | attribute1 | attribute2 }}{%endraw%}

Ciò ti consente di creare qualsiasi funzionalità necessaria nei tuoi Designs.

Autenticazione HTTP #

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

Ciò bloccherà il Clerk Importer e mostrerà un errore 401 Unauthorized nel log della sincronizzazione.

Puoi risolvere inserendo le credenziali di autenticazione nell’URL di importazione.

In my.clerk.io > Data > Configuration, aggiorna il tuo import URL così:

http://USER:PASS@magento.clerk.io/clerk/api/store/1

Errori comuni di sincronizzazione #

Nota: raccomandiamo di aggiornare sempre l’estensione all’ultima versione per ottenere tutte le funzionalità più aggiornate da Clerk.

Durante l’importazione dei dati con l’estensione Magento 1, il server del tuo webshop è responsabile dell’invio di dati di prodotti, categorie e vendite a Clerk.

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

Di seguito 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 l’accesso.

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

http://username:password@magento.clerk.io/clerk/api/store/1

403 Forbidden #

Questo errore si verifica se il server blocca l’accesso all’importer.

Nella maggior parte dei casi, basta whitelistare l’indirizzo IP dell’importer per fornire l’accesso.

L’indirizzo IP più recente si trova qui.

Controlla anche che la tua public key, la private key e l’import URL siano corretti per lo store che stai operando all’interno di my.clerk.io.

Cosa fare se hai già whitelistato ma l’errore si verifica ancora?

Ci sono alcuni casi in cui l’indirizzo IP dell’importer è stato whitelistato, ma l’errore persiste.

In questi casi, ti consigliamo di controllare questi aspetti:

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

• Limitazione delle richieste (rate limit) sul server, ad esempio con Cloudflare.

404 Not Found #

Questo errore si verifica se l’importer non riesce ad accedere al link che invia dati dal webshop.

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

• Non installata

• Una cache causa la mancata inizializzazione del link

Verifica prima di aver installato correttamente l’estensione.

Assicurati poi 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’importer a causa di troppe richieste in arrivo.

Puoi risolvere aumentando il limite di richieste per il tuo server oppure impostando Page Size ad un valore più alto in my.clerk.io > Data > Configuration, causando così che l’importer effettui meno richieste, ma più grandi:

Se usi l’host provider Byte.nl, l’importer restituisce solitamente questo errore a causa del loro rate limiter. In questo caso, contatta Byte.nl e chiedi di whitelistare lo User-Agent dell’importer “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 è capitato.

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

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

503 Service Unavailable #

Questo errore è di solito temporaneo e causato dal server troppo occupato per gestire la richiesta.

Riprova più tardi.

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

Controlla il carico sul server per verificare se questa è la causa.

Errore API Magento #

Questo errore significa sempre che il tuo server ha avuto un errore interno e non è riuscito a specificare quale errore o codice di errore è capitato.

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

Nella maggior parte dei casi, il problema è semplicemente un prodotto con attributi non validi, o il superamento del limite di memoria.

Powerstep non visibile #

Se il passaggio Aggiungi al carrello non è attivato, solitamente dipende da due motivi:

• Hai un altro popup o funzione di aggiunta al carrello abilitata che blocca la funzione di Clerk.

• Sono stati inseriti ID di elemento errati nell’estensione.

Altro popup abilitato #

Inizia controllando la tua installazione Magento per vedere se hai già un popup o dropdown che appare durante l’aggiunta di un prodotto al carrello.

Questi possono normalmente bloccare il passaggio di aggiunta al carrello di Clerk.

Se questo è il caso, disabilitalo e riprova.

ID elemento errati #

Se non hai altri popup di aggiunta al carrello, e il powerstep è attivato ma non visibile, probabilmente sono stati inseriti ID template errati nelle impostazioni dell’estensione Clerk.

Ciò farà fallire il Powerstep.

Per risolvere, accedi all’admin Magento e vai su System > Configuration > Clerk > Settings.

Scegli quindi il Configuration Scope corretto per il tuo store.

Sotto Power step settings, controlla il campo Templates.

Questo campo dovrebbe contenere gli ID corretti separati da virgola, se ne usi più di uno.

Per assicurarti che i tuoi ID siano corretti, accedi a my.clerk.io.

Scegli lo Store corretto e vai su Recommendations/Search > Elements.

Clicca su Edit Element per uno slider che vuoi mostrare nel powerstep.

Controlla l’ultima scheda “Insert into website” e individua il codice embed.

L’ID trovato in data-template è l’ID che devi copiare nell’estensione Magento:

Clicca su Save Config nell’estensione Magento e il Powerstep dovrebbe poi funzionare.

Problemi di cache #

Se hai attivato il popup powerstep e non appare ancora aggiungendo un prodotto al carrello, spesso la causa è la cache.

1. Vai su System > Cache e svuota tutte le cache interne e di terze parti.

2. Se non risolve, probabilmente stai usando la Full Page cache, che influisce solo sulle pagine già visitate nella sessione di un visitatore. La disattivazione avrà un impatto minimo sulla velocità della pagina.

3. Lo screenshot seguente mostra esattamente quale disattivare:

Dopo aver disattivato la Full Page Cache, il popup Clerk dovrebbe comparire.

Altrimenti, contatta Clerk Support tramite l’icona della chat in basso a destra e ti aiuteremo a trovare una soluzione adatta alla tua configurazione.

Slider della homepage in cache #

Di solito ciò succede solo se i codici embed sono inseriti tramite le CMS Pages nel backend di Magento, poiché la homepage è in cache:

Invece, i codici embed dovrebbero essere inseriti direttamente nei file della homepage tramite FTP:

Magento non metterà in cache i risultati se inseriti in questo modo.

Immagini non visibili #

Quando la cache immagini di Magento viene svuotata, manualmente o automaticamente, tutti i percorsi delle immagini cambiano.

Questo significa che i percorsi delle immagini inviati a Clerk non funzionano più.

Puoi risolvere facilmente così:

1. Accedi a my.clerk.io.

2. Clicca sullo Store in cui mancano le immagini.

3. Vai su Data.

4. Clicca su Start New Data Sync in alto a destra.

Verrà avviata una nuova sincronizzazione completa dei prodotti, permettendo a Clerk di ottenere i percorsi immagini corretti.

Nell’estensione Magento di Clerk v2.1.0, il problema viene risolto avviando automaticamente una sincronizzazione quando la cache immagini viene svuotata.

Se usi una vecchia versione dell’estensione, si consiglia vivamente di aggiornarla all’ultima versione.

Aggiorna a Clerk.js 2 #

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

Rende più facile l’installazione di Clerk su qualsiasi webshop.

Poiché le due versioni funzionano in modo leggermente diverso, dovrai seguire questi passaggi per un upgrade riuscito.

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

Crea design #

Poiché Clerk.js 2 adotta un approccio diverso ai Designs, sarà necessario crearne di nuovi.

Puoi creare i Design di Clerk.js 2 in due modi:

• Usa l’intuitivo Design Editor per crearli, 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. Scegli il tipo di Design.

3. Nel Design Editor, clicca su qualsiasi elemento (nome, immagine, pulsante, ecc.) per modificarlo oppure seleziona nuovi elementi da aggiungere al Design.

4. Clicca su Publish quando hai finito e vai al Punto 2 della guida.

5. Vai su Recommendations/Search > Elements e cambia il Clerk Element affinché usi il nuovo Design.

6. Clicca su Update Element. Questo farà sì che temporaneamente non compaiano più sul tuo webshop finché non avrai completato il Punto 2. Scegli il nuovo Design per tutti gli Element che devono essere aggiornati.

Ora sei pronto a passare a Clerk.js 2.

Aggiorna estensione #

Se hai già l’ultima versione dell’estensione Clerk Magento puoi saltare questo passaggio.

Puoi scaricare l’ultima versione dell’estensione a questo link:

https://github.com/clerkio/clerk-magento/releases/latest

Salva le modifiche #

Prima di tentare l’aggiornamento, assicurati di aver:

• Salvato localmente i file modificati tramite FTP, oppure
• Eseguito un backup dei file modificati, che potrai trasferire nella nuova estensione.

Gli sviluppatori modificano solitamente i file Product.php e Productbase.php, che gestiscono gli attributi prodotto.

Questi file si trovano qui:

app->code->community->Clerk->Clerk->Model->Catalog->Product.php

app->code->community->Clerk->Clerk->Model->Catalog->Productbase.php

Disattiva estensione #

Prima di tentare l’aggiornamento, è fondamentale fare quanto segue:

1. Disattiva la vecchia estensione nella pagina System > Configuration > Clerk > Settings di Magento. Imposta Enable su No e clicca su Save Config.

2. Quindi, disinstallala tramite Magento Connect o eliminando i file da FTP se l’hai installata manualmente.

Altrimenti, la pagina Configuration potrebbe smettere di funzionare e nessuna delle estensioni funzionerà più dopo.

Installa estensione #

Per finire, installa nuovamente l’ultima versione dell’estensione e sposta su FTP i file salvati in precedenza.

La tua configurazione dovrebbe essere conservata anche installando la nuova versione.

Controlla System > Configuration > Clerk per verificare che tutto sia ancora presente.

Ora hai l’ultima versione di Clerk per Magento installata e Clerk.js 2 operativo sul tuo webshop!

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

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

Gestione di require.js #

Valido solo per la versione v.3.7.2 o inferiore dell’estensione Clerk Magento 1.

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

Quando ciò accade, nel console apparirà il seguente errore:

Uncaught ReferenceError: Clerk is not defined

Ci sono due modi per gestire Require.js. Entrambi richiedono modifiche allo script di tracking in questo file:

app->design->frontend->base->default->template->clerk->tracking.phtml

Inclusione in Require.js #

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

Si può fare inserendo require(['clerk'], function() {}); in fondo allo script di tracking:

Ignorare Require.js #

Se la soluzione precedente non funziona, è possibile ignorare Require.js.

Basta inserire window.__clerk_ignore_requirejs = true; in cima allo script di tracking:

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