Integrazione Google Merchant XML & API: configurazione e aiuto

Carica e installa mprgooglemerchant dalla schermata di caricamento dei moduli del Back Office. Fai clic su "Configure" per aprire Google Merchant > Feed. Usa un sottoinsieme del catalogo per il primo feed.

Scegli XML se vuoi l'URL di un file generato. Scegli Products API se vuoi che il modulo invii gli input dei prodotti. Entrambi i metodi usano lingua, valuta, selezione prodotti e impostazioni delle varianti del feed. Un feed API richiede un account Merchant e un'attivazione LIVE separata.

Apri Google Merchant > Impostazioni > Configurazione.

Generale

• TTL cache predefinito. TTL cache iniziale dei nuovi feed, inizialmente 3600 secondi. I nuovi feed usano la preferenza salvata; quelli esistenti mantengono il proprio TTL cache.
• Directory dei feed. Mostra il percorso del filesystem in cui vengono scritti i file XML generati e indica se la directory è scrivibile; valore predefinito: _PS_MODULE_DIR_ . 'mprgooglemerchant/feeds/'.

Concedi al processo PHP l'accesso in scrittura alla directory dei feed. Proteggi XML generati, ricevute e file temporanei. Il file Apache .htaccess fornito nega l'accesso diretto a questa directory. Se il server non elabora .htaccess, configura una regola equivalente. Usa l'URL del controller del feed autenticato per recuperare l'XML.

"Access & Feed URLs"

• Token di accesso. Autorizza i front controller dei feed e del cron; valore predefinito: generated 32-character token.

• Rigenera token. Crea un nuovo token di accesso e invalida gli URL esistenti dei feed e del cron; valore predefinito: manual action.

• URL cron. Mostra l'endpoint cron protetto da token da richiamare tramite il tuo pianificatore; valore predefinito: https://your-shop.example/module/mprgooglemerchant/cron?token=TOKEN.

• Pattern URL del feed. Mostra il pattern dell'endpoint del feed protetto da token da inviare a Merchant Center; valore predefinito: https://your-shop.example/module/mprgooglemerchant/feed?id={ID}&token=TOKEN.

• "Canonical Merchant Base URL". Valore predefinito: vuoto. Inserisci l'URL di base del negozio in produzione, includendo eventuali sottodirectory. Gli URL dei prodotti e delle immagini usano questa base.

• Modalità API Merchant. Valore predefinito: test. TEST esegue anteprime locali e mantiene disponibili le esportazioni XML. LIVE consente scritture su Google solo se gli altri controlli di identità hanno esito positivo.

• Attivazione LIVE. Salva prima l'URL canonico. Un super amministratore deve fare clic su Attiva LIVE per questo negozio nel contesto del negozio previsto. L'attivazione associa quel negozio e quell'installazione all'identità salvata. Un'associazione esistente non corrispondente non viene sostituita.

• Stato effettivo delle scritture Google. Leggi questo stato prima di un'esecuzione API reale. Dopo l'attivazione, il selettore della modalità consente di sospendere e riprendere le scritture sulla stessa installazione.

La preferenza interna sync_lock_ttl_seconds ha valore predefinito 600. Non è un normale campo di questa schermata. Una seconda esecuzione per un feed già bloccato restituisce uno stato di blocco invece di avviare un lavoro duplicato.

Apri Google Merchant > Account commercianti e aggiungi un account.

• Nome account. Etichetta interna per un account Merchant Center; valore predefinito: "".
• ID Merchant Center. ID del tuo account Google Merchant Center; valore predefinito: "".
• Percorso JSON account di servizio. Inserisci il percorso del file JSON dell'account di servizio. Valore predefinito: vuoto. Conserva il file fuori dalla radice web pubblica e consenti al processo PHP di leggerlo.
• Attivo. Abilita l'account Merchant per l'uso nei feed API; valore predefinito: 1.

