Risoluzione dei problemi

Quasi tutti i problemi si riconducono a una manciata di cause. Qui sono ordinate in base a quanto spesso i merchant le incontrano, e ognuna ha la sua soluzione.

“Ho collegato tutto ma non sincronizza niente”

Quasi sempre si tratta di una di due cose, ed entrambe hanno una verifica veloce.

1. Il cron non è in esecuzione. La sincronizzazione avviene tramite una coda in background, quindi senza cron non viene inviato nulla. L’estensione però ti avvisa: la card Mailchimp sulla Dashboard dell’admin passa a Background sync paused, e il riquadro System status sul Cron Monitor indica la pianificazione bloccata. Per averne conferma, apri la scheda Queue Monitor (Marketing → Intuit Mailchimp → Dashboard): se i Pending continuano a crescere e non si azzerano mai, il colpevole è il cron. Chiedi al tuo host di confermare che il cron di Magento sia pianificato; una volta in esecuzione, la scheda Cron Monitor mostra ogni job in verde.

2. Il tuo database è al di sotto del minimo. L’estensione richiede MySQL 8.0+ o MariaDB 10.6+ per la sincronizzazione in background. Se il cron è in esecuzione e i Pending non si azzerano lo stesso, controlla la versione del tuo database e aggiornala se è sotto il minimo.

L’installazione o l’aggiornamento fallisce (errori di setup:upgrade o di:compile)

Installando con Composer, i requisiti vengono applicati per te (Magento 2.4.6+, PHP da 8.1 a 8.4, MySQL 8.0+ o MariaDB 10.6+), quindi un rifiuto netto significa che l’ambiente deve raggiungere quella soglia minima. Un’installazione da zip della sola estensione compila e funziona; PulseCore è facoltativo, non incluso. Aggiungi i pacchetti PulseCore e Pulse bridge solo se vuoi i journey di Pulse, ciascuno scompattato sotto app/code, poi riesegui la stessa sequenza di setup. setup:upgrade aggiunge colonne ad alcune tabelle core, quindi i negozi di grandi dimensioni dovrebbero eseguirlo dentro una finestra di manutenzione. Se una compilazione fallisce dopo un aggiornamento, passa all’ultima patch pubblicata e riesegui setup:upgrade, di:compile e cache:flush. Installazione contiene la procedura completa.

Cosa significano le etichette di stato

Ordini e clienti mostrano l’insieme completo degli stati nelle rispettive griglie; la griglia Products mostra solo Synced o Not in Mailchimp, con lo stato completo di un prodotto nella Entity Queue e sulla scheda Mailchimp del prodotto stesso:

Perché “Not in Mailchimp”? Non è un errore: il record era fuori dall’ambito di sincronizzazione. La sua store view non è connessa, è più vecchio della tua finestra di sincronizzazione, oppure è un ordine storico fuori dalla tua selezione di entrate confermate. Per impostazione predefinita, le entrate confermate corrispondono agli stati processing, complete e closed: quella selezione decide quali ordini storici vengono importati e quali ordini contano ai fini delle entrate e del lifetime value. I nuovi ordini si sincronizzano man mano che accadono e restano aggiornati a ogni cambio di stato.

Errori “Invalid email”, ma non trovo quel cliente

Mailchimp rifiuta gli indirizzi che sembrano falsi o malformati. Le email reali degli ospiti si sincronizzano senza problemi; solo quelle non valide vengono escluse, di proposito. Per correggerne una, apri l’ordine e correggi l’email di fatturazione, poi apri la Entity Queue e clicca Retry sulla riga dell’ordine: una riga ancora in Error continua a ritentare da sola e recepisce la correzione, mentre una riga in Action needed aspetta il tuo Retry. Sui negozi di test, i dati di esempio portano spesso email segnaposto che Mailchimp rifiuterà; è previsto, non è un difetto.

Problemi di connessione

• Un banner dice “Mailchimp is disconnected”: la soluzione viaggia insieme al messaggio. Il banner porta con sé il proprio pulsante Reconnect to Mailchimp, e un clic ripristina il collegamento. Se mai ti servisse la via più approfondita, sposta Configuration sulla store view e apri Manage Connection: disconnetti dalla scheda Manage, riconnetti tramite il wizard, poi verifica che la store view punti ancora al pubblico giusto.
• L’intestazione dice ancora “Let’s connect” dopo aver aggiunto un account: l’intestazione della configurazione continua a mostrare il suo pulsante Log in to Mailchimp perché aggiungere un account e connettere una store view sono due passaggi separati. Cambia l’ambito su una store view, poi scegli Connect store.
• “Connect store” non mostra alcun negozio: o non è ancora connesso alcun account, oppure ogni negozio Mailchimp è già collegato a un’altra store view. Aggiungi un account, oppure crea un nuovo negozio in Mailchimp.
• Il popup di login non si completa: consenti i popup per il dominio del tuo admin, e assicurati che il tuo server possa raggiungere Mailchimp via HTTPS.

