Extension

Configura le impostazioni dell’estensione Magento 2, gestisci le opzioni di sincronizzazione dei dati e personalizza le funzionalità di search, recommendations e logging. Questa guida copre anche l’installazione tramite Toolbox Script, l’aggiornamento e la disinstallazione.

Installazione con toolbox #

Lo script Clerk Toolbox è stato creato per facilitare l’installazione dell’estensione Clerk nel tuo webshop Magento senza utilizzare Magento Connect.

Il Toolbox Script verrà eseguito direttamente da un terminale.

Suggeriamo questi:

- Apple: iTerm, dovrai scaricarlo da Internet;

- Windows: Prompt dei comandi, è già installato nel tuo computer.

Lo script crea anche un backup della cartella Magento2 così da poter essere ripristinata in caso di problemi.

Cosa serve #

Per installare, è necessario avere accesso SSH o SFTP al tuo webshop, incluso Username e Password.

Navigare nella cartella #

1. Inizia accedendo al tuo server Magento tramite un terminale, utilizzando il tuo Username e Domain in questo modo:

ssh Stefan@mywebshop.com

2. Ti verrà chiesto di inserire la password del tuo Utente (il terminale non restituirà nessun feedback durante la digitazione, ma la password viene comunque registrata).

Naviga nella cartella root di Magento2. Puoi farlo scrivendo:

cd /var/www/html

e scrivendo:

ls

Il comando ls elenca le cartelle così puoi trovare la directory root di Magento.

Nell’elenco delle cartelle cerca quella giusta, in questo caso sarebbe magento2.

A questo punto devi solo entrare nella cartella, puoi farlo scrivendo:

cd NOME_CARTELLA

NOME_CARTELLA deve essere sostituito con il nome reale della cartella.

Installare l’estensione #

1. Quando sei nella Root Folder, devi scaricare il Toolbox Script con questa linea:

sudo wget https://raw.githubusercontent.com/clerkio/clerk-magento2/master/clerk_toolbox_magento2.sh

2. Poi digita questa linea per vedere l’elenco delle opzioni disponibili dentro il Toolbox:

sh clerk_toolbox_magento2.sh

3. Poiché vuoi installare l’estensione, userai -i insieme al numero dell’ultima versione dell’estensione. Digita questa linea:

sudo sh clerk_toolbox_magento2.sh -i

4. Ti verrà chiesto di inserire la password. Dopo averlo fatto, lo script effettuerà il backup della cartella Magento2 e inizierà l’installazione dell’estensione:

5. Fatto! Ora l’estensione è installata e puoi configurarla dal backend di Magento2.

Comandi opzionali #

Disinstallazione

Il Toolbox permette anche di disinstallare l’estensione. Puoi farlo con questa linea:

sudo sh clerk_toolbox_magento2.sh -u

Ripristino

In caso di problemi con il tuo webshop, puoi sempre ripristinare dal backup creato durante l’installazione dell’estensione.

Usa questa linea per farlo:

sudo sh clerk_toolbox_magento2.sh -r

Backup

Durante l’installazione dell’estensione, lo script crea sempre prima un backup, ma puoi anche crearne uno separatamente con questa linea:

sudo sh clerk_toolbox_magento2.sh -b

Impostazioni my.clerk.io #

Per accedere e modificare le impostazioni dati Magento 2 in Clerk, vai su my.clerk.io, clicca su “Data” dal menu laterale sinistro, poi su “Configuration”.

Nota: Le informazioni relative all’estensione Magento 2 Clerk, disponibili tramite il portale admin Magento, sono successivamente in questo articolo.

Qui puoi impostare la URL del tuo negozio, la dimensione delle pagine delle sincronizzazioni dati, nonché l’ora del giorno in cui i dati vengono sincronizzati con Clerk (l’impostazione predefinita è “quando necessario”).

Impostazioni dell’estensione #

Se usi la v6.7.0 o una versione successiva dell’estensione, potrai accedere alle seguenti impostazioni in due modi dopo aver aggiunto le Public e Private Keys all’estensione:

• Dal backend Magento2 in Stores > Settings > Configuration > Clerk > Configuration

• Da my.clerk.io, under Developers > Extensions

Non importa dove apporti le modifiche, l’estensione si sincronizzerà con qualsiasi cambiamento fatto su my.clerk.io e viceversa.

In my.clerk.io potrai anche visualizzare la tua versione attuale dell’estensione, la piattaforma e la versione PHP.

Clicca su Edit su un’impostazione per vedere le sue opzioni disponibili.

