Installa il plugin e connetti magnews a Magento

Per utilizzare il Magento Connector devi completare il setup prima sul backend di Magento e poi nelle impostazioni del connettore in magnews. Questa guida copre l'intero percorso: installazione del plugin, creazione dell'utente/integrazione, configurazione della connessione e test.

Quale versione del plugin?

Il connettore funziona con due generazioni del plugin PHP e rileva automaticamente quella installata sulla tua istanza Magento. Alcuni passaggi cambiano a seconda della versione:

• Plugin v1 (versioni 1.5.x): la generazione storica dell'integrazione; l'autenticazione avviene con utente e password/API key e la riscrittura delle disiscrizioni su Magento richiede un permesso di scrittura sul ruolo.
• Plugin v2 (versioni ≥ 2.0.0): la generazione più recente, con un livello di sicurezza aggiuntivo nella comunicazione con Magento (protetta da una chiave dedicata) e con iscrizioni/disiscrizioni gestite tramite servizi dedicati del plugin.

Nei passaggi che seguono, dove il comportamento cambia, sono indicate le istruzioni specifiche per Plugin v1 e Plugin v2.

Gli step per la connessione con il Magento Connector sono:

1. Installazione del plugin
2. Configurazione dell'accesso su Magento Admin
3. Generazione della chiave di cifratura (solo Plugin v2)
4. Configurazione della connessione su magnews

1. Installazione del plugin PHP

Il plugin PHP Magento è un modulo da installare sulla tua istanza Magento e permette la comunicazione tra magnews e Magento. Chiedi a chi gestisce la tua istanza Magento di seguire le istruzioni contenute nella pagina Installazione del plugin Magento, accessibile dalla Configurazione globale del connettore, e nel file README incluso nel plugin.

Plugin v1: Installazione (1.5.x)

Sono disponibili due modalità di installazione:

• Completamente automatica: tramite composer.
• Semi-automatica: una parte tramite composer e una parte tramite un file zip.

Plugin v2: Installazione (≥ 2.0.0)

Sono disponibili due modalità di installazione. In entrambi i casi fai riferimento al file README del plugin per i comandi completi.

• Tramite composer (consigliata): configura i token di autenticazione per repo.magento.com e GitHub, aggiungi il repository del plugin e installa con composer require magnews/magento-query-service. Segui la sezione Install using composer del README.
• Tramite zip: scarica lo zip dalla pagina Releases del repository, installa la dipendenza composer require greenlion/php-sql-parser e scompatta l'archivio sotto app/code/MagNews/QueryService. Segui la sezione Install with zip file del README.

2. Configurazione dell'accesso su Magento Admin

Dopo aver installato il modulo MagNews_QueryService, abilitalo sulla tua istanza Magento:

bin/magento module:enable MagNews_QueryService
bin/magento setup:upgrade
bin/magento cache:clean
bin/magento setup:di:compile

Il modo in cui magnews si autentica su Magento dipende dalla versione del plugin.

Plugin v1: Utente e permessi (User Role)

Una volta abilitato il modulo avrai a disposizione un nuovo permesso tra gli User Role disponibili su Magento Admin. Crea un nuovo profilo con entrambi i permessi Read e Write e assegnalo all'utente da usare nella connessione. Il permesso Write serve per riportare le disiscrizioni dei contatti iniziate dalle nostre newsletter anche su Magento, in modo che restino disiscritti su magnews a seguito degli import giornalieri.

Plugin v2: Integrazione e token di accesso

Con il plugin v2 l'autenticazione avviene tramite un token di accesso generato da un'Integrazione di Magento (non serve creare un utente/ruolo).

a) Abilita i token Bearer (solo Magento ≥ 2.4.4):
Stores > Configuration > Services > OAuth > Consumer Settings → Allow OAuth Access Tokens to be used as standalone Bearer tokens = Yes.

b) Crea l'integrazione:

1. Vai in System > Extensions > Integrations e clicca Add New Integration.
2. Assegna un nome (es. "magnews").
3. Nella scheda API assegna i permessi:
   • magnews > Read: esecuzione query e lettura configurazione;
   • magnews > Newsletter: iscrizione/disiscrizione alla newsletter;
   • magnews > Configuration: accesso alla configurazione.
4. Salva e Attiva l'integrazione.
5. Copia l'Access Token: ti servirà nella configurazione della connessione su magnews (punto 4).

3. Generazione della chiave di cifratura (solo Plugin v2)

Con il plugin v2 la comunicazione con Magento è protetta tramite una chiave di cifratura, generata automaticamente durante l'installazione del modulo, che dovrà essere incollata nella configurazione della connessione su magnews (campo Chiave di cifratura query).

Per recuperarla su Magento:

