Google Indexing API per Magento 2 - installazione e configurazione

1. Informazioni importanti prima dell implementazione

Il modulo integra Magento 2 con Google Indexing API e consente di aggiungere URL alla coda centrale delle segnalazioni. La coda viene elaborata dal cron di Magento e ogni segnalazione viene validata, deduplicata, soggetta a limiti e registrata nei log.

Secondo la documentazione di Google, Indexing API è ufficialmente destinata principalmente alle pagine con dati strutturati:

• JobPosting,
• BroadcastEvent incorporato in VideoObject.

L utilizzo dell API per prodotti, categorie, pagine CMS o articoli del blog non garantisce l indicizzazione né la posizione nei risultati di ricerca. Il modulo deve essere considerato uno strumento tecnico per la segnalazione degli URL, e non un sostituto di sitemap XML, canonical corretti, robots, hreflang, linking interno e qualità SEO generale.

Materiali ufficiali Google:

• https://developers.google.com/search/apis/indexing-api/v3/quickstart
• https://developers.google.com/search/apis/indexing-api/v3/prereqs
• https://developers.google.com/search/apis/indexing-api/v3/using-api
• https://developers.google.com/search/apis/indexing-api/v3/quota-pricing

2. Requisiti

Prima dell installazione assicurati che l ambiente soddisfi i requisiti:

• Magento 2.4.x,
• PHP 8.1 o successivo,
• Composer,
• cron di Magento funzionante,
• possibilità di installare il pacchetto google/apiclient,
• accesso amministrativo a Magento,
• progetto Google Cloud con Indexing API abilitata,
• property in Google Search Console verificata per il dominio del negozio,
• account di servizio Google aggiunto come proprietario in Google Search Console.

Il modulo richiede il pacchetto:

google/apiclient:^2.16

Il pacchetto è dichiarato nel composer.json del modulo, quindi Composer dovrebbe installarlo automaticamente.

3. Installazione del modulo

3.1. Installazione tramite Composer da repository VCS

Se il modulo viene installato da un repository Git privato o pubblico, aggiungi il repository al progetto Magento:

composer config repositories.kowal.google.indexing.api vcs https://github.com/kowalco/google-indexing-api

Se il repository è privato, configura il token GitHub:

composer config --global --auth github-oauth.github.com 

Installa il pacchetto:

composer require kowal/module-google-indexing-api

Abilita il modulo:

bin/magento module:enable Kowal_GoogleIndexingApi

Esegui l aggiornamento dello schema del database:

bin/magento setup:upgrade

Svuota la cache:

bin/magento cache:flush

In modalità produzione esegui inoltre:

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3.2. Installazione locale in app/code

Se il modulo viene installato senza Composer come codice locale, posizionalo nella directory:

app/code/Kowal/GoogleIndexingApi

Successivamente installa la dipendenza Google API Client nel progetto Magento:

composer require google/apiclient:^2.16

Abilita il modulo ed esegui i comandi standard di Magento:

bin/magento module:enable Kowal_GoogleIndexingApibin/magento setup:upgradebin/magento cache:flush

Per la produzione:

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3.3. Verifica dell installazione

Controlla che il modulo sia attivo:

bin/magento module:status Kowal_GoogleIndexingApi

Dopo una corretta installazione nel pannello di amministrazione dovrebbero essere disponibili:

• Stores > Configuration > Kowal > Google Indexing API,
• menu amministrativo Google Indexing API > Indexing Queue,
• Google Indexing API > Import URLs,
• Google Indexing API > API Logs,
• Google Indexing API > Setup Assistant.

Nel database dovrebbero essere create le tabelle:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Preparazione di Google Cloud e Search Console

4.1. Creazione del progetto Google Cloud

1. Vai a Google Cloud Console.
2. Crea un nuovo progetto oppure seleziona un progetto esistente usato per il negozio.
3. Abilita l API:

Indexing API

Senza API abilitata il modulo non potrà inviare correttamente le segnalazioni.