Panorama #

Per accedere alla tua estensione Clerk in Magento 2, accedi al portale admin del tuo webshop, poi segui il percorso Stores > Settings > Configuration > Clerk > Configuration

Generale #

Troverai il numero di versione della tua Clerk Extension, così come le public e private API keys del tuo store nella sezione General.

Per includere Pages nella sincronizzazione dei dati con Clerk, scegli “Yes” nel prossimo menu a tendina e inserisci eventuali campi aggiuntivi che vuoi includere nei dati delle pagine (ad esempio immagini o tipo di pagina) come valori separati da virgola.

Puoi anche impostare la lingua predefinita per i dati del negozio sincronizzato nell’ultimo menu a tendina in General.

Legacy Authentication #

Questa impostazione controlla se l’estensione utilizza autenticazione JWT header o il vecchio metodo della chiave privata. Disabilitare questa opzione è fortemente raccomandato, poiché JWT offre un flusso di autenticazione più sicuro e moderno per tutte le richieste API tra Magento 2 e Clerk.io.

Store ID #

Questo è un campo di configurazione legacy che non viene più utilizzato nelle installazioni moderne di Clerk.io. Può essere ignorato in sicurezza, dato che l’estensione identifica e gestisce automaticamente gli scope dei negozi usando le API native di Magento.

Sincronizzazione #

Nella sezione Synchronization del plugin Clerk, hai la possibilità di personalizzare i dati sincronizzati di clienti, ordini, carrelli e prodotti.

Le opzioni sono disabilitate e non modificabili quando si usa il dato del sito web, indicato dalla casella selezionata a destra di ciascuna sezione.

Basta deselezionare la casella appropriata per modificarla.

• Use Real-time Updates: scegli “Yes” per abilitare gli aggiornamenti in tempo reale dei dati sincronizzati con Clerk.

Con gli aggiornamenti in tempo reale abilitati, lo stock verrà ora aggiornato sia dopo gli ordini sia dopo il salvataggio dei prodotti nell’amministrazione Magento 2.

• Collect Emails: seleziona “Yes” qui per sincronizzare le email dei clienti.

• Collect Baskets: per raccogliere i dati dei carrelli e sincronizzarli con Clerk, seleziona “Yes” qui.

• Nei seguenti due menu a tendina, seleziona “yes” per sincronizzare solo i prodotti vendibili, e/o sincronizzare solo i prodotti con visibilità per Clerk.

• Se desideri disabilitare la sincronizzazione degli ordini, puoi farlo scegliendo “Yes” in questo menu a tendina.

Additional Fields #

Elenco separato da virgola degli attributi di prodotto extra che vuoi sincronizzare con Clerk.io (ad esempio, color, size, material). Questo ti permette di utilizzare questi attributi personalizzati nei design delle recommendations di Clerk.io, nei filtri di search, o nelle campagne email.

Search Non-Indexed Attributes #

Quando abilitato, Clerk.io effettuerà una query più profonda per recuperare i valori degli attributi personalizzati non pre-indicizzati nella raccolta prodotti standard di Magento. Questo assicura che tutti i campi personalizzati richiesti vengano sincronizzati con successo, sebbene potrebbe richiedere qualche risorsa server in più.

È come mandare un assistente molto educato a rovistare sugli scaffali polverosi del magazzino invece di leggere solo la lavagna all’ingresso.

Track Returned Orders #

Abilitando questa opzione, l’estensione rileverà la creazione di credit memo in Magento 2. I credit memos sincronizzano le variazioni di stock e tracciano gli articoli restituiti in Clerk.io.

Image Type #

Questo menu a tendina ti permette di selezionare quale tipo di immagine Magento e quali dimensioni (come immagine base, piccola o miniatura) debbano essere inviate a Clerk.io. È molto utile per adattare la qualità e il formato delle immagini al tema e al design specifico del tuo negozio.

Sincronizzazione clienti #

Abilita la sincronizzazione dei dati clienti scegliendo “Yes” dal menu a tendina in questa sezione.

Se hai attributi extra dei clienti che desideri includere nella sincronizzazione con Clerk, inseriscili nel campo di testo, separati da virgola.

Sync Subscribers #

Abilitando questa opzione sincronizzerai gli iscritti alla newsletter del tuo negozio con Clerk.io.

Per i clienti registrati che sono anche iscritti alla newsletter, l’estensione aggiornerà automaticamente il loro profilo cliente con subscribed: true e includerà il loro link di disiscrizione unico.