1. Vai in Stores > Configuration > magnews > Query Service > Encryption Settings.
2. Copia il valore del campo Encryption Key.
3. Incollalo nel campo Chiave di cifratura query della configurazione della connessione su magnews (punto 4).

Se necessario puoi generare una nuova chiave con il pulsante Regenerate Key.

4. Configurazione della connessione su magnews

Una volta configurato il modulo in Magento, spostati nella sezione Configurazione globale del connettore seguendo il percorso:
Gestione > Magento Connector > Configurazione globale.

Connessione a Magento

I parametri di questa sezione configurano nel dettaglio la connessione tra la piattaforma e Magento. Inserisci i seguenti valori:

• URL Web Services:
  indica l'indirizzo del servizio REST, ad esempio: https://www.mystore.com/index.php/rest
• Modalità di autenticazione:
  Plugin v1: seleziona Username e Password/API Key e inserisci User Name e Password dell'utente creato su Magento.
  Plugin v2: seleziona Chiave fissa e incolla nell'apposito campo l' Access Token dell'integrazione creata al punto 2.
• Chiave di cifratura query (solo Plugin v2):
  incolla la chiave recuperata da Magento al punto 3. È obbligatoria con il plugin v2: senza una chiave valida il test di connessione fallisce. Con il plugin v1 il campo va lasciato vuoto.
• Timeout connessione HTTP:
  se il server di Magento risulta troppo lento a rispondere, aumenta il valore; altrimenti lascia il default.
• Disabilita controllo di validità dei certificati:
  disabilita il controllo di validità dei certificati di sicurezza.
• Il server web richiede un'autenticazione:
  se il server web richiede autenticazione, attiva l'opzione e inserisci nome utente e password.
• Il server web richiede autenticazione per le immagini del frontend di Magento:
  se il server web richiede autenticazione per mostrare le immagini del frontend, attiva l'opzione e inserisci nome utente e password.

Il campo Stato indica se magnews è effettivamente connesso a Magento.
Il campo Plugin di piattaforma mostra la versione del plugin installato su Magento, rilevata automaticamente dal connettore.
Il plugin da installare su Magento è disponibile (anche dopo l'installazione) cliccando sul link Installazione del plugin Magento.

Test di connessione

Completata la configurazione dei parametri di base, effettua un test cliccando sul bottone Test di connessione. Il test verificherà che magnews e Magento siano effettivamente connessi. Se l'esito è positivo, clicca su Salva in alto a destra e conferma o personalizza le ulteriori impostazioni mostrate nella pagina.

Parametri tecnici

I parametri tecnici consentono di ottimizzare le performance di alcuni aspetti della sincronizzazione tra il connettore e la piattaforma.

• Dimensione di pagina: numero di contatti per pagina processati dalla sincronizzazione contatti. Più il numero è elevato più l'operazione è veloce, ma richiede un server di Magento con risorse maggiori.
• Timezone: la modifica del timezone (UTC di default) potrebbe comportare problemi con le date. Cambia questo valore solo se sei sicuro di operare in una regione con un timezone differente.

• Time-to-live cache immagini (minuti): per quanti minuti la piattaforma mantiene in memoria le immagini scaricate da Magento (0 = caching disattivato).

Dopo aver verificato la correttezza dei parametri tecnici, collega il connettore alla piattaforma Magento cliccando sul bottone Aggiorna le definizioni.

Aggiornare dal plugin v1 al v2

Se hai già una connessione funzionante con il plugin v1 (1.5.x) e vuoi passare al plugin v2, segui questi passaggi. Il connettore rileva automaticamente la nuova versione, ma l'autenticazione e la cifratura vanno riconfigurate.

1. Rimuovi il plugin v1 e installa il plugin v2 (via composer o zip) come descritto al punto 1, poi abilita il modulo con i comandi bin/magento del punto 2.
2. Crea l'integrazione su Magento (System > Extensions > Integrations) con i permessi magnews > Read / Newsletter / Configuration, attivala e copia l' Access Token (vedi punto 2). Se usi Magento ≥ 2.4.4 abilita anche i token Bearer.
3. Recupera la chiave di cifratura generata durante l'installazione da Stores > Configuration > magnews > Query Service > Encryption Settings (vedi punto 3).
4. Aggiorna la configurazione della connessione su magnews (punto 4):
   • imposta la Modalità di autenticazione su Chiave fissa e incolla l'Access Token;
   • incolla la chiave nel campo Chiave di cifratura query;
   • esegui il Test di connessione e salva.

Al termine, l'utente/ruolo dedicato al plugin v1 non è più necessario e può essere rimosso da Magento.

Prossimi passi

Completata la connessione, prosegui con:

• Configurazione dei negozi
• Workflow