Le richieste API richiedono PHP cURL e OpenSSL, un file JSON dell'account di servizio leggibile e l'accesso all'account Merchant Center. Il client legge i campi dell'account di servizio, tra cui client_email, private_key e token_uri. Usa il tuo file di credenziali effettivo. Non incollare una chiave privata nei modelli o in una cartella pubblica.

Apri Google Merchant > Feed e aggiungi o modifica un feed.

• Nome del feed. Nome interno mostrato nell'elenco dei feed; valore predefinito: "".
• Account commerciante. Assegna il feed a un account Merchant per la sincronizzazione API, i controlli di sovrapposizione e la deduplicazione; valore predefinito: 0.
• Modalità sincronizzazione. Sceglie l'output come file XML o la sincronizzazione Merchant Products API; valore predefinito: file_only.
• Paesi target. Imposta uno o più codici paese di destinazione Merchant a due lettere, come FR o AE,AU,GB,US; valore predefinito: FR.
• Etichetta feed. Imposta l'etichetta del feed Merchant usando lettere maiuscole, numeri o trattini; valore predefinito: FR.
• Lingua contenuto. Imposta la lingua dei contenuti Merchant con un codice a due lettere; valore predefinito: fr.
• Nome origine dati Merchant API. Memorizza il nome della risorsa dell'origine dati Merchant API dopo la configurazione API; valore predefinito: "".
• Priorità. Imposta la priorità del feed per la deduplicazione; i numeri maggiori riservano per primi i prodotti; valore predefinito: 0.
• Lingua. Sceglie la lingua PrestaShop usata per nomi dei prodotti, descrizioni, caratteristiche e attributi; valore predefinito: current Back Office language.
• Valuta. Sceglie la valuta del feed o usa quella predefinita del negozio; valore predefinito: 0.
• Nome del file. Imposta il nome del file XML generato senza .xml; valore predefinito: "".
• Attivo. Abilita il feed per la generazione e l'elaborazione cron/API; valore predefinito: 1.
• Includi varianti. Esporta le combinazioni dei prodotti come articoli separati; valore predefinito: 0.
• Deduplica automaticamente. Esclude i prodotti già presenti in feed attivi con priorità maggiore nello stesso account Merchant; valore predefinito: 0.
• TTL cache. Imposta per quanto tempo rimane valido il file XML generato di questo feed; i nuovi feed partono dal TTL cache predefinito salvato (inizialmente 3600 secondi).
• Selezione prodotto. Definisce quali prodotti sono inclusi nel feed; valore predefinito: all active products with visibility both or catalog.
• Filtri attributi. Esclude i gruppi di attributi non selezionati dalla risoluzione dei tag {attribute:...}; valore predefinito: all attribute groups included.
• Intestazione XML. Controlla il contenuto XML scritto prima degli articoli prodotto; valore predefinito: standard RSS header.
• Modello elemento XML. Controlla l'XML generato per ogni prodotto o combinazione; valore predefinito: standard Google Merchant item template.
• Piè di pagina XML. Controlla il contenuto XML scritto dopo gli articoli prodotto; valore predefinito: standard RSS footer.

Modifica i valori iniziali FR per paese/etichetta e fr per la lingua in base alla destinazione effettiva. Lingua è la lingua PrestaShop usata per i testi del catalogo; Lingua contenuto è il codice della lingua dei contenuti Merchant. Valuta = 0 usa il valore predefinito del negozio.

Usa un Nome del file univoco senza .xml. Una Selezione prodotto vuota ripiega sui prodotti attivi con visibilità both o catalog. Usa le condizioni di inclusione/esclusione del selettore per restringere il feed. I Filtri attributi influiscono sulla risoluzione dei tag degli attributi; da soli non determinano quali combinazioni sono incluse.

I valori numerici più alti di Priorità riservano per primi i prodotti quando Deduplica automaticamente è attivo per i feed dello stesso account Merchant. Esamina le sovrapposizioni prima di abilitare più feed per un account.

Il formulario contiene anche "Acknowledge XML removals". Leggi il messaggio di generazione ed esamina i prodotti rimossi prima di confermare una modifica di pubblicazione protetta. Non cambiare le selezioni solo per eliminare un avviso.

