Google Indexing API pentru Magento 2 - instalare și configurare

1. Informații importante înainte de implementare

Modulul integrează Magento 2 cu Google Indexing API și permite adăugarea adreselor URL într-o coadă centrală de trimiteri. Coada este procesată de cron Magento, iar fiecare trimitere este validată, deduplicată, supusă limitelor și logată.

Conform documentației Google, Indexing API este destinat oficial în principal paginilor cu date structurate:

• JobPosting,
• BroadcastEvent încorporat în VideoObject.

Utilizarea API-ului pentru produse, categorii, pagini CMS sau articole de blog nu garantează indexarea sau poziția în rezultatele căutării. Modulul trebuie tratat ca un instrument tehnic pentru trimiterea URL-urilor, nu ca un înlocuitor pentru sitemap XML, canonicale corecte, robots, hreflang, linkuri interne și calitatea generală SEO.

Materiale oficiale 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. Cerințe

Înainte de instalare, asigurați-vă că mediul îndeplinește cerințele:

• Magento 2.4.x,
• PHP 8.1 sau mai nou,
• Composer,
• cron Magento funcțional,
• posibilitatea de a instala pachetul google/apiclient,
• acces administrativ la Magento,
• proiect Google Cloud cu Indexing API activat,
• proprietate în Google Search Console verificată pentru domeniul magazinului,
• contul de serviciu Google adăugat ca proprietar în Google Search Console.

Modulul necesită pachetul:

google/apiclient:^2.16

Pachetul este declarat în composer.json al modulului, astfel încât Composer ar trebui să îl instaleze automat.

3. Instalarea modulului

3.1. Instalare prin Composer dintr-un repository VCS

Dacă modulul este instalat dintr-un repository Git privat sau public, adăugați repository-ul în proiectul Magento:

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

Dacă repository-ul este privat, configurați tokenul GitHub:

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

Instalați pachetul:

composer require kowal/module-google-indexing-api

Activați modulul:

bin/magento module:enable Kowal_GoogleIndexingApi

Executați actualizarea schemei bazei de date:

bin/magento setup:upgrade

Goliți cache-ul:

bin/magento cache:flush

În modul producție executați suplimentar:

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

3.2. Instalare locală în app/code

Dacă modulul este instalat fără Composer ca cod local, plasați-l în directorul:

app/code/Kowal/GoogleIndexingApi

Apoi instalați dependența Google API Client în proiectul Magento:

composer require google/apiclient:^2.16

Activați modulul și executați comenzile standard Magento:

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

Pentru producție:

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

3.3. Verificarea instalării

Verificați dacă modulul este activ:

bin/magento module:status Kowal_GoogleIndexingApi

După instalarea corectă, în panoul de administrare ar trebui să fie disponibile:

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

În baza de date ar trebui să fie create tabelele:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Pregătirea Google Cloud și Search Console

4.1. Crearea proiectului Google Cloud

1. Accesați Google Cloud Console.
2. Creați un proiect nou sau selectați un proiect existent utilizat pentru magazin.
3. Activați API-ul:

Indexing API

Fără API activat, modulul nu va putea trimite corect solicitările.

4.2. Crearea contului de serviciu

1. În Google Cloud accesați IAM & Admin > Service Accounts.
2. Creați un cont de serviciu nou.
3. Generați o cheie în format JSON.
4. Descărcați fișierul JSON și păstrați-l în siguranță.

Modulul cere ca JSON-ul să conțină cel puțin câmpurile:

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

Câmpul type trebuie să aibă valoarea:

service_account

4.3. Adăugarea contului de serviciu ca proprietar în Search Console

1. Deschideți Google Search Console.
2. Selectați proprietatea corespunzătoare domeniului magazinului.
3. Asigurați-vă că proprietatea este verificată.
4. Adăugați adresa client_email din fișierul JSON ca proprietar al proprietății.

Exemplu de adresă a contului de serviciu:

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