“Dice che la mia chiave API non è valida, ma la chiave è nuova di zecca”

Prima controlla il formato: una chiave Mailchimp termina con il suffisso del suo data-center (per esempio -us21), quindi genera una chiave nuova e incollala per intero. Se la chiave è sicuramente valida, il log sotto var/log registra ogni chiamata di validazione con la chiave mascherata: una riga con HTTP 401 significa che Mailchimp ha rifiutato la chiave stessa, mentre un errore di trasporto senza stato significa che il tuo server non è riuscito a raggiungere Mailchimp, quindi chiedi al tuo host di consentire l’HTTPS in uscita verso <dc>.api.mailchimp.com. Una chiave che smette di funzionare in un secondo momento si vede sulla pagina Mailchimp accounts: l’indicatore di salute dell’account cambia entro l’ora, e Update key la corregge proprio lì, senza disconnettere il negozio. Collega il tuo account Mailchimp illustra ogni passaggio.

I tag non compaiono sui contatti

I tag di categoria si applicano a ogni ordine che si sincronizza dal momento in cui li abiliti, e una risincronizzazione applica i tag anche allo storico dei tuoi ordini: i tag non vengono mai duplicati, quindi risincronizzare è sempre sicuro. Anche gli acquisti come ospite vengono taggati quando Update Audience Members from Guest Orders è attivo. Tag, campi dati e segmentazione spiega come viene costruito ciascun tag.

Campi dell’acquisto vuoti sui contatti più vecchi

I campi dati dell’acquisto vengono creati automaticamente alla prima sincronizzazione di un contatto. Se risultano vuoti su contatti già presenti nel tuo pubblico, Rebuild merge fields (o una risincronizzazione) li compila. Tag, campi dati e segmentazione spiega cosa traccia ciascun campo.

“Le entrate delle campagne di Mailchimp non coincidono con il mio negozio”

Un calo improvviso a $0 su tutte le campagne significa che gli ordini hanno smesso di raggiungere Mailchimp: controlla prima il Queue Monitor e il Cron Monitor. Quali ordini contano è un’impostazione: Order Statuses to Sync (Configuration → Ecommerce Sync) decide cosa conta ai fini delle entrate, e le cancellazioni vengono inviate con totali azzerati, quindi non le gonfiano mai. L’attribuzione del merito alla campagna sbagliata è esclusa per progettazione: l’estensione non assegna mai una campagna a un ordine; l’attribuzione è il tracciamento dei clic di Mailchimp stesso. Per leggere l’attribuzione registrata dal tuo negozio, campagna per campagna, e per dimostrarla rispetto alla Dashboard, apri Il report Campaign Performance. Quando i numeri continuano a non coincidere, ogni superficie misura una fetta diversa, e Perché i tuoi numeri non coincidono con Mailchimp contiene l’analisi completa.

I prodotti sembrano sbagliati in Mailchimp: immagini mancanti, prezzi strani, dettagli non aggiornati

Correggi prima i dati di catalogo: un prodotto senza immagine nel ruolo Base si sincronizza senza immagine, e il prezzo proviene dall’ambito di store view in cui lo modifichi. Poi rimandalo: Push Now sulla scheda Mailchimp del prodotto lo rimette in coda con priorità in tempo reale, e la mass action Push to Mailchimp invia sempre, anche quando nulla è cambiato in Magento. Da riga di comando, bin/magento mailchimp:resync --force fa lo stesso; senza --force il comando mostra solo un’anteprima di ciò che verrebbe rimandato. Il dettaglio della riga nella Entity Queue mostra l’esatto payload che è stato inviato, quindi controllalo poco dopo l’invio. I prezzi si sincronizzano come prezzo finale di catalogo senza imposte aggiunte, e Mailchimp mostra un unico prezzo di vendita attivo per prodotto, che è previsto. Le gift card di Adobe Commerce portano un prezzo rappresentativo (l’importo configurato più basso, o il minimo dell’importo libero), e un prodotto di tipo custom a prezzo zero ripiega su 0.00. I totali degli ordini e i prezzi di riga provengono sempre dagli importi effettivamente pagati, quindi una gift card a importo libero viene riportata all’esatto importo scelto dall’acquirente. Come funziona la sincronizzazione spiega cosa viene inviato e quando.