• Dimensione batch API. Limita le operazioni di inserimento/eliminazione di Product API per batch; valore predefinito: 25. Un’esecuzione cron o una sincronizzazione manuale può elaborare più batch entro i limiti di tempo e numero di batch.
• Elimina prodotti API mancanti. Elimina gli input dei prodotti Merchant quando i prodotti escono da questo feed; valore predefinito: 1.
• "Delete guard threshold (%)". Blocca le eliminazioni API quando un'esecuzione eliminerebbe più di questa percentuale di articoli noti e più di 10 articoli; valore predefinito: 20.
• Escludi prodotti senza immagini. Salta i prodotti il cui {image_link} risolto è vuoto; valore predefinito: 1.
• "Export loyalty member prices". Aggiunge voci loyaltyPrograms di Merchant API quando i prezzi dei gruppi clienti mappati sono inferiori al prezzo normale; valore predefinito: 0.
• "Loyalty program label". Etichetta del programma fedeltà Merchant Center usata per i prezzi riservati ai membri tramite API; valore predefinito: "".
• "Loyalty group tier map". Oggetto JSON che associa gli ID dei gruppi clienti PrestaShop alle etichette dei livelli Merchant Center; valore predefinito: "".
• Template titolo Merchant. Modello di titolo solo per API; valore predefinito: "".
• Template descrizione Merchant. Modello di descrizione solo per API; valore predefinito: "".
• Template tipo prodotto Merchant. Modello di tipo di prodotto solo per API; valore predefinito: "".
• Categoria prodotto Google. Valore API predefinito per googleProductCategory, sostituito da google_product_category a livello di prodotto; valore predefinito: "".
• Custom label 0. Valore API predefinito per customLabel0, sostituito da custom_label_0 a livello di prodotto; valore predefinito: "".
• Custom label 1. Valore API predefinito per customLabel1, sostituito da custom_label_1 a livello di prodotto; valore predefinito: "".
• Custom label 2. Valore API predefinito per customLabel2, sostituito da custom_label_2 a livello di prodotto; valore predefinito: "".
• Custom label 3. Valore API predefinito per customLabel3, sostituito da custom_label_3 a livello di prodotto; valore predefinito: "".
• Custom label 4. Valore API predefinito per customLabel4, sostituito da custom_label_4 a livello di prodotto; valore predefinito: "".

Nome origine dati Merchant API memorizza l'associazione alla risorsa. Usa "Rebind data source" solo se intendi modificare quell'associazione e hai valutato l'effetto sugli articoli già inviati. Per impostazione predefinita è disattivato.

"Delete guard threshold (%)" blocca un batch di eliminazioni quando verrebbero eliminati più di 10 articoli noti e la percentuale di eliminazione supera la soglia. Il valore predefinito è 20; 0 disattiva questa protezione percentuale. Inserimenti e aggiornamenti possono continuare mentre le eliminazioni rimangono bloccate. Esamina le modifiche alla selezione e il messaggio di stato prima di autorizzare le eliminazioni in attesa.

Per i prezzi dei membri, abilita "Export loyalty member prices", inserisci "Loyalty program label", poi associa gli ID dei gruppi clienti alle etichette dei livelli Merchant in "Loyalty group tier map", ad esempio {"4":"trade","5":"vip"}. L'indicazione "Customer groups" accanto al campo elenca i gruppi del negozio. Solo i prezzi di gruppo inferiori che soddisfano i requisiti producono voci fedeltà.

Spedizione

Seleziona "Shipping carriers" solo se vuoi voci per la spedizione fisica. Per impostazione predefinita la selezione è vuota e queste voci vengono omesse. Il modulo sceglie il vettore selezionato disponibile più economico per un articolo fisico in ogni paese di destinazione. Seleziona vettori attivi con intervalli di prezzo o peso nativi.

