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'integrazione, configurazione della connessione e test. Se hai già una connessione attiva con il plugin 1.5.x, vai a Aggiornare al plugin 2.x.

Prima di iniziare

Procurati questi tre elementi, così non devi interrompere la procedura a metà:

• l'accesso a Magento Admin con permessi di amministratore, e la collaborazione di chi gestisce l'istanza Magento per i comandi da shell;
• un Access key su repo.magento.com, e, solo se installi tramite composer, un account GitHub con l'accesso al repository del plugin, che è privato: va richiesto tramite l'Helpdesk e non è immediato, quindi richiedilo per primo. Se installi tramite lo zip scaricato da magnews non serve;
• una finestra di manutenzione, se stai aggiornando una connessione già attiva: durante il passaggio la sincronizzazione con Magento non è operativa.

Quale versione del plugin?

Il connettore comunica con Magento tramite un plugin PHP e rileva automaticamente la versione installata sulla tua istanza. La versione da usare è la 2.x: è quella che l'app distribuisce e l'unica a cui si riferiscono i passaggi di questa guida.

Rispetto alla generazione precedente, la 2.x protegge la comunicazione con Magento tramite una chiave di cifratura dedicata, si autentica con il token di un'integrazione di Magento invece che con utente e password, e gestisce le iscrizioni e le disiscrizioni tramite servizi dedicati del plugin.

Gli step per la connessione con il Magento Connector sono:

1. Installazione del plugin
2. Creazione dell'integrazione su Magento Admin
3. Recupero della chiave di cifratura
4. Configurazione della connessione su magnews

1. Installazione del plugin PHP

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

Sono disponibili due modalità di installazione. In entrambi i casi serve un Access key su repo.magento.com e devi fare 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. Ti serve un Personal Access Token GitHub con scope repo: se il tuo account non ha l'accesso al repository del plugin, scrivi all'Helpdesk per richiederlo prima di iniziare.
• Tramite zip: scarica lo zip del plugin, 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. Lo zip è disponibile in due punti:
  • da magnews, nella pagina Installazione del plugin Magento accessibile dalla Configurazione globale del connettore, che distribuisce sempre la versione più recente del plugin;
  • dalla pagina Releases del repository GitHub del plugin.

Completata l'installazione, abilita il modulo sulla tua istanza Magento:

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

Durante l'installazione il plugin genera automaticamente la chiave di cifratura che ti servirà al punto 3.

2. Creazione dell'integrazione su Magento Admin

Il modo consigliato per autenticare magnews su Magento è un token di accesso generato da un'Integrazione di Magento: non serve creare un utente né un ruolo, e i permessi restano circoscritti ai servizi del plugin.

a) Abilita i token Bearer (solo Magento 2.4.4 o superiore):
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 e 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. Recupero della chiave di cifratura

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:
  Chiave fissa (consigliata): incolla nell'apposito campo l'Access Token dell'integrazione creata al punto 2.
  Username e Password/API Key: inserisci User Name e Password di un utente amministratore di Magento, il cui ruolo abbia i permessi magnews Read, Newsletter e Configuration. Il token viene richiesto da magnews a ogni sessione.
• Chiave di cifratura query:
  incolla la chiave recuperata da Magento al punto 3. È obbligatoria: senza una chiave valida il test di connessione fallisce.
• 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, e ti avvisa se è disponibile una versione più recente.
Il link Installazione del plugin Magento resta disponibile anche dopo l'installazione, per scaricare di nuovo il plugin o rileggere le istruzioni.

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 al plugin 2.x

Se hai una connessione funzionante con il plugin 1.5.x e vuoi passare alla 2.x, segui questi passaggi. Il connettore rileva automaticamente la nuova versione, ma l'autenticazione e la cifratura vanno riconfigurate.

1. Rimuovi il plugin 1.5.x da app/code/MagNews/QueryService prima di installare il nuovo modulo, poi installa e abilita la 2.x come descritto al punto 1.
2. Crea l'integrazione su Magento e copia l' Access Token, come descritto al punto 2.
3. Recupera la chiave di cifratura generata durante l'installazione, come descritto al 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, al posto di User Name e Password usati dalla 1.5.x. Puoi anche restare su Username e Password/API Key, ma il passaggio all'integrazione è consigliato: verifica che il ruolo dell'utente abbia i permessi magnews Read, Newsletter e Configuration;
   • incolla la chiave nel campo Chiave di cifratura query, che con la 1.5.x era vuoto;
   • esegui il Test di connessione e salva.

Al termine, l'utente e il ruolo dedicati al plugin 1.5.x non sono più necessari e possono essere rimossi da Magento.

Plugin 1.5.x (legacy)

Questa sezione riguarda solo le connessioni già attive con il plugin 1.5.x, che continua a funzionare ma non viene più distribuito dall'app. Per le nuove installazioni usa la 2.x. Se stai aggiornando, vedi Aggiornare al plugin 2.x.

Utente e permessi (User Role)

Con la 1.5.x l'autenticazione avviene con utente e password, o API key, e richiede un profilo dedicato su Magento. Tra gli User Role di 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 su Magento le disiscrizioni dei contatti iniziate dalle newsletter di magnews. In questo modo i contatti restano disiscritti anche su magnews dopo gli import giornalieri.

Parametri di connessione su magnews

Nella Configurazione globale del connettore (punto 4) i parametri specifici della 1.5.x sono:

• Modalità di autenticazione: seleziona Username e Password/API Key e inserisci User Name e Password dell'utente creato su Magento.
• Chiave di cifratura query: lascia il campo vuoto, la cifratura della query è introdotta dalla 2.x.

Tutti gli altri parametri e i parametri tecnici sono identici a quelli del punto 4.

Prossimi passi

Completata la connessione, prosegui con:

• Configurazione dei negozi
• Workflow