Come aggiungere un assistente AI a Shopify o WooCommerce

Puoi aggiungere un assistente AI per lo shopping a un negozio Shopify o WooCommerce in un pomeriggio. Gran parte del lavoro è copia e incolla. L’unico passaggio che richiede un po’ di codice, cioè collegare il pulsante “Aggiungi al carrello” della chat al tuo vero carrello, si risolve con poche righe che puoi copiare da questa guida. La procedura segue la documentazione di AskMerra e vale anche per Magento 2 e per i negozi sviluppati su misura.

Prima di iniziare

Ti servono quattro cose:

• Un account AskMerra e un negozio. Quando crei il negozio inserisci il dominio del tuo sito, perché il widget funziona solo lì.
• I dati dei tuoi prodotti, come file di export o URL di un feed.
• L’accesso ai file del tema, a un plugin per header e footer o a Google Tag Manager.
• La tua chiave del sito pubblica (inizia con pk_live_), che trovi in Dashboard → Installazione.

Passo 1: importa il catalogo

AskMerra consiglia solo prodotti presenti nel tuo catalogo, quindi un catalogo completo e aggiornato è l’elemento più importante. Oggi ci sono tre modi per importare i prodotti:

• Caricamento di un file (CSV, JSON o XML): il modo più rapido per iniziare. I file possono arrivare a 25 MB, e separatori e codifiche dei CSV vengono riconosciuti automaticamente.
• URL del feed: se pubblichi già un feed prodotti, per esempio per Google Shopping, AskMerra lo risincronizza automaticamente ogni 1-6 ore, a seconda del piano. Un feed XML di Google Merchant Center funziona così com’è.
• Push API: per piattaforme personalizzate ed ERP che hanno bisogno di disponibilità e prezzi in tempo reale.

Da dove arrivano i dati su ogni piattaforma

Su Shopify, installa un’app per il feed Google Shopping e aggiungi l’URL del suo feed, oppure carica un export CSV. Su WooCommerce, usa un plugin per i feed prodotti o un export CSV. Su Magento 2, usa un’estensione per i feed o la Push API. Le app native per Shopify e Magento con sincronizzazione automatica sono in roadmap. Finché non arrivano, il feed e le API coprono le stesse esigenze.

Mappatura e arricchimento

Dopo il caricamento, AskMerra suggerisce come abbinare le tue colonne ai suoi campi (id, nome, prezzo, prezzo scontato, disponibilità, categorie, marchio e così via). Controlla la mappatura prima di importare. Le colonne che mappi su attribute:<name>, come attribute:skin_type, diventano attributi di prodotto ricercabili.

Ogni prodotto viene poi arricchito: l’AI estrae utilizzi, tipi di pelle o capelli, problematiche, ingredienti chiave o specifiche e passaggi della routine, e indicizza il risultato per la ricerca semantica. Le successive variazioni di prezzo e disponibilità si applicano subito e non avviano di nuovo l’arricchimento. I prodotti assenti da una nuova sincronizzazione completa vengono disattivati, mai eliminati.

Inviare i prodotti dal tuo backend

Se sincronizzi dal tuo sistema, invia lotti fino a 500 prodotti, autenticati con la tua chiave segreta:

curl -X POST "https://api.askmerra.com/v1/catalog/products:batchUpsert" \
  -H "Authorization: Bearer $ASKMERRA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"products":[{"external_id":"LUM-SE-01","name":"Hydra Glow Serum 30 ml","price":39,"in_stock":true}]}'

Invia sempre il prodotto completo: un upsert sostituisce ciò che è memorizzato, quindi i campi che ometti vengono svuotati.

Passo 2: aggiungi un tag script

Copia il tuo snippet da Dashboard → Installazione e incollalo subito prima del tag di chiusura </body> in ogni pagina in cui deve comparire l’assistente:

<script src="https://cdn.askmerra.com/v1/widget.js" data-site-key="pk_live_…" async></script>

Lo script pesa circa 27 KB compresso con gzip. Aspetta che la pagina sia caricata e che il browser sia inattivo, poi mostra solo il pulsante di apertura. La chat viene renderizzata dentro uno Shadow DOM, quindi il CSS del tuo tema non può romperla e il suo CSS non può riversarsi sul tuo tema.

Shopify

Vai su Negozio online → Temi → Modifica codice, apri layout/theme.liquid e incolla lo snippet prima di </body>.

WooCommerce e WordPress

Aggiungi lo snippet con un plugin per header e footer come WPCode, nella sezione del footer. Se preferisci il codice, inseriscilo nel footer.php del tuo tema child prima di wp_footer().

Google Tag Manager

Crea un tag HTML personalizzato che si attivi su Tutte le pagine. Alcune configurazioni di GTM eliminano gli attributi data-*, quindi usa invece l’oggetto delle impostazioni:

<script>
  window.AskMerraSettings = { siteKey: 'pk_live_…' };
</script>
<script src="https://cdn.askmerra.com/v1/widget.js" async></script>

Su Magento 2, aggiungi lo snippet in Content → Design → Configuration → HTML Head → Scripts and Style Sheets. Le single-page app (React, Vue, Next.js) lo caricano una sola volta nel layout principale, e la conversazione resta aperta durante la navigazione lato client.

Passo 3: imposta i domini autorizzati

La tua chiave del sito funziona solo sui domini elencati in Impostazioni → Domini autorizzati. shop.com include anche www.shop.com, e *.shop.com include tutti i sottodomini. Aggiungi anche il dominio di staging, altrimenti lì il widget si rifiuterà di funzionare.

Un avvertimento: lo snippet deve contenere la tua chiave del sito pk_live_. Non incollare mai una chiave segreta sk_live_ in una pagina web. In ogni caso, gli endpoint del widget la rifiutano.

Passo 4: dai all’assistente il contesto della pagina prodotto

In una pagina prodotto, AskMerra può sapere quale prodotto sta guardando il cliente, così “Va bene per la pelle grassa?” funziona e basta. Legge il prodotto dal JSON-LD schema.org della pagina (Product.sku, poi productID, poi mpn). Su WooCommerce viene usato il JSON-LD del tuo plugin SEO. Se il tuo tema non ne genera, imposta tu il prodotto:

<script>
  window.AskMerraSettings = { productId: 'LUM-SE-01' };
</script>

Il valore deve corrispondere all’external_id o allo sku del prodotto nel tuo catalogo AskMerra.

Passo 5: collega “Aggiungi al carrello”

Le schede prodotto nella chat possono mostrare un pulsante “Aggiungi al carrello”. Attivalo nelle impostazioni di comportamento del widget, poi gestisci l’evento add_to_cart con l’API del carrello della tua piattaforma. Senza un gestore, il pulsante apre semplicemente la pagina prodotto.

Su Shopify, externalId è l’id della variante quando il catalogo arriva da Shopify:

AskMerra.on('add_to_cart', async ({ externalId }) => {
  await fetch('/cart/add.js', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ items: [{ id: Number(externalId), quantity: 1 }] }),
  });
});

Su WooCommerce, externalId è l’id del prodotto WooCommerce:

AskMerra.on('add_to_cart', async ({ externalId }) => {
  const body = new URLSearchParams({ product_id: externalId, quantity: '1' });
  await fetch('/?wc-ajax=add_to_cart', { method: 'POST', body });
  document.body.dispatchEvent(new Event('wc_fragment_refresh'));
});

Lo script del widget si carica in modo asincrono, quindi il posto più sicuro per registrare i gestori è la callback onReady in window.AskMerraSettings. La stessa API JavaScript ti permette di aprire la chat dal tuo pulsante “Chiedi a un esperto” con AskMerra.sendMessage(), di seguire il selettore di lingua del sito con AskMerra.setLocale() e di inoltrare gli eventi open, product_click e add_to_cart ai tuoi strumenti di analisi.

Passo 6: verifica l’installazione

Apri il tuo negozio in un browser, poi vai su Dashboard → Installazione. Lì vedi quando e dove il widget è stato rilevato l’ultima volta, anche per le installazioni tramite tag manager. Il pulsante Verifica ora carica i tuoi domini e ti dice se lo snippet è stato trovato, se è installata una chiave del sito diversa o se il sito non era raggiungibile.

Se il pulsante di apertura non compare, apri la console del browser. Il widget registra un avviso chiaro: chiave del sito sconosciuta, dominio non autorizzato o negozio in pausa. Se il tuo sito invia un’intestazione Content Security Policy, consenti https://cdn.askmerra.com in script-src e https://api.askmerra.com in connect-src.

Qualche ritocco finale:

• Nascondi il pulsante nel checkout con una regola di percorso come /checkout*, così il percorso d’acquisto resta libero da distrazioni.
• Prima di andare online, fai nel Playground le domande reali dei clienti. Il suo pannello di debug mostra quali prodotti sono stati recuperati e quale percorso ha risposto.
• Le modifiche al design che pubblichi dalla dashboard arrivano sul tuo sito in circa un minuto, senza toccare lo snippet.

Inizia ora

Per seguire tutti i passaggi descritti sopra, crea il tuo account; se preferisci una presentazione guidata, prenota una demo. Il riferimento completo si trova nella documentazione sull’installazione e nella documentazione dell’API JavaScript. Se stai ancora valutando l’idea, parti da cos’è un assistente AI per lo shopping e scopri in cosa si differenzia da una classica barra di ricerca in ricerca prodotti conversazionale vs parole chiave.