"Minimum handling days", "Maximum handling days", "Minimum transit days" e "Maximum transit days" accettano numeri interi di giorni facoltativi. Vuoto significa non inviato; zero significa lo stesso giorno. Gli hook di prezzo e imposte vengono usati solo quando il negozio del feed è quello della richiesta corrente. Gli altri contesti di negozio usano le tabelle native di prezzi, riduzioni e imposte.

Opzioni memorizzate di compatibilità ed esecuzione

fetch_hour = 2 e fetch_timezone = Europe/Paris sono vecchi campi memorizzati, non controlli di pianificazione del formulario attuale. Richiama invece l'endpoint cron dal tuo pianificatore.

Il modulo ha anche preferenze interne per la disponibilità dei prodotti esauriti ordinabili (in_stock per impostazione predefinita, oppure backorder), il tempo di riapprovvigionamento (21 giorni), l'etichettatura del testo generato (disattivata), la marca predefinita (vuota), il rinnovo API (7 giorni), il tempo disponibile per cron (105 secondi) e il tipo di immagine (vuoto per l'originale). Non sono campi aggiuntivi della schermata di configurazione. I requisiti del negozio sulla provenienza delle immagini possono trattenere i prodotti la cui immagine originale non ha i metadati di origine richiesti. Controlla la diagnostica se un prodotto con immagine continua a essere trattenuto.

Apri Google Merchant > Campi personalizzati > Gruppi per definire i tag. Crea un campo prima di usare il suo tag in un modello di testo XML o API.

• Nome tag. Crea il nome del tag usato nei modelli, ripulito per contenere solo lettere minuscole, numeri e trattini bassi; valore predefinito: "".
• Etichetta di visualizzazione. Imposta l'etichetta del campo personalizzato nel Back Office; valore predefinito: "".
• Tipo di campo. Sceglie text, textarea, select o number; valore predefinito: text.
• Valore predefinito. Fornisce un valore quando non esiste un valore specifico del prodotto; valore predefinito: "".
• Opzioni. Memorizza un'opzione per riga per i campi di selezione; valore predefinito: "".
• Attivo. Rende disponibile il tag personalizzato nei modelli e nell'assegnazione dei valori; valore predefinito: 1.

I nomi dei tag vengono ripuliti per contenere solo lettere minuscole, numeri e trattini bassi. La posizione è gestita tramite l'ordinamento memorizzato anziché un campo Posizione separato in questo formulario.

Apri Campi personalizzati > Valori per assegnare un valore ai prodotti selezionati:

• Nome del gruppo. Etichetta facoltativa del Back Office per un'operazione di assegnazione di massa; valore predefinito: "".
• Campo personalizzato. Seleziona il tag personalizzato che riceve un valore; valore predefinito: "".
• Valore. Imposta il valore assegnato ai prodotti selezionati; valore predefinito: "".
• Prodotti obiettivo. Seleziona i prodotti che ricevono il valore personalizzato; valore predefinito: empty selection.

Ad esempio, definisci merchant_title, merchant_description, merchant_product_type, google_product_category o custom_label_0, poi assegna i valori prima di fare riferimento ai tag. I valori predefiniti dei campi compensano i valori specifici del prodotto mancanti.

Mantieni intestazione e piè di pagina iniziali per il primo test XML. Modifica Modello elemento XML usando i tag disponibili, poi rigenera e controlla l'XML. Il modello iniziale dell'articolo include:

<item>
  <g:id>{id}</g:id>
  <g:title>{title}</g:title>
  <g:description>{description_short}</g:description>
  <g:link>{link}</g:link>
  <g:image_link>{image_link}</g:image_link>
  <g:additional_image_link>{additional_image_links}</g:additional_image_link>
  <g:price>{price} {currency}</g:price>
  <g:sale_price>{sale_price} {currency}</g:sale_price>
  <g:availability>{availability}</g:availability>
  <g:brand>{brand}</g:brand>
  <g:gtin>{ean13}</g:gtin>
  <g:mpn>{mpn}</g:mpn>
  <g:condition>{condition}</g:condition>
  <g:product_type>{categories}</g:product_type>
  <g:item_group_id>{item_group_id}</g:item_group_id>