4.2. Creazione dell account di servizio

1. In Google Cloud vai in IAM & Admin > Service Accounts.
2. Crea un nuovo account di servizio.
3. Genera una chiave in formato JSON.
4. Scarica il file JSON e conservalo in modo sicuro.

Il modulo richiede che il JSON contenga almeno i campi:

• type,
• project_id,
• private_key,
• client_email.

Il campo type deve avere il valore:

service_account

4.3. Aggiunta dell account di servizio come proprietario in Search Console

1. Apri Google Search Console.
2. Seleziona la property corrispondente al dominio del negozio.
3. Assicurati che la property sia verificata.
4. Aggiungi l indirizzo client_email del file JSON come proprietario della property.

Esempio di indirizzo dell account di servizio:

my-service-account@project-name.iam.gserviceaccount.com

Se l account di servizio non sarà proprietario della property in Search Console, Google potrebbe restituire errori di autorizzazione, ad esempio la mancanza di conferma della proprietà dell URL.

5. Configurazione del modulo in Magento

La configurazione si trova in:

Stores > Configuration > Kowal > Google Indexing API

La configurazione supporta gli scope di Magento:

• Default Config,
• Website,
• Store View.

In questo modo è possibile avere impostazioni separate per diversi negozi o store view, se il progetto lo richiede.

6. Sezione General

Enable

Predefinito:

No

Abilita o disabilita il funzionamento del modulo.

Quando il campo ha valore No, il cron non elabora la coda. Gli indirizzi possono esistere nel database, ma il processore della coda non li invierà a Google.

Raccomandazione:

• durante la prima configurazione imposta No oppure lascia Dry Run = Yes,
• dopo test corretti imposta Yes.

Dry Run

Predefinito:

Yes

Modalità di test. Quando Dry Run è abilitato, il modulo elabora i record della coda, salva stati e log, ma non invia una segnalazione reale a Google.

È la modalità più sicura per il primo avvio, i test di configurazione e la verifica che gli URL entrino nella coda come previsto.

Raccomandazione:

• esegui sempre i primi test con Dry Run = Yes,
• disattiva Dry Run solo dopo aver verificato credentials, allowed hosts, coda e log.

7. Sezione Google Access Credentials

Credentials Source

Predefinito:

Encrypted configuration value

Definisce da dove il modulo recupera il JSON dell account di servizio Google.

Opzioni disponibili:

Raccomandazione:

• per implementazioni semplici si può usare il valore cifrato in configurazione,
• per ambienti con controllo di accesso ai file può essere più comodo l upload del file JSON.

Service Account JSON

Visibile quando Credentials Source = Encrypted configuration value.

In questo campo va incollato l intero contenuto del file JSON dell account di servizio Google.

Il modulo valida il JSON prima del salvataggio. Vengono verificati:

• correttezza del formato JSON,
• presenza dei campi type, project_id, private_key, client_email,
• valore type = service_account.

Il valore viene salvato come configurazione cifrata di Magento.

Service Account JSON File

Visibile quando Credentials Source = Uploaded JSON file.

Consente di caricare il file JSON dell account di servizio Google.

Il modulo:

• accetta solo file con estensione .json,
• valida il contenuto del file,
• verifica i campi richiesti type, project_id, private_key, client_email,
• salva il file fuori dalla directory pubblica, in var/google-indexing,
• prova a impostare i permessi del file su 0600, se il driver del file system lo consente.

Il file viene salvato con un nome dipendente dallo scope di configurazione, ad esempio per lo scope globale:

var/google-indexing/service-account-default-0.json

Google Cloud Project ID

Campo di testo per l identificatore del progetto Google Cloud.

Nell implementazione attuale del modulo l autorizzazione principale si basa sui dati del JSON dell account di servizio. Il campo Google Cloud Project ID ha funzione informativa e di organizzazione della configurazione, soprattutto quando il negozio utilizza più ambienti o più progetti Google Cloud.

Raccomandazione:

• inserisci il valore project_id del file JSON,
• usa progetti Google Cloud separati per ambienti di produzione e test, se tale separazione è prevista nel progetto.

8. Sezione Queue and Limits

Daily Publish Limit

Predefinito:

200

Definisce il numero massimo di segnalazioni publish che il modulo può eseguire in un giorno.

Il limiter conta le request di tipo:

• publish,
• publish_dry_run.

Se il limite viene raggiunto, il processore della coda non preleverà ulteriori record da inviare fino alla successiva finestra giornaliera.

Raccomandazione:

• lascia 200 se il progetto utilizza il limite onboarding predefinito di Google,
• aumenta il valore solo se il progetto Google Cloud ha un limite superiore approvato,
• l impostazione 0 blocca l invio, perché il numero di slot disponibili sarà 0.

Requests Per Minute Limit

Predefinito:

60

Definisce il numero massimo di request publish al minuto.

Il modulo confronta questo valore con il numero di request salvate nei log nell ultimo minuto. Se il limite al minuto è stato raggiunto, il cron non elaborerà altri record in quella esecuzione.

Raccomandazione:

• per un implementazione tipica lascia il valore predefinito,
• riduci il valore se vuoi caricare l API in modo più conservativo,
• non impostare 0, a meno che tu non voglia fermare temporaneamente l invio.

Cron Batch Size

Predefinito:

20

Definisce il numero massimo di record della coda elaborati in una singola esecuzione del cron.

Il numero reale di record elaborati è limitato anche da:

• Daily Publish Limit,
• Requests Per Minute Limit,
• numero di record pronti per l invio,
• stato e data di scheduled_at.

Raccomandazione:

• 20 è un valore iniziale sicuro,
• con code grandi si può aumentare il valore, ma solo tenendo conto dei limiti di Google.

Default Indexing Lag (minutes)

Predefinito:

15

Definisce il ritardo predefinito tra l aggiunta di un URL alla coda e il momento a partire dal quale può essere inviato.

Il ritardo aiuta a:

• ridurre i duplicati,
• evitare l invio dopo ogni piccola modifica,
• dare all amministratore il tempo di correggere i contenuti,
• gestire meglio il limite API.

Nell implementazione attuale questa impostazione viene usata quando la segnalazione non ha un proprio ritardo.

Manual Form Indexing Lag (minutes)

Predefinito:

15

Definisce il ritardo per gli URL aggiunti tramite il modulo:

Google Indexing API > Import URLs

Se l amministratore incolla manualmente un elenco di URL, ogni indirizzo valido verrà pianificato con questo ritardo.

Raccomandazione:

• imposta 0 se l importazione manuale deve entrare immediatamente nella coda,
• lascia 15 se vuoi mantenere un buffer per deduplicazione e controllo delle segnalazioni.

Mass Action Indexing Lag (minutes)

Predefinito:

15

Definisce il ritardo per gli URL aggiunti tramite:

• azioni massive sui prodotti,
• azioni massive sulle pagine CMS,
• pulsanti di richiesta indicizzazione nelle schermate di modifica di prodotto, categoria e pagina CMS.

Raccomandazione:

• per operazioni massive lascia il valore 15 o superiore,
• per piccoli negozi e lavoro amministrativo manuale si può valutare un valore inferiore.

Max Attempts

Predefinito:

5

Definisce il numero massimo di tentativi di invio di un singolo record della coda.

Se Google restituisce un errore temporaneo, il modulo imposterà lo stato retry, purché il numero di tentativi sia inferiore a Max Attempts. Dopo aver superato il limite, il record riceverà lo stato failed_permanent.

Errori considerati temporanei:

• 408,
• 409,
• 412,
• 429,
• 500,
• 502,
• 503,
• 504.

Retry Delay (minutes)

Predefinito:

15

Ritardo di base prima del tentativo successivo di invio dopo un errore temporaneo.

Il cron usa un ritardo crescente. Il moltiplicatore dipende dal numero di tentativi ed è limitato a un massimo di 24. In questo modo i tentativi successivi non vengono eseguiti in modo troppo aggressivo.