Dacă acel cont de serviciu nu este proprietarul proprietății din Search Console, Google poate returna erori de permisiuni, de exemplu lipsa confirmării proprietății URL-ului.

5. Configurarea modulului în Magento

Configurația se află în:

Stores > Configuration > Kowal > Google Indexing API

Configurația suportă scope-urile Magento:

• Default Config,
• Website,
• Store View.

Datorită acestui lucru, puteți avea setări separate pentru magazine sau view-uri diferite, dacă proiectul necesită acest lucru.

6. Secțiunea General

Enable

Implicit:

No

Activează sau dezactivează funcționarea modulului.

Când câmpul are valoarea No, cron nu procesează coada. Adresele pot exista în baza de date, dar procesorul cozii nu le va trimite către Google.

Recomandare:

• în timpul configurării inițiale setați No sau lăsați Dry Run = Yes,
• după testele reușite setați Yes.

Dry Run

Implicit:

Yes

Mod de test. Când Dry Run este activat, modulul procesează înregistrările din coadă, salvează statusurile și logurile, dar nu trimite solicitări reale către Google.

Acesta este cel mai sigur mod pentru prima pornire, testele de configurare și verificarea faptului că URL-urile ajung în coadă conform așteptărilor.

Recomandare:

• efectuați întotdeauna primele teste cu Dry Run = Yes,
• dezactivați Dry Run abia după verificarea credentials, allowed hosts, cozii și logurilor.

7. Secțiunea Google Access Credentials

Credentials Source

Implicit:

Encrypted configuration value

Definește de unde preia modulul JSON-ul contului de serviciu Google.

Opțiuni disponibile:

Recomandare:

• pentru implementări simple se poate folosi valoarea criptată din configurație,
• pentru mediile cu control al accesului la fișiere, încărcarea fișierului JSON poate fi mai convenabilă.

Service Account JSON

Vizibil atunci când Credentials Source = Encrypted configuration value.

În acest câmp trebuie lipit conținutul complet al fișierului JSON al contului de serviciu Google.

Modulul validează JSON-ul înainte de salvare. Sunt verificate:

• corectitudinea formatului JSON,
• prezența câmpurilor type, project_id, private_key, client_email,
• valoarea type = service_account.

Valoarea este salvată ca configurație Magento criptată.

Service Account JSON File

Vizibil atunci când Credentials Source = Uploaded JSON file.

Permite încărcarea fișierului JSON al contului de serviciu Google.

Modulul:

• acceptă doar fișiere cu extensia .json,
• validează conținutul fișierului,
• verifică prezența câmpurilor obligatorii type, project_id, private_key, client_email,
• salvează fișierul în afara directorului public, în var/google-indexing,
• încearcă să seteze permisiunile fișierului la 0600, dacă driverul de fișiere permite acest lucru.

Fișierul este salvat cu un nume dependent de scope-ul configurației, de exemplu pentru scope-ul global:

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

Google Cloud Project ID

Câmp text pentru identificatorul proiectului Google Cloud.

În implementarea actuală a modulului, autorizarea principală se bazează pe datele din JSON-ul contului de serviciu. Câmpul Google Cloud Project ID are un rol informativ și ajută la organizarea configurației, mai ales atunci când magazinul folosește mai multe medii sau mai multe proiecte Google Cloud.

Recomandare:

• introduceți valoarea project_id din fișierul JSON,
• folosiți proiecte Google Cloud separate pentru mediile de producție și de test, dacă această separare este adoptată în proiect.

8. Secțiunea Queue and Limits

Daily Publish Limit

Implicit:

200

Definește numărul maxim de trimiteri publish pe care modulul le poate efectua într-o zi.

Limiterul numără requesturile de tip:

• publish,
• publish_dry_run.

Dacă limita este consumată, procesorul cozii nu va prelua alte înregistrări pentru trimitere până la următoarea fereastră zilnică.

Recomandare:

• lăsați 200 dacă proiectul utilizează limita implicită de onboarding Google,
• măriți valoarea doar atunci când proiectul Google Cloud are aprobată o limită mai mare,
• setarea 0 blochează trimiterea, deoarece numărul de sloturi disponibile va fi 0.

Requests Per Minute Limit

Implicit:

60

Definește numărul maxim de requesturi publish pe minut.

Modulul compară această valoare cu numărul de requesturi salvate în loguri în ultimul minut. Dacă limita pe minut este atinsă, cron nu va procesa alte înregistrări în acea execuție.

Recomandare:

• pentru o implementare tipică, păstrați valoarea implicită,
• reduceți valoarea dacă doriți să încărcați API-ul mai conservator,
• nu setați 0, decât dacă doriți să opriți temporar trimiterea.

Cron Batch Size

Implicit:

20

Definește numărul maxim de înregistrări din coadă procesate într-o singură execuție cron.

Numărul real de înregistrări procesate este limitat suplimentar de:

• Daily Publish Limit,
• Requests Per Minute Limit,
• numărul de înregistrări gata de trimitere,
• statusul și data scheduled_at.

Recomandare:

• 20 este o valoare de start sigură,
• pentru cozi mari valoarea poate fi crescută, dar numai ținând cont de limitele Google.

Default Indexing Lag (minutes)

Implicit:

15

Definește întârzierea implicită dintre adăugarea URL-ului în coadă și momentul din care poate fi trimis.

Întârzierea ajută la:

• reducerea duplicatelor,
• evitarea trimiterii după fiecare schimbare minoră,
• oferirea de timp administratorului pentru corectarea conținutului,
• gestionarea mai bună a limitelor API.

În implementarea actuală, această setare este folosită atunci când trimiterea nu are propria întârziere.

Manual Form Indexing Lag (minutes)

Implicit:

15

Definește întârzierea pentru URL-urile adăugate prin formularul:

Google Indexing API > Import URLs

Dacă administratorul lipește manual o listă de URL-uri, fiecare adresă corectă va fi planificată cu această întârziere.

Recomandare:

• setați 0 dacă importul manual trebuie să ajungă imediat în coadă,
• lăsați 15 dacă doriți să păstrați un buffer pentru deduplicare și controlul trimiterilor.

Mass Action Indexing Lag (minutes)

Implicit:

15

Definește întârzierea pentru URL-urile adăugate prin:

• acțiuni în masă pentru produse,
• acțiuni în masă pentru pagini CMS,
• butoanele de trimitere a indexării de pe ecranele de editare ale produsului, categoriei și paginii CMS.

Recomandare:

• pentru operațiuni în masă, păstrați valoarea 15 sau una mai mare,
• pentru magazine mici și muncă administrativă manuală poate fi luată în calcul o valoare mai mică.

Max Attempts

Implicit:

5

Definește numărul maxim de încercări de trimitere a unei singure înregistrări din coadă.

Dacă Google returnează o eroare temporară, modulul va seta statusul retry, dacă numărul de încercări este mai mic decât Max Attempts. După depășirea limitei, înregistrarea va primi statusul failed_permanent.

Erori tratate ca temporare:

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

Retry Delay (minutes)

Implicit:

15

Întârzierea de bază înainte de următoarea încercare de trimitere după o eroare temporară.

Cron folosește o întârziere progresivă. Multiplicatorul depinde de numărul de încercări și este limitat la maximum 24. Astfel, încercările succesive nu sunt executate prea agresiv.

Exemplu pentru valoarea 15:

Allowed Source Types

Implicit:

manual,product,category,cms_page,amasty_blog_post

Lista tipurilor de surse permise, separate prin virgule.

Valori suportate:

Dacă tipul sursei nu se află pe listă, schedulerul va omite trimiterea și o va marca drept skipped.

Recomandare:

• păstrați valorile implicite dacă magazinul folosește toate sursele standard,
• eliminați sursele pe care nu doriți să le permiteți în coadă.