Per gli iscritti guest (ossia chi si è registrato alla newsletter ma non ha un account cliente), l’estensione li sincronizza come profili indipendenti—che in Clerk.io sono identificati semplicemente tramite l’indirizzo email—con un prefisso ID SUB. Questo assicura che tutti gli iscritti siano registrati senza creare duplicati per i clienti già esistenti. È estremamente utile per costruire audience complete per l’email marketing e condurre campagne personalizzate.

Search #

Abilita la Search Page del tuo negozio scegliendo “Yes” nel relativo menu a tendina.

• Dopo aver abilitato la Search Page, inserisci il nome dell’Element preso dal campo data-template del suo embed code. Ad esempio, usa search-page se quello è il nome del tuo Element.

• Puoi impostare le frasi " load more" e " no results" scrivendo il testo desiderato nei relativi campi di testo.

Includi categorie #

Abilitando questa opzione, includerai direttamente nei risultati di search principale anche i risultati delle categorie. Questo aiuta i clienti a navigare più facilmente mostrando collezioni e categorie rilevanti che corrispondono alla loro ricerca.

Numero di categorie #

Imposta il numero massimo di risultati di categorie da mostrare nella pagina di search. Ad esempio, impostando su 5 verranno mostrate fino a cinque categorie corrispondenti, permettendo agli utenti di saltare rapidamente nelle sezioni rilevanti del catalogo.

Numero di pagine #

Imposta il numero massimo di risultati di pagine CMS o di contenuto da mostrare nella pagina di search. È ideale per mostrare post blog, guide o pagine informative (come policy di reso) insieme ai prodotti.

Pages Type #

Filtra i tipi di pagine CMS o di contenuto che devono essere visualizzati nei risultati di ricerca. Puoi scegliere di mostrare solo pagine CMS standard, specifici post blog o tutte le pagine di contenuto sincronizzate su Clerk.io.

Live search #

• Dopo aver selezionato “Enabled” dal menu a tendina per abilitare la Live Search, scegli se Categories devono essere visualizzate nei risultati di search.

  • Puoi inoltre selezionare il numero di risultati di suggestions, categories e content da mostrare in Live Search oltre ai risultati dei prodotti.

• Hai anche la possibilità di scegliere quali page types visualizzare come risultati di ricerca, come “CMS Pages”, “Blog Posts”, o “All”.

• Puoi scegliere la posizione del menu a tendina di live search dalla search box con Dropdown Positioning.

• Fornisci il nome dell’Element per la tua live search, reperibile accanto a data-template nel codice embed della Live Search nel tuo Element su my.clerk.io. Probabilmente sarà live-search.

• Infine, puoi inserire il Live Search Input Selector e Form Selector, che puoi trovare ispezionando la search box del tuo webshop via browser e identificando l’ID o la classe associata al suo input e form.

  • Per un input con ID search, usa #search come input selector. Scegli la form selector più adatta al tuo shop.

Faceted navigation #

Per aggiungere facets alla tua Search Page, assicurati prima di selezionare “Enabled” nella casella di Faceted Navigation.

• Clicca sugli attributi che desideri aggiungere alle facets e salva la configurazione.

• Una volta aggiunti, gli attributi compariranno sotto Titles. In questa sezione puoi creare il Title da visualizzare per quella facet e la posizione in cui dovrà apparire nella lista delle facets.

Facets In Url #

Abilitando questa opzione verranno aggiunte le facets di ricerca selezionate (filtri) direttamente nei parametri della query URL del browser. Questo permette ai clienti di salvare nei segnalibri, aggiornare o condividere i risultati filtrati preservando l’esatto stato del filtro.

Multiselect Attributes #

Permette di selezionare quali facets di ricerca devono supportare la selezione di più opzioni contemporaneamente (ad esempio filtrando sia per colore “Rosso” che per “Blu”). Così l’esperienza di filtraggio sarà molto più flessibile e user-friendly.

Nota: Ora puoi richiamare i dati di categories e pages nella tua Search page come già avviene nella Live search, avendo così accesso a molte più informazioni per coinvolgere i clienti. Per maggiori informazioni puoi consultare qui.

Personalizzazione facets #

• Clerk permette di personalizzare le facets della search page direttamente dal design, visualizzandole tramite il field design ID.

• Il design ID si trova nel backend Clerk, nella colonna più a sinistra di ogni design nella pagina panoramica dei design e in basso a sinistra della pagina una volta che sei entrato a modificare il design.

Powerstep ed exit intent #