Esempio per il valore 15:

Allowed Source Types

Predefinito:

manual,product,category,cms_page,amasty_blog_post

Elenco dei tipi di fonte consentiti, separati da virgola.

Valori supportati:

Se il tipo di fonte non si trova nell elenco, lo scheduler salterà la segnalazione e la contrassegnerà come skipped.

Raccomandazione:

• lascia i valori predefiniti se il negozio usa tutte le fonti standard,
• rimuovi le fonti che non vuoi ammettere nella coda.

Allowed URL Hosts

Predefinito:

vuoto

Elenco degli host URL consentiti, separati da virgola.

Esempio:

example.com,www.example.com

Se l elenco è compilato, il modulo accetterà solo gli indirizzi appartenenti agli host indicati. Se l URL ha un host diverso, la validazione restituirà l errore:

host_not_allowed

Raccomandazione:

• in produzione compila sempre questo elenco,
• aggiungi tutti gli host usati dal negozio, ad esempio dominio principale, versione www, domini store view e domini linguistici,
• non aggiungere domini di test alla configurazione di produzione.

Require HTTPS URLs

Predefinito:

Yes

Impone che gli URL segnalati usino lo schema https.

Se il campo è abilitato, un indirizzo con http verrà rifiutato con l errore:

https_required

Raccomandazione:

• per i negozi di produzione lascia Yes,
• usa No solo in ambienti di test eccezionali.

9. Sezione Auto-Indexing

Enable Auto-Indexing

Predefinito:

No

Il campo è predisposto per integrazioni automatiche di salvataggio o rimozione delle entità e di provider URL aggiuntivi.

Nell attuale ambito del modulo sono disponibili meccanismi manuali e amministrativi per aggiungere URL alla coda, tra cui importazione URL, Mass Actions e pulsanti nei moduli di modifica.

Raccomandazione:

• lascia No se l auto-indexing non è stato implementato nel progetto,
• abilitalo solo quando il progetto include la gestione di eventi automatici delle entità che usa questa configurazione.

10. Sezione Logs

API Log Retention Days

Predefinito:

90

Definisce il numero di giorni di conservazione dei log API.

Il cron di pulizia dei log viene eseguito ogni giorno alle:

03:15

Rimuove le voci più vecchie del numero di giorni impostato in questo campo.

Raccomandazione:

• 90 giorni sono un valore diagnostico ragionevole,
• con un numero elevato di request si può ridurre la retention,
• in caso di audit SEO si può aumentare la retention, ricordando la dimensione della tabella dei log.

11. Assistente di installazione e configurazione

L assistente si trova in:

Google Indexing API > Setup Assistant

Il suo scopo è verificare rapidamente se la configurazione lato Magento e Google è pronta per il primo test.

11.1. Sezione Current Status

L assistente mostra lo stato corrente degli elementi più importanti:

Se Credentials ha stato Missing or invalid, è necessario tornare alla configurazione e correggere il JSON o il file credentials.

Se Allowed Hosts mostra Not configured, il modulo non limita gli host. Tecnicamente può funzionare, ma in produzione è consigliato inserire esplicitamente gli host del negozio.

11.2. Sezione Setup Steps

L assistente visualizza l elenco dei passaggi necessari prima della prima request reale:

1. Creazione o selezione del progetto Google Cloud.
2. Abilitazione di Indexing API e creazione della JSON key per l account di servizio.
3. Incollare il JSON oppure caricare il file JSON nella configurazione di Magento.
4. Aggiungere l email del service account come proprietario in Google Search Console.
5. Eseguire i test, quindi importare un URL con Dry Run abilitato.

L assistente contiene link a:

• Google Cloud per Indexing API,
• configurazione del modulo in Magento,
• Google Search Console.

11.3. Test Google Credentials

Pulsante:

Test Google Credentials

verifica se Magento è in grado di usare i dati dell account di servizio per ottenere un token OAuth per lo scope:

https://www.googleapis.com/auth/indexing

Un risultato positivo significa che:

• il JSON è corretto,
• la chiave privata può essere usata,
• Google ha emesso un token OAuth.

Un risultato negativo può indicare:

• JSON non corretto,
• private_key errata o danneggiata,
• campo richiesto mancante nel JSON,
• problema di comunicazione con Google,
• uso di una chiave che non è una chiave di account di servizio.

Questo test non conferma ancora che l account di servizio abbia accesso proprietario al dominio in Search Console. Per questo è necessario un test URL metadata oppure una reale segnalazione di un URL di prova.

11.4. Test URL Metadata

Modulo:

Test URL Metadata

consente di inserire un URL pubblico di un host consentito ed eseguire una request metadata a Google Indexing API.

Prima di inviare la request il modulo:

• normalizza l URL,
• verifica che l URL sia assoluto,
• controlla lo schema http oppure https,
• con Require HTTPS URLs abilitato richiede https,
• verifica Allowed URL Hosts, se sono stati configurati.

Possibili risultati:

Il test metadata non crea una nuova segnalazione publish. Serve per la diagnostica della connessione e dello stato dell URL.

12. Primo avvio passo dopo passo

Ordine consigliato per il primo avvio:

1. Installa il modulo ed esegui setup:upgrade.
2. In Magento vai in Stores > Configuration > Kowal > Google Indexing API.
3. Imposta Enable = Yes.
4. Lascia Dry Run = Yes.
5. Seleziona la fonte delle credentials.
6. Incolla il JSON dell account di servizio oppure carica il file JSON.
7. Compila Google Cloud Project ID con il valore project_id del JSON.
8. Compila Allowed URL Hosts, ad esempio example.com,www.example.com.
9. Lascia i limiti predefiniti se Google non ha approvato limiti superiori.
10. Salva la configurazione e svuota la cache.
11. Vai in Google Indexing API > Setup Assistant.
12. Controlla che l assistente mostri le credentials come pronte.
13. Fai clic su Test Google Credentials.
14. Aggiungi l email del service account come proprietario in Google Search Console, se non è già stato fatto.
15. Esegui Test URL Metadata per un URL pubblico di un host consentito.
16. Vai in Google Indexing API > Import URLs.
17. Aggiungi un URL di test con azione URL_UPDATED.
18. Esegui il cron di Magento:

bin/magento cron:run

19. Controlla Google Indexing API > Indexing Queue.
20. Controlla Google Indexing API > API Logs.
21. Se tutto funziona correttamente, disattiva Dry Run.
22. Aggiungi di nuovo un URL di test e controlla la risposta reale di Google.

13. Importazione URL dal pannello di amministrazione

L importazione manuale si trova in:

Google Indexing API > Import URLs

Il modulo contiene i campi:

Azioni disponibili:

Dopo l invio del modulo, il modulo mostrerà un riepilogo:

• aggiunti,
• aggiornati,
• deduplicati,
• non validi,
• saltati.

I primi 10 messaggi di validazione vengono mostrati come notice nel pannello di amministrazione.

14. Coda di indicizzazione

La coda si trova in:

Google Indexing API > Indexing Queue

Ogni record della coda contiene tra l altro:

• URL,
• hash dell URL,
• store ID,
• website ID,
• tipo di fonte,
• ID dell entità sorgente,
• origine della request,
• azione URL_UPDATED oppure URL_DELETED,
• stato,
• priorità,
• numero di tentativi,
• numero massimo di tentativi,
• data di invio pianificata,
• data di elaborazione,
• ultimo codice di errore,
• ultimo motivo dell errore,
• ultimo messaggio di errore,
• risposta di Google,
• informazione created_by.

Stati della coda

Azioni sui record della coda

Nota: Transmit Now esegue una request reale se Dry Run = No. Con Dry Run = Yes verrà salvato un log dry-run senza invio reale a Google.

15. Cron

Il modulo aggiunge due task cron nel gruppo default.

Elaborazione della coda