Allowed URL Hosts

Implicit:

gol

Lista hosturilor URL permise, separată prin virgule.

Exemplu:

example.com,www.example.com

Dacă lista este completată, modulul va accepta doar adresele aparținând hosturilor indicate. Dacă URL-ul are alt host, validarea va returna eroarea:

host_not_allowed

Recomandare:

• în producție completați întotdeauna această listă,
• adăugați toate hosturile folosite de magazin, de exemplu domeniul principal, versiunea www, domeniile store view și domeniile de limbă,
• nu adăugați domenii de test în configurația de producție.

Require HTTPS URLs

Implicit:

Yes

Impune ca URL-urile trimise să folosească schema https.

Dacă acest câmp este activat, o adresă cu http va fi respinsă cu eroarea:

https_required

Recomandare:

• pentru magazinele de producție păstrați Yes,
• folosiți No doar în medii de test excepționale.

9. Secțiunea Auto-Indexing

Enable Auto-Indexing

Implicit:

No

Câmpul este pregătit pentru integrări automate la salvarea sau ștergerea entităților și pentru provideri suplimentari de URL-uri.

În aria actuală a modulului sunt disponibile mecanisme manuale și administrative de adăugare a URL-urilor în coadă, inclusiv import URL-uri, Mass Actions și butoane în formularele de editare.

Recomandare:

• păstrați No dacă auto-indexing nu a fost implementat în proiect,
• activați-l doar atunci când proiectul conține suport pentru evenimente automate ale entităților care folosesc această configurație.

10. Secțiunea Logs

API Log Retention Days

Implicit:

90

Definește numărul de zile de păstrare a logurilor API.

Cronul care curăță logurile rulează zilnic la:

03:15

Elimină intrările mai vechi decât numărul de zile setat în acest câmp.

Recomandare:

• 90 de zile reprezintă o valoare rezonabilă pentru diagnosticare,
• în cazul unui număr mare de requesturi, retenția poate fi redusă,
• în audituri SEO, retenția poate fi crescută, ținând cont de dimensiunea tabelului de loguri.

11. Asistentul de instalare și configurare

Asistentul se află în:

Google Indexing API > Setup Assistant

Scopul lui este verificarea rapidă a faptului că setările din Magento și Google sunt pregătite pentru primul test.

11.1. Secțiunea Current Status

Asistentul afișează starea curentă a celor mai importante elemente:

Dacă Credentials are statusul Missing or invalid, trebuie să reveniți la configurare și să corectați JSON-ul sau fișierul credentials.

Dacă Allowed Hosts afișează Not configured, modulul nu limitează hosturile. Tehnic acest lucru poate funcționa, dar în producție este recomandată introducerea explicită a hosturilor magazinului.

11.2. Secțiunea Setup Steps

Asistentul afișează lista pașilor necesari înainte de primul request real:

1. Crearea sau selectarea proiectului Google Cloud.
2. Activarea Indexing API și crearea unei chei JSON pentru contul de serviciu.
3. Lipirea JSON-ului sau încărcarea fișierului JSON în configurația Magento.
4. Adăugarea service account email ca proprietar în Google Search Console.
5. Rularea testelor, apoi importul unui URL cu Dry Run activat.

Asistentul conține linkuri către:

• Google Cloud pentru Indexing API,
• configurația modulului în Magento,
• Google Search Console.

11.3. Test Google Credentials

Butonul:

Test Google Credentials

verifică dacă Magento poate folosi datele contului de serviciu pentru a obține un token OAuth pentru scope-ul:

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

Un rezultat pozitiv înseamnă că:

• JSON-ul este corect,
• cheia privată poate fi utilizată,
• Google a emis tokenul OAuth.

Un rezultat negativ poate însemna:

• JSON incorect,
• private_key greșit sau corupt,
• lipsa unui câmp obligatoriu în JSON,
• o problemă de comunicare cu Google,
• utilizarea unei chei care nu aparține unui cont de serviciu.