I prezzi sono cambiati in Magento ma Mailchimp mostra ancora quelli vecchi

Quando lo storefront applica il prezzo nuovo e Mailchimp continua a mostrare quello vecchio, la causa abituale è il modo in cui il prezzo è stato scritto. L’estensione si accorge che un prodotto è cambiato osservando la sua data di ultima modifica, e non tutti i modi di impostare un prezzo aggiornano quella data. L’import dei prodotti di Magento, la normale API di salvataggio dei prodotti e la mass action Aggiorna gli attributi dell’admin la aggiornano tutti, quindi i prezzi scritti per quelle vie raggiungono Mailchimp entro circa un minuto. L’endpoint bulk di Magento dedicato ai prezzi speciali invece non l’aggiorna, e nemmeno qualunque cosa scriva direttamente nel database, quindi quei cambi di prezzo sono invisibili all’estensione, senza errori e senza avvisi. Per verificarlo, apri il prodotto e confronta la sua data di Ultima modifica con il Last Sync mostrato sulla sua scheda Mailchimp e con il momento in cui il prezzo è cambiato davvero: se il prezzo è nuovo ma l’Ultima modifica è vecchia, hai la conferma. Punta il tuo ERP, PIM o repricer verso una via che aggiorni la data, poi usa Push Now sulla scheda Mailchimp del prodotto, o la mass action Push to Mailchimp, per correggere ciò che è già in Mailchimp. Se hai integrazioni che scrivono i prezzi, vale la pena confermarlo con chi le ha costruite.

I campi dati mappati arrivano vuoti o smettono di aggiornarsi

Le mappature personalizzate risiedono nella griglia Data fields (Configuration → Contact Sync) e si modificano a livello di store view, perché ogni store view si mappa al proprio pubblico. Crea prima il campo del pubblico in Mailchimp: il menu a discesa elenca solo i tag che esistono in quel pubblico, quindi un refuso non può mai essere salvato. Salvare una modifica reale rimette in coda ogni contatto interessato, e Rebuild merge fields forza lo stesso aggiornamento, che compila anche i campi che risultano vuoti sui contatti precedenti alla mappatura. Se un campo smette silenziosamente di aggiornarsi, la causa abituale è che il suo tag è stato eliminato in Mailchimp: ricrealo lì o svuota la riga. Tag, campi dati e segmentazione illustra ogni campo.

Gli ospiti non compaiono dopo aver abbandonato i carrelli

Mailchimp ha bisogno di un indirizzo email per inviare un promemoria, e l’estensione ne cattura uno nel momento in cui un ospite lo digita ovunque: al checkout, in un box newsletter, o arrivando da un link di una campagna. Se i carrelli degli ospiti non compaiono, verifica che la store view sia connessa; un ospite che non ha mai condiviso un’email da nessuna parte non può essere raggiunto da un promemoria, e ogni altro carrello procede da solo. Recupera i carrelli abbandonati mostra l’intero percorso.

“La mia automazione dei carrelli abbandonati non invia mai un’email”

Le email di recupero vengono inviate dalla tua automazione Mailchimp, non dall’estensione, quindi parti dal pannello Abandoned Carts della Dashboard: se i carrelli vengono conteggiati ma non viene inviato nulla, segui il link Set up automation del pannello per completare l’automazione in Mailchimp. Se il conteggio Abandoned del pannello resta a 0, apri il Cron Monitor (i carrelli viaggiano sulla lane Boost) e il Queue Monitor, e verifica che quella store view sia connessa. Un ordine completato rimuove subito il suo carrello da Mailchimp, così gli acquirenti non ricevono mai un promemoria per qualcosa che hanno già comprato, e i link di recupero per i clienti registrati portano alla pagina di login, per progettazione. Recupera i carrelli abbandonati accompagna lungo l’intero percorso.

L’interruttore del Pixel non si attiva

