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 a una coda centrale di invio. La coda viene elaborata dal cron di Magento e ogni richiesta viene validata, deduplicata, sottoposta a limiti e registrata nei log.

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

• JobPosting,
• BroadcastEventincorporato inVideoObject.

L'utilizzo dell'API per prodotti, categorie, pagine CMS o post del blog non garantisce l'indicizzazione né il posizionamento nei risultati di ricerca. Il modulo deve essere considerato uno strumento tecnico per inviare URL, non un sostituto di sitemap XML, canonical corretti, robots, hreflang, linking interno e qualità SEO complessiva.

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 superiore,
• Composer,
• cron Magento funzionante,
• possibilità di installare il pacchettogoogle/apiclient,
• accesso amministrativo a Magento,
• progetto Google Cloud con Indexing API abilitata,
• proprietà 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 filecomposer.jsondel modulo, quindi Composer dovrebbe installarlo automaticamente.

3. Installazione del modulo

3.1. Installazione tramite Composer

Aggiungi il repository Composer Kowal al progetto Magento:

I dati di accesso al repository Composer, ovvero l indirizzo e-mail del cliente e il token di licenza, saranno inviati via e-mail dopo l acquisto. Sono disponibili anche nel pannello cliente dopo l accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

composer config repositories.kowal composer https://repo.kowal.store

Configura i dati di accesso al repository Composer Kowal:

composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"

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:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3.2. Installazione locale inapp/code

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

app/code/Kowal/GoogleIndexingApi

Quindi installa la dipendenza Google API Client nel progetto Magento:

composer require google/apiclient:^2.16

Abilita il modulo ed esegui i comandi Magento standard:

bin/magento module:enable Kowal_GoogleIndexingApi
bin/magento setup:upgrade
bin/magento cache:flush

Per la produzione:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3.3. Verifica dell'installazione

Controlla se il modulo è 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 amministrativoGoogle 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 di un progetto Google Cloud

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

Indexing API

Senza l'API abilitata, il modulo non potrà inviare correttamente le richieste.

4.2. Creazione dell'account di servizio

1. In Google Cloud vai aIAM & 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.

Campotype 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 proprietà corrispondente al dominio del negozio.
3. Assicurati che la proprietà sia verificata.
4. Aggiungi l'indirizzoclient_emaildel file JSON come proprietario della proprietà.

Esempio di indirizzo dell'account di servizio:

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

Se l'account di servizio non sarà proprietario della proprietà Search Console, Google potrebbe restituire errori di autorizzazione, ad esempio 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 ambiti 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

Predefinita:

No

Abilita o disabilita il funzionamento del modulo.

Quando il campo ha valoreNo, 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 impostaNooppure lasciaDry Run = Yes,
• dopo test corretti impostaYes.

Dry Run

Predefinita:

Yes

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

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

Raccomandazione:

• esegui sempre i primi test conDry Run = Yes,
• disabilitaDry Runsolo dopo aver verificato credentials, allowed hosts, coda e log.

7. Sezione Google Access Credentials

Credentials Source

Predefinita:

Encrypted configuration value

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

Opzioni disponibili:

Raccomandazione:

• per implementazioni semplici è possibile usare il valore cifrato nella configurazione,
• per ambienti con controllo dell'accesso ai file può essere più comodo caricare il file JSON.

Service Account JSON

Visibile quandoCredentials Source = Encrypted configuration value.

In questo campo è necessario incollare l'intero contenuto del file JSON dell'account di servizio Google.

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

• correttezza del formato JSON,
• presenza dei campitype,project_id,private_key,client_email,
• valoretype = service_account.

Il valore viene salvato come configurazione Magento cifrata.

Service Account JSON File

Visibile quandoCredentials 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,
• controlla i campi richiestitype,project_id,private_key,client_email,
• salva il file fuori dalla directory pubblica, invar/google-indexing,
• prova a impostare i permessi del file su0600, se il driver dei file lo consente.

Il file viene salvato con un nome dipendente dall'ambito della configurazione, ad esempio per l'ambito 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 campoGoogle Cloud Project IDha una funzione informativa e di organizzazione della configurazione, soprattutto quando il negozio utilizza più ambienti o più progetti Google Cloud.

Raccomandazione:

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

8. Sezione Queue and Limits

Daily Publish Limit

Predefinita:

200

Specifica il numero massimo di richieste publish che il modulo può eseguire in un giorno.