Simile a Search, abilita Powerstep di Clerk selezionando “Yes” dal menu a tendina, poi scegli il tipo di powerstep che vuoi visualizzare (Page o Popup).

• Inserisci il nome dell’Element del Powerstep dal suo embed code, campo data-template. Ad esempio, usa power-step-others-also-bought se quello è il nome del tuo Element.

• Segui la stessa procedura per abilitare l’Exit Intent e individua e aggiungi il giusto Exit Intent Element.

Powerstep Filter Duplicates #

Abilitando questa funzione si evitano prodotti duplicati su più slider dentro Powerstep. Se un prodotto è già visualizzato in uno slider, Clerk.io lo escluderà automaticamente dagli slider successivi nella stessa pagina.

Recommendations #

Anche queste, come per Search, si abilitano le impostazioni Product, Category e Cart Page di Clerk selezionando “Enabled” dai relativi menu a tendina.

• Come per Search, puoi trovare il nome dell’element accanto a data-template nell’embed code dentro my.clerk.io > Recommendations > Elements.

  • Ad esempio, puoi abilitare Category, Product e Cart Page settings e assegnare category-page-popular, product-page-alternatives, product-page-others-also-bought, e cart-others-also-bought alle rispettive pagine.

Category Filter Duplicates #

Abilitando questa funzione si evitano prodotti duplicati raccomandati su più slider nelle pagine di categoria. Garantisce ai clienti una gamma diversificata di prodotti, senza vedere lo stesso articolo ripetuto in sezioni diverse.

Product Filter Duplicates #

Abilitando questa funzione evita prodotti duplicati raccomandati su più slider nelle pagine di dettaglio prodotto. Mantiene la freschezza delle recommendations e massimizza le possibilità di attirare il cliente con prodotti diversi.

Cart Filter Duplicates #

Abilitando questa funzione evita prodotti duplicati raccomandati su più slider nella pagina carrello. Molto efficace per il cross-selling, assicura una varietà ampia e interessante di possibili aggiunte last-minute.

Dopotutto, se un cliente ha già rifiutato di comprare un tostapane verde fosforescente nel primo slider, riproporglielo altre tre volte prima del checkout difficilmente cambierà idea, e anzi potrebbe metterlo in dubbio sulla sanità mentale dello shop.

Logging #

Per modificare le impostazioni di logging, apri Stores > Configuration > Clerk > Configuration nel backend Magento 2.

Trova il menu a tendina denominato Logging Settings e imposta la configurazione preferita.

Clicca su Save per applicare le modifiche.

Le opzioni logging includono:

Scegli livello di logging

• Only Errors: Registra solo gli errori che impediscono il corretto funzionamento del modulo.

• Error + Warn: Registra anche gli avvisi che non bloccano il modulo, ma che potrebbero dover essere risolti.

• Error + Warn + Debug: Registra tutto ciò con cui il modulo interagisce. Da non abilitare su un webshop live perché rallenta il sito.

Scegli dove loggare

• File: Salva il log su un file nel server Magento2.

• my.clerk.io: Registra tutto in Developers->Logs nel backend di my.clerk.io.

Log File Link #

Mostra il percorso assoluto del file di log locale sul server Magento (tipicamente /var/log/clerk_log.log). Così sviluppatori e amministratori potranno trovare e consultare facilmente i file di log grezzi per il debug del comportamento dell’estensione.

Aggiornamento #

Se usi una versione antecedente la 3.0.0, l’aggiornamento romperà i tuoi Designs, poiché verrà usato Clerk.js 2. Se usi una versione più vecchia, segui questa guida.

Importante: ricordati di fare il backup di qualsiasi file modificato, perché verrà sovrascritto.

L’aggiornamento dell’estensione Magento 2 avviene tramite commandline.

Si esegue seguendo questi passaggi:

1. Accedi al tuo server tramite commandline.

2. Vai nella cartella webroot (di solito “/var/www/your_domain/public_html”)

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

4. Inserisci i seguenti comandi uno dopo l’altro:

   composer update clerk/magento2

   php bin/magento setup:upgrade

   php bin/magento setup:di:compile

5. Attendi il termine della procedura.

Ora Magento 2 è aggiornato all’ultima versione.

Disinstallazione #

Come per l’installazione delle estensioni su Magento 2, anche la disinstallazione va fatta da Command Line.

Basta inserire i seguenti comandi nell’ordine corretto per rimuoverla:

1. php bin/magento setup:module:disable Clerk_Clerk

2. composer remove clerk/magento2