kowal_google_indexing_process_queue

Pianificazione:

*/5 * * * *

Il task avvia il processore della coda ogni 5 minuti.

Il processore:

1. Controlla se il modulo è abilitato.
2. Rilascia i vecchi lock dei record processing più vecchi di 30 minuti.
3. Sposta i record scheduled in pending se scheduled_at <= now.
4. Controlla gli slot disponibili nei limiti giornalieri e al minuto.
5. Recupera i record pending e retry.
6. Li ordina in base a priorità e data di invio pianificata.
7. Invia la request a Google oppure esegue il dry-run.
8. Salva risposta, stato e log API.

Pulizia dei log

kowal_google_indexing_cleanup_logs

Pianificazione:

15 3 * * *

Il task elimina i log API più vecchi del numero di giorni impostato nel campo:

API Log Retention Days

16. Log API

I log sono disponibili in:

Google Indexing API > API Logs

Il log include:

• ID del record della coda,
• store ID,
• tipo di request,
• URL dell endpoint,
• payload,
• stato HTTP,
• body della risposta,
• durata della request,
• data di creazione del log.

Tipi di request:

17. Mass Actions e pulsanti amministrativi

Il modulo aggiunge meccanismi per segnalare URL dal pannello di amministrazione.

Prodotti

Nella griglia prodotti è disponibile un azione massiva che aggiunge gli URL dei prodotti alla coda.

Il modulo salta i prodotti:

• disabilitati,
• non visibili individualmente.

Gli URL vengono generati sulla base degli URL rewrite per gli store view attivi.

Pagine CMS

Nella griglia delle pagine CMS è disponibile un azione massiva che aggiunge gli URL delle pagine alla coda.

Il modulo salta le pagine non attive.

Se una pagina CMS è assegnata a tutti gli store view, il modulo risolve gli URL per tutti gli store view.

Prodotto, categoria e pagina CMS - pulsanti nel modulo di modifica

Il modulo aggiunge pulsanti per richiedere l indicizzazione nelle schermate di modifica di:

• prodotto,
• categoria,
• pagina CMS.

Il pulsante risolve gli URL dell entità per gli store view e li aggiunge alla coda come URL_UPDATED.

18. Configurazione iniziale consigliata

Per la prima implementazione in produzione:

19. Problemi comuni e diagnostica

Credentials test failed

Controlla:

• se il JSON è corretto,
• se il JSON proviene da un account di servizio,
• se contiene private_key e client_email,
• se il campo type ha valore service_account,
• se il file JSON non è stato danneggiato durante l incollaggio.

Google restituisce un errore di autorizzazione

Controlla:

• se il dominio è verificato in Search Console,
• se il client_email dell account di servizio è stato aggiunto come proprietario,
• se l URL testato appartiene alla stessa property Search Console,
• se stai usando il progetto Google Cloud corretto e il JSON corretto.

L URL viene rifiutato prima dell invio

Controlla il messaggio di validazione:

La coda non viene elaborata

Controlla:

• se Enable = Yes,
• se il cron di Magento funziona,
• se i record hanno stato pending oppure retry,
• se scheduled_at non è nel futuro,
• se i limiti giornalieri o al minuto non sono stati raggiunti,
• se Daily Publish Limit e Requests Per Minute Limit non sono impostati su 0.

I record finiscono in retry

Controlla:

• lo stato HTTP nel record della coda,
• il log API,
• la risposta di Google,
• se è presente il limite 429,
• se ci sono errori temporanei 5xx,
• se Max Attempts e Retry Delay sono impostati come previsto.

20. Integrazione opzionale con Amasty Blog

L integrazione con Amasty Blog è prevista come modulo separato:

Kowal_GoogleIndexingApiAmastyBlog

Pacchetto:

kowal/module-google-indexing-api-amasty-blog

Questo modulo non è richiesto per il funzionamento dell integrazione principale. Va installato solo nei progetti che usano amasty/blog e hanno bisogno di un azione massiva per gli articoli del blog.