Il limiter conta le request di tipo:

• publish,
• publish_dry_run.

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

Raccomandazione:

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

Requests Per Minute Limit

Predefinita:

60

Specifica il numero massimo di request publish al minuto.

Il modulo confronta questo valore con il numero di request registrate nei log dell'ultimo minuto. Se il limite al minuto è stato utilizzato, 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ù prudente,
• non impostare0, a meno che tu voglia interrompere temporaneamente gli invii.

Cron Batch Size

Predefinita:

20

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

Il numero effettivo di record elaborati è limitato anche da:

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

Raccomandazione:

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

Default Indexing Lag (minutes)

Predefinita:

15

Specifica il ritardo predefinito tra l'aggiunta dell'URL alla coda e il momento a partire dal quale può essere inviato.

Il ritardo aiuta a:

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

Nell'implementazione attuale questa impostazione viene utilizzata quando la richiesta non ha un ritardo proprio.

Manual Form Indexing Lag (minutes)

Predefinita:

15

Specifica 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:

• imposta0se l'importazione manuale deve entrare immediatamente in coda,
• lascia15se vuoi mantenere un buffer per deduplicazione e controllo delle richieste.

Mass Action Indexing Lag (minutes)

Predefinita:

15

Specifica 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 valore15o superiore,
• per piccoli negozi e lavoro amministrativo manuale si può considerare un valore più basso.

Max Attempts

Predefinita:

5

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

Se Google restituisce un errore temporaneo, il modulo imposterà lo statoretry, a condizione che il numero di tentativi sia inferiore aMax Attempts. Dopo il superamento del limite, il record riceverà lo statofailed_permanent.

Errori trattati come temporanei:

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

Retry Delay (minutes)

Predefinita:

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 al massimo a24. In questo modo i tentativi successivi non vengono eseguiti in modo troppo aggressivo.

Esempio per il valore15:

Allowed Source Types

Predefinita:

manual,product,category,cms_page,amasty_blog_post

Elenco dei tipi di origine consentiti, separati da virgole.

Valori supportati:

Se il tipo di origine non si trova nell'elenco, lo scheduler salterà la richiesta e la contrassegnerà comeskipped.

Raccomandazione:

• lascia i valori predefiniti se il negozio utilizza tutte le origini standard,
• rimuovi le origini che non vuoi consentire nella coda.

Allowed URL Hosts

Predefinita:

puste

Elenco degli host URL consentiti, separati da virgole.

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 utilizzati dal negozio, ad esempio il dominio principale, la versionewww, i domini store view e i domini linguistici,
• non aggiungere domini di test alla configurazione di produzione.

Require HTTPS URLs

Predefinita:

Yes

Impone che gli URL inviati utilizzino lo schemahttps.

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

https_required

Raccomandazione:

• per negozi in produzione lasciaYes,
• Nousa

solo in ambienti di test eccezionali.

9. Sezione Auto-Indexing

Predefinita:

No

Valore predefinito:

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

Raccomandazione:

• lasciaNolascia
• se l'auto-indexing non è stato implementato nel progetto,

abilita solo quando il progetto include il supporto di eventi automatici delle entità che utilizzano questa configurazione.

10. Sezione Logs

Predefinita:

90

Valore predefinito:

Specifica il numero di giorni di conservazione dei log API.

03:15

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

Raccomandazione:

• 90Raccomandazione:
• giorni è un valore diagnostico ragionevole,
• con un numero elevato di request è possibile ridurre la retention,

per audit SEO è possibile aumentare la retention, tenendo presente la dimensione della tabella dei log.

11. Assistente di installazione e configurazione

Google Indexing API > Setup Assistant

L'assistente si trova in:

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

11.1. Sezione Current Status

SeCredentialsSeMissing or invalidha stato

SeAllowed HostsSeNot configuredmostra

, il modulo non limita gli host. Tecnicamente può funzionare, ma in produzione è consigliato inserire esplicitamente gli host del negozio.

11.2. Sezione Setup Steps

1. L'assistente visualizza l'elenco dei passaggi necessari prima della prima request reale:
2. Creazione o selezione del progetto Google Cloud.
3. Abilitazione di Indexing API e creazione di una JSON key per l'account di servizio.
4. Incollare il JSON oppure caricare il file JSON nella configurazione Magento.
5. Aggiunta del service account email come proprietario in Google Search Console.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