L’interruttore scatta solo dopo che Mailchimp conferma l’attivazione, quindi quando resta spento, il popup dell’estensione ti dice perché e indica la store view coinvolta. Il caso comune è due store view che condividono uno stesso indirizzo web: ogni Pixel risiede sul proprio dominio, quindi una delle store view lo porta. Gli eventi comportamentali continuano comunque a fluire lato server per ogni store view, così i segmenti e i Customer Journey continuano a funzionare. Il Pixel di Mailchimp e gli eventi comportamentali ha i dettagli.

Il Pixel è attivo ma non si attiva nulla sullo storefront

Apri lo storefront con gli strumenti di sviluppo del tuo browser e la pagina ti dice quale dei tre comportamenti noti stai vedendo. Se il tuo banner di cookie-consent non è ancora stato accettato, il Pixel viene trattenuto di proposito: accettalo e lo script si inietta entro circa un secondo. Se la console mostra una violazione Content-Security-Policy che nomina chimpstatic.com o mcjs.prd.a.intuit.com, il blocco proviene da una CSP impostata fuori da Magento: aggiungi entrambi gli host a script-src e connect-src lì. Se si tratta di un mismatch di hash di uno script inline al checkout, aggiorna l’estensione: ogni release include l’hash approvato corrente. Gli eventi lato server continuano comunque a fluire, sulla scheda Events Tracking. Il Pixel di Mailchimp e gli eventi comportamentali spiega entrambe le metà.

La checkbox di iscrizione non compare

Tre verifiche veloci: svuota la cache di Magento; controlla se il Pixel è attivo su quella store view (la checkbox del checkout si fa da parte di proposito, così la pagina di conferma non porta prompt sovrapposti); e verifica che Sync Newsletter Subscribers sia attivo nelle impostazioni Contact Sync, che è ciò che rende disponibili le superfici di opt-in. Fai crescere il tuo pubblico illustra entrambe le checkbox.

Le disiscrizioni fatte in Mailchimp non arrivano a Magento

I webhook si registrano da soli durante il Go Live, quindi parti dalla superficie di audit: apri Webhooks dal menu ops, clicca Check Webhooks e scegli la store view. Un negozio sano mostra “Webhooks are active”; se invece propone Register, cliccalo (o Re-register se l’URL del tuo negozio è cambiato). Quando la registrazione fallisce, la finestra spiega perché, e il caso comune è Mailchimp che non riesce a raggiungere l’URL del tuo negozio (firewall, modalità di manutenzione, o un sito di staging protetto da password): rendilo raggiungibile pubblicamente e registra di nuovo. Le disiscrizioni si applicano nel momento in cui arrivano; le modifiche al profilo richiedono inoltre Sync Newsletter Subscribers attivo. Disiscrizioni e consenso illustra il flusso bidirezionale.

Le email di conferma arrivano due volte, o gli iscritti restano in “pending”

Il Double Opt-In si imposta in Mailchimp: la riga Double Opt-In in Configuration → Contact Sync è di sola lettura e rispecchia l’impostazione del tuo pubblico, che risiede in Mailchimp sotto Audience → Settings → Audience name and defaults. Con esso attivo, Mailchimp invia l’unica email di conferma e gestisce il passaggio di conferma. Lascia disattivata l’impostazione Newsletter “Need to Confirm” di Magento a meno che tu non voglia deliberatamente una seconda email di conferma: con entrambe attive, gli iscritti ricevono due email e restano in pending finché non cliccano il link di Mailchimp. Se un cliente si iscrive di nuovo ma non ricompare mai, l’API Log mostra la voce bloccata per conformità: Mailchimp protegge i contatti che hanno annullato l’iscrizione tramite un link di una campagna, e questi rientrano tramite un modulo di iscrizione ospitato da Mailchimp. Disiscrizioni e consenso spiega il consenso in entrambe le direzioni.

Abbiamo cambiato dominio e la sincronizzazione si è messa in pausa

Si è messa in pausa di proposito: è la protezione che impedisce a un negozio spostato o clonato di scrivere nel posto sbagliato. Quando l’indirizzo del tuo negozio cambia, dopo un cambio di dominio, uno spostamento di server o un ambiente copiato, l’estensione mette in pausa quella store view e un banner nell’admin spiega cosa è successo. Disconnetti e riconnetti la store view e la sincronizzazione riprende; Collega il tuo account Mailchimp accompagna nei passaggi di connessione. Prima di farlo, cosa succede se disconnetti o disinstalli spiega cosa viene rimosso e cosa torna.

Un banner dice che il nostro negozio Mailchimp collegato è stato eliminato in Mailchimp