</item>

Puoi usare campi personalizzati e caratteristiche o attributi con nome, ad esempio {merchant_title}, {attribute:size}, {attribute:color}, {feature:material}, {gtin} e {custom_label_0}. I nomi di attributi e caratteristiche devono corrispondere al tuo catalogo. Lunghezze o cifre di controllo GTIN EAN/UPC non valide producono un identificatore vuoto.

I modelli di testo API usano gli stessi tag del catalogo, ad esempio:

Merchant title template: {name} {attribute:size} {feature:style_de_grille}
Merchant description template: {merchant_description}
Merchant product type template: Sanitaire > Receveurs de douche > {feature:serie}

Con Includi varianti abilitato, gli articoli delle combinazioni usano ID come 125-842 e condividono {item_group_id}. Controlla prezzo, identificatori, immagine e link di ogni variante.

Copia gli effettivi URL cron e Pattern URL del feed dalla configurazione. Sostituisci {ID} con l'ID del feed. Esempi:

wget -q -O - "https://your-shop.example/module/mprgooglemerchant/cron?token=YOUR_ACCESS_TOKEN"
wget -q -O - "https://your-shop.example/module/mprgooglemerchant/cron?token=YOUR_ACCESS_TOKEN&id=3&force=1"
wget -q -O - "https://your-shop.example/module/mprgooglemerchant/cron?token=YOUR_ACCESS_TOKEN&api_limit=25&api_max_batches=3&api_max_seconds=90"

https://your-shop.example/module/mprgooglemerchant/feed?id=3&token=YOUR_ACCESS_TOKEN
https://your-shop.example/module/mprgooglemerchant/feed?file=google-fr&token=YOUR_ACCESS_TOKEN
https://your-shop.example/module/mprgooglemerchant/feed?id=3&token=YOUR_ACCESS_TOKEN&generate=1

Esegui prima l'azione del feed manualmente. Per l'XML, apri l'URL autenticato e controlla numero di prodotti, lingua, valuta, immagini e identificatori. Il controller invia XML e X-Robots-Tag: noindex, nofollow, noarchive. Invia l'URL verificato al tuo account Merchant. Gli hook di aggiornamento/eliminazione dei prodotti invalidano la cache; non rigenerano immediatamente l'XML da soli.

Per l'API, controlla il risultato TEST locale, poi completa l'attivazione LIVE ed esegui una piccola sincronizzazione reale. Controlla Stato API, il messaggio dell'ultima sincronizzazione e la diagnostica dell'account Merchant. L'accettazione da parte di Google è separata dal buon esito dell'invio. Il formulario offre le modalità file XML e API; i vecchi valori api_fetch e both vengono normalizzati ad API nel formulario.

Apri Google Merchant > Impostazioni > Integrità per controllare tabelle, hook, directory di output, token, feed, sovrapposizioni e account. Per una risposta 403, controlla il token e sostituisci gli URL copiati dopo Rigenera token. Per un articolo mancante, controlla stato attivo, visibilità, selezione, determinazione dell'URL dell'immagine, provenienza dell'immagine e deduplicazione. Per le esecuzioni bloccate, controlla il lavoro attivo prima di avviarne un altro. Per le scritture API bloccate, leggi Stato effettivo delle scritture Google e il messaggio del feed.

Esegui il backup delle definizioni dei feed, dei campi personalizzati, dei record degli account e dei file generati prima di disinstallare. Rimuovi le voci del pianificatore e smetti di usare gli URL dei feed inviati. La disinstallazione rimuove attività, menu, schema e configurazione del modulo. Non esegue un'eliminazione generale dei prodotti Google. Rimuovi o sostituisci separatamente l'origine dati Google se questa è la tua intenzione. Mantieni il controllo sulla pulizia del file dell'account di servizio.

Richiede PrestaShop 1.6.1 o successivo e PHP 7.1 o successivo.