Test Google Credentials

Pulsante:

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

verifica se Magento è in grado di usare i dati dell'account di servizio per ottenere un token OAuth per l'ambito:

• Un risultato positivo significa che:
• il JSON è corretto,
• la chiave privata può essere utilizzata,

Google ha emesso un token OAuth.

• Un risultato negativo può indicare:
• JSON non corretto,private_key,
• mancanza di un campo richiesto 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 come proprietario al dominio in Search Console. Per questo è necessario il test URL metadata oppure l'invio reale di un URL di test.

11.4. Test URL Metadata

Modulo:

Test URL Metadata

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

Prima di inviare la request, il modulo:

• normalizza l'URL,
• controlla se l'URL è assoluto,
• controlla lo schemahttpohttps,
• conRequire HTTPS URLsabilitato richiedehttps,
• controllaAllowed URL Hosts, se configurati.

Risultati possibili:

Il metadata test non crea una nuova richiesta 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 eseguisetup:upgrade.
2. In Magento vai aStores > Configuration > Kowal > Google Indexing API.
3. ImpostaEnable = Yes.
4. LasciaDry Run = Yes.
5. Seleziona l'origine delle credentials.
6. Incolla il JSON dell'account di servizio oppure carica il file JSON.
7. CompilaGoogle Cloud Project IDcon il valoreproject_iddel JSON.
8. CompilaAllowed URL Hosts, ad esempioexample.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 aGoogle Indexing API > Setup Assistant.
12. Controlla se l'assistente mostra le credentials come pronte.
13. CliccaTest Google Credentials.
14. Aggiungi il service account email come proprietario in Google Search Console, se non è già stato fatto.
15. EseguiTest URL Metadataper un URL pubblico da un host consentito.
16. Vai aGoogle Indexing API > Import URLs.
17. Aggiungi un URL di test con azioneURL_UPDATED.
18. Esegui il cron Magento:

bin/magento cron:run

13. Importazione degli 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 origine,
• ID dell'entità di origine,
• provenienza della request,
• azioneURL_UPDATEDoURL_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 Google,
• informazionecreated_by.

Stati della coda

Azioni sui record della coda

Nota:Transmit Nowesegue una request reale seDry Run = No. ConDry Run = Yesverrà salvato un log dry-run senza invio reale a Google.

15. Cron

Il modulo aggiunge due attività cron nel gruppodefault.

Elaborazione della coda

kowal_google_indexing_process_queue

Pianificazione:

*/5 * * * *

L'attività avvia il processore della coda ogni 5 minuti.

Il processore:

1. Controlla se il modulo è abilitato.
2. Rilascia i vecchi blocchi dei recordprocessingpiù vecchi di 30 minuti.
3. Sposta i recordscheduledinpending, sescheduled_at <= now.
4. Controlla gli slot disponibili nei limiti giornaliero e al minuto.
5. Preleva i recordpendingeretry.
6. Li ordina per 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 * * *

L'attività rimuove 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 inviare URL dal pannello di amministrazione.

Prodotti

Nella griglia dei 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 rewrites 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 inattive.

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 di richiesta indicizzazione nelle schermate di modifica:

• del prodotto,
• della categoria,
• della pagina CMS.

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

18. Configurazione iniziale consigliata

Per la prima implementazione in produzione:

19. Problemi tipici e diagnostica

Credentials test failed

Controlla:

• se il JSON è corretto,
• se il JSON proviene da un account di servizio,
• se contieneprivate_keyeclient_email,
• se il campotypeha valoreservice_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,
• seclient_emaildell'account di servizio è aggiunto come proprietario,
• se l'URL testato appartiene alla stessa proprietà 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:

• seEnable = Yes,
• se il cron Magento funziona,
• se i record hanno statopendingoppureretry,
• sescheduled_atnon è nel futuro,
• se i limiti giornalieri o al minuto non sono stati utilizzati,
• seDaily Publish LimiteRequests Per Minute Limitnon sono impostati su0.

I record finiscono inretry

Controlla:

• stato HTTP nel record della coda,
• log API,
• risposta Google,
• se non si verifica il limite429,
• se non ci sono errori temporanei5xx,
• seMax AttemptseRetry Delaysono 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. Deve essere installato solo nei progetti che utilizzanoamasty/blog e hanno bisogno di un'azione massiva per i post del blog.