Nulla è perso: la sincronizzazione non scrive mai contro un negozio mancante, e le modifiche in coda attendono al sicuro in Pending. Ripristina il negozio dal lato Mailchimp (un controllo di salute orario toglie la pausa da solo), oppure sposta Configuration sulla store view interessata, disconnetti dal popup di connessione e riconnetti tramite il Setup Wizard; i dati si risincronizzano automaticamente. Se un negozio Mailchimp esiste già sullo stesso dominio quando riconnetti, il wizard propone di archiviarlo e crearne uno nuovo, lasciando intatto il tuo pubblico. È connesso e sincronizza bene? mostra ogni segnale di connessione in un unico posto. Prima di farlo, cosa succede se disconnetti o disinstalli spiega cosa viene rimosso e cosa torna.

La nuova attività si sincronizza ma lo storico si blocca (o viceversa)

Boost gira nel proprio gruppo cron (ebizmarts_mailchimp_boost) e Backfill nel gruppo principale dell’estensione (ebizmarts_mailchimp), e nessuno dei due è il gruppo predefinito di Magento. Un host che vincola il cron a gruppi specifici può avviare una lane e non l’altra, quindi chiedi al tuo host di confermare che il cron di Magento esegua tutti i gruppi; il Cron Monitor mostra lo stato di ciascun gruppo, così puoi vedere esattamente quale è in attesa. Come lavora il motore di sincronizzazione spiega le due lane.

“Il mio pubblico è molto più grande della mia lista di iscritti” (conteggio contatti e fatturazione)

Il volume dei contatti è mostrato in anteprima prima che qualcosa si sincronizzi: il Setup Wizard mostra una stima per le scelte che fai, ed è quella stima il numero di cui fidarsi, perché conta tutti i contatti che verranno creati, iscritti compresi. La finestra storica che scegli (3, 12, 24, 36 o 48 mesi, oppure tutto) limita lo storico di ordini e carrelli e i clienti importati con esso; non limita gli iscritti alla newsletter, che si sincronizzano per intero qualunque finestra tu scelga. Sync Customers sincronizza solo i clienti che hanno effettuato un ordine, mai l’intero database dei tuoi clienti, e Default Subscription Status for Synced Customers decide se arrivano come iscritti o non iscritti. Se il pubblico è già più grande di quanto vuoi, archivia i contatti in Mailchimp: i contatti archiviati non vengono fatturati e rientrano da soli se l’acquirente compra di nuovo. Come funziona la sincronizzazione spiega esattamente chi si sincronizza e quando.

Una regola promo è bloccata su “Action needed”

Prima verifica che Sync Promo Rules & Codes ed Enable Ecommerce Sync siano entrambi su Yes (Configuration → Ecommerce Sync). Quando Mailchimp rifiuta una regola (uno sconto pari a zero, date mancanti, un nome mancante), solo quella regola resta in attesa: apri la scheda Entity Queue, filtra lo Status su “Action needed” e leggi lo Status Message per il motivo esatto. Correggi la Cart Price Rule in Magento, poi clicca il link Retry della riga: risalvare la regola da sola non riattiva la riga. Tutto il resto continua a sincronizzarsi mentre attende. Tieni d’occhio la sincronizzazione mostra come leggere la coda.

Un prodotto mostra “Not supported” nella Entity Queue

Questo stato ambra compare solo per un prodotto di tipo custom (una gift card di Adobe Commerce o un tipo di un’estensione di terze parti) a cui manca lo SKU o il nome: non è stato inviato nulla, e lo Status Message indica il tipo di prodotto. I prodotti di tipo custom con uno SKU e un nome si sincronizzano automaticamente con un payload best-effort, registrato nell’API Log come generic_type_fallback. Aggiungi lo SKU o il nome mancante, poi usa il Retry della riga nella Entity Queue (oppure esegui Resync All Data da Manage Connection, sulla scheda Manage); risalvare da solo non sblocca la riga. Un ordine che contiene il prodotto si ferma su “Action needed” indicando i suoi SKU; una volta che il prodotto riparato si è sincronizzato, usa Retry sulla riga dell’ordine. Risincronizzazione e strumenti da riga di comando ha i dettagli.

Ancora bloccato?

Apri il Queue Monitor, trova il record che non si sincronizza e leggi l’errore Mailchimp completo; di solito indica la soluzione. Se sei ancora bloccato, il supporto ebizmarts è a portata di una sola email: includi la tua versione di Magento, la versione del database, la versione dell’estensione e uno screenshot dell’errore.