Acest test nu confirmă încă faptul că respectivul cont de serviciu are drepturi de proprietar asupra domeniului în Search Console. Pentru aceasta este necesar testul URL metadata sau o trimitere reală a unui URL de test.

11.4. Test URL Metadata

Formularul:

Test URL Metadata

permite introducerea unui URL public de pe un host permis și executarea unui request metadata către Google Indexing API.

Înainte de trimiterea requestului, modulul:

• normalizează URL-ul,
• verifică dacă URL-ul este absolut,
• verifică schema http sau https,
• când Require HTTPS URLs este activat, impune https,
• verifică Allowed URL Hosts, dacă au fost configurate.

Rezultate posibile:

Testul metadata nu creează o nouă trimitere publish. El servește la diagnosticarea conexiunii și a statusului URL-ului.

12. Prima pornire pas cu pas

Ordinea recomandată pentru prima pornire:

1. Instalați modulul și rulați setup:upgrade.
2. În Magento accesați Stores > Configuration > Kowal > Google Indexing API.
3. Setați Enable = Yes.
4. Lăsați Dry Run = Yes.
5. Selectați sursa credentials.
6. Lipiți JSON-ul contului de serviciu sau încărcați fișierul JSON.
7. Completați Google Cloud Project ID cu valoarea project_id din JSON.
8. Completați Allowed URL Hosts, de exemplu example.com,www.example.com.
9. Păstrați limitele implicite dacă Google nu a aprobat limite mai mari.
10. Salvați configurația și goliți cache-ul.
11. Accesați Google Indexing API > Setup Assistant.
12. Verificați dacă asistentul afișează credentials ca fiind pregătite.
13. Faceți clic pe Test Google Credentials.
14. Adăugați service account email ca proprietar în Google Search Console, dacă acest lucru nu a fost făcut deja.
15. Executați Test URL Metadata pentru un URL public de pe un host permis.
16. Accesați Google Indexing API > Import URLs.
17. Adăugați un URL de test cu acțiunea URL_UPDATED.
18. Rulați cron Magento:

bin/magento cron:run

19. Verificați Google Indexing API > Indexing Queue.
20. Verificați Google Indexing API > API Logs.
21. Dacă totul funcționează corect, dezactivați Dry Run.
22. Adăugați din nou un URL de test și verificați răspunsul real Google.

13. Importul URL-urilor din panoul de administrare

Importul manual se află în:

Google Indexing API > Import URLs

Formularul conține câmpurile:

Acțiuni disponibile:

După trimiterea formularului, modulul va afișa un rezumat:

• adăugate,
• actualizate,
• deduplicate,
• incorecte,
• omise.

Primele 10 mesaje de validare sunt afișate ca notice în panoul de administrare.

14. Coada de indexare

Coada se află în:

Google Indexing API > Indexing Queue

Fiecare înregistrare din coadă conține, printre altele:

• URL,
• hash-ul URL-ului,
• store ID,
• website ID,
• tipul sursei,
• ID-ul entității sursă,
• originea requestului,
• acțiunea URL_UPDATED sau URL_DELETED,
• statusul,
• prioritatea,
• numărul de încercări,
• numărul maxim de încercări,
• data trimiterii planificate,
• data procesării,
• ultimul cod de eroare,
• ultimul motiv al erorii,
• ultimul mesaj de eroare,
• răspunsul Google,
• informația created_by.

Statusurile cozii

Acțiuni asupra înregistrărilor din coadă

Notă: Transmit Now execută un request real dacă Dry Run = No. Cu Dry Run = Yes va fi salvat un log dry-run fără trimitere reală către Google.

15. Cron

Modulul adaugă două taskuri cron în grupul default.

Procesarea cozii

kowal_google_indexing_process_queue

Programare:

*/5 * * * *

Taskul pornește procesorul cozii la fiecare 5 minute.

Procesorul:

1. Verifică dacă modulul este activat.
2. Eliberează blocările vechi ale înregistrărilor processing mai vechi de 30 de minute.
3. Mută înregistrările scheduled în pending dacă scheduled_at <= now.
4. Verifică sloturile disponibile în limitele zilnice și pe minut.
5. Preia înregistrările pending și retry.
6. Le sortează după prioritate și data trimiterii planificate.
7. Trimite requestul către Google sau execută dry-run.
8. Salvează răspunsul, statusul și logul API.

Curățarea logurilor

kowal_google_indexing_cleanup_logs

Programare:

15 3 * * *

Taskul șterge logurile API mai vechi decât numărul de zile setat în câmpul:

API Log Retention Days

16. Loguri API

Logurile sunt disponibile în:

Google Indexing API > API Logs

Logul include:

• ID-ul înregistrării din coadă,
• store ID,
• tipul requestului,
• URL-ul endpointului,
• payload-ul,
• statusul HTTP,
• body-ul răspunsului,
• durata requestului,
• data creării logului.

Tipuri de requesturi:

17. Mass Actions și butoane administrative

Modulul adaugă mecanisme pentru trimiterea URL-urilor din panoul de administrare.

Produse

În gridul de produse este disponibilă o acțiune în masă care adaugă URL-urile produselor în coadă.

Modulul omite produsele:

• dezactivate,
• care nu sunt vizibile individual.

URL-urile sunt generate pe baza URL rewrites pentru store view-urile active.

Pagini CMS

În gridul paginilor CMS este disponibilă o acțiune în masă care adaugă URL-urile paginilor în coadă.

Modulul omite paginile inactive.

Dacă pagina CMS este atribuită tuturor store view-urilor, modulul rezolvă URL-urile pentru toate store view-urile.

Produs, categorie și pagină CMS - butoane în formularul de editare

Modulul adaugă butoane pentru trimiterea indexării pe ecranele de editare ale:

• produsului,
• categoriei,
• paginii CMS.

Butonul rezolvă URL-urile entității pentru store view și le adaugă în coadă ca URL_UPDATED.

18. Configurație inițială recomandată

Pentru prima implementare în producție:

19. Probleme tipice și diagnosticare

Credentials test failed

Verificați:

• dacă JSON-ul este corect,
• dacă JSON-ul provine dintr-un cont de serviciu,
• dacă acesta conține private_key și client_email,
• dacă câmpul type are valoarea service_account,
• dacă fișierul JSON nu a fost corupt în timpul copierii.

Google returnează o eroare de permisiuni

Verificați:

• dacă domeniul este verificat în Search Console,
• dacă client_email al contului de serviciu este adăugat ca proprietar,
• dacă URL-ul testat aparține aceleiași proprietăți Search Console,
• dacă utilizați proiectul Google Cloud corect și JSON-ul corect.

URL-ul este respins înainte de trimitere

Verificați mesajul de validare:

Coada nu este procesată

Verificați:

• dacă Enable = Yes,
• dacă cron Magento funcționează,
• dacă înregistrările au statusul pending sau retry,
• dacă scheduled_at nu este în viitor,
• dacă limitele zilnice sau pe minut nu sunt consumate,
• dacă Daily Publish Limit și Requests Per Minute Limit nu sunt setate la 0.

Înregistrările ajung în retry

Verificați:

• statusul HTTP din înregistrarea cozii,
• logul API,
• răspunsul Google,
• dacă nu apare limita 429,
• dacă nu există erori temporare 5xx,
• dacă Max Attempts și Retry Delay sunt setate conform așteptărilor.

20. Integrare opțională cu Amasty Blog

Integrarea cu Amasty Blog este prevăzută ca modul separat:

Kowal_GoogleIndexingApiAmastyBlog

Pachet:

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

Acest modul nu este necesar pentru funcționarea integrării principale. Trebuie instalat doar în proiectele care folosesc amasty/blog și au nevoie de o acțiune în masă pentru articolele de blog.