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 solicitări. Coada este procesată de cron Magento, iar fiecare solicitare este validată, deduplicată, supusă limitelor și jurnalizată.

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

• JobPosting,
• BroadcastEvent încorporat în VideoObject.

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

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, asigură-te că mediul îndeplinește cerințele:

• Magento 2.4.x,
• PHP 8.1 sau mai nou,
• Composer,
• cron Magento funcțional,
• posibilitatea instalării pachetului google/apiclient,
• acces administrativ la Magento,
• proiect Google Cloud cu Indexing API activat,
• proprietate în Google Search Console verificată pentru domeniul magazinului,
• cont 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

Adaugă repository-ul Composer Kowal în proiectul Magento:

Datele de acces la repository-ul Composer, adresa de e-mail a clientului și tokenul de licență, le vei primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificarea pe kowal.store. Înlocuiește TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului tău, iar TWOJ_TOKEN cu tokenul primit. Execută comenzile în directorul rădăcină Magento.

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

Configurează datele de acces la repository-ul Composer Kowal:

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

Instalează pachetul:

composer require kowal/module-google-indexing-api

Activează modulul:

bin/magento module:enable Kowal_GoogleIndexingApi

Execută actualizarea schemei bazei de date:

bin/magento setup:upgrade

Curăță cache-ul:

bin/magento cache:flush

În modul de producție, execută 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, plasează-l în directorul:

app/code/Kowal/GoogleIndexingApi

Apoi instalează suplimentar dependența Google API Client în proiectul Magento:

composer require google/apiclient:^2.16

Activează modulul și execută 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

Verifică dacă modulul este activ:

bin/magento module:status Kowal_GoogleIndexingApi

După instalarea corectă, în panoul administrativ 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. Accesează Google Cloud Console.
2. Creează un proiect nou sau selectează un proiect existent utilizat pentru magazin.
3. Activează API:

Indexing API

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

4.2. Crearea contului de serviciu

1. În Google Cloud, accesează IAM & Admin > Service Accounts.
2. Creează un cont de serviciu nou.
3. Generează o cheie în format JSON.
4. Descarcă fișierul JSON și păstrează-l în siguranță.

Modulul necesită ca JSON 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 Google Search Console.
2. Selectează proprietatea corespunzătoare domeniului magazinului.
3. Asigură-te că proprietatea este verificată.
4. Adaugă 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ă contul de serviciu nu va fi proprietar al proprietății Search Console, Google poate returna erori de permisiuni, de exemplu lipsa confirmării proprietății asupra 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.

Astfel poți avea setări separate pentru diferite magazine sau store views, 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 primei configurări setează No sau lasă Dry Run = Yes,
• după teste corecte setează Yes.

Dry Run

Implicit:

Yes

Mod de testare. Când Dry Run este activat, modulul procesează înregistrările din coadă, salvează statusurile și logurile, dar nu trimite o solicitare reală către Google.

Este cel mai sigur mod pentru prima pornire, testarea configurației și verificarea faptului că URL-urile ajung în coadă conform așteptărilor.

Recomandare:

• efectuează întotdeauna primele teste cu Dry Run = Yes,
• dezactivează Dry Run numai după verificarea credentials, allowed hosts, cozii și logurilor.

7. Secțiunea Google Access Credentials

Credentials Source

Implicit:

Encrypted configuration value

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

Opțiuni disponibile:

Recomandare:

• pentru implementări simple se poate utiliza valoarea criptată în configurație,
• pentru medii cu control al accesului la fișiere, uploadul fișierului JSON poate fi mai comod.

Service Account JSON

Vizibil 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 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ă câmpurile 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 rol informativ și de organizare a configurației, mai ales atunci când magazinul utilizează mai multe medii sau mai multe proiecte Google Cloud.

Recomandare:

• introdu valoarea project_id din fișierul JSON,
• utilizează proiecte Google Cloud separate pentru mediile de producție și de testare, dacă o astfel de separare este adoptată în proiect.

8. Secțiunea Queue and Limits

Daily Publish Limit

Implicit:

200

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

Limiterul numără requesturile de tip:

• publish,
• publish_dry_run.

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

Recomandare:

• lasă 200 dacă proiectul utilizează limita implicită de onboarding Google,
• crește valoarea numai dacă proiectul Google Cloud are aprobată o limită mai mare,
• setarea 0 blochează trimiterea, deoarece numărul disponibil de sloturi va fi 0.

Requests Per Minute Limit

Implicit:

60

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

Modulul compară această valoare cu numărul de requesturi salvate în loguri din ultimul minut. Dacă limita pe minut este utilizată, cron nu va procesa alte înregistrări în rularea respectivă.

Recomandare:

• pentru o implementare tipică, lasă valoarea implicită,
• redu valoarea dacă vrei să încarci API mai conservator,
• nu seta 0, decât dacă vrei să oprești temporar trimiterea.

Cron Batch Size

Implicit:

20

Stabilește numărul maxim de înregistrări din coadă procesate într-o singură rulare cron.

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

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

Recomandare:

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

Default Indexing Lag (minutes)

Implicit:

15

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

Întârzierea ajută la:

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

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

Manual Form Indexing Lag (minutes)

Implicit:

15

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

Google Indexing API > Import URLs

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

Recomandare:

• setează 0 dacă importul manual trebuie să ajungă imediat în coadă,
• lasă 15 dacă vrei să păstrezi un buffer pentru deduplicare și controlul solicitărilor.

Mass Action Indexing Lag (minutes)

Implicit:

15

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

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

Recomandare:

• pentru operațiuni în masă, lasă valoarea 15 sau una mai mare,
• pentru magazine mici și lucru administrativ manual, se poate lua în considerare o valoare mai mică.

Max Attempts

Implicit:

5

Stabileș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, atât timp cât 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 utilizează o întârziere progresivă. Multiplicatorul depinde de numărul de încercări și este limitat la maximum 24. Astfel, încercările succesive nu sunt efectuate 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 acceptate:

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

Recomandare:

• lasă valorile implicite dacă magazinul utilizează toate sursele standard,
• elimină sursele pe care nu vrei să le permiți în coadă.

Allowed URL Hosts

Implicit:

puste

Lista hosturilor URL permise, separate prin virgule.

Exemplu:

example.com,www.example.com

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

host_not_allowed

Recomandare:

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

Require HTTPS URLs

Implicit:

Yes

Impune ca adresele URL 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, lasă Yes,
• folosește No doar în medii de testare excepționale.

9. Secțiunea Auto-Indexing

Enable Auto-Indexing

Implicit:

No

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

În domeniul actual al modulului sunt disponibile mecanisme manuale și administrative de adăugare a URL-urilor în coadă, printre altele importul URL-urilor, Mass Actions și butoanele de pe formularele de editare.

Recomandare:

• lasă No dacă auto-indexing nu a fost implementat în proiect,
• activează doar atunci când proiectul include suport pentru evenimente automate ale entităților care folosesc această configurație.

10. Secțiunea Logs

API Log Retention Days

Implicit:

90

Stabilește numărul de zile pentru păstrarea logurilor API.

Cronul de curățare a logurilor rulează zilnic la:

03:15

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

Recomandare:

• 90 de zile este o valoare rezonabilă pentru diagnosticare,
• la un număr mare de requesturi, retenția poate fi redusă,
• în cazul auditurilor SEO, retenția poate fi mărită, ținând cont de dimensiunea tabelului de loguri.

11. Asistent de instalare și configurare

Asistentul se află în:

Google Indexing API > Setup Assistant

Scopul său este verificarea rapidă dacă configurația din Magento și Google este pregătită 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ă revii la configurație și să corectezi JSON-ul sau fișierul credentials.

Dacă Allowed Hosts arată 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 unui proiect Google Cloud.
2. Activarea Indexing API și crearea JSON key 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 folosită,
• Google a emis tokenul OAuth.

Un rezultat negativ poate însemna:

• JSON incorect,
• private_key greșit sau deteriorat,
• lipsa unui câmp obligatoriu în JSON,
• problemă de comunicare cu Google,
• utilizarea unei chei care nu este cheia unui cont de serviciu.

Acest test nu confirmă încă faptul că respectivul cont de serviciu are acces de proprietar la domeniu în Search Console. Pentru aceasta este necesar testul URL metadata sau o solicitare reală pentru un URL de test.

11.4. Test URL Metadata

Formularul:

Test URL Metadata

permite introducerea unui URL public dintr-un host permis și efectuarea 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,
• cu Require HTTPS URLs activat, necesită https,
• verifică Allowed URL Hosts, dacă au fost configurate.

Rezultate posibile:

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

12. Prima pornire pas cu pas

Ordinea recomandată pentru prima pornire:

1. Instalează modulul și rulează setup:upgrade.
2. În Magento, accesează Stores > Configuration > Kowal > Google Indexing API.
3. Setează Enable = Yes.
4. Lasă Dry Run = Yes.
5. Alege sursa credentials.
6. Lipește JSON-ul contului de serviciu sau încarcă fișierul JSON.
7. Completează Google Cloud Project ID cu valoarea project_id din JSON.
8. Completează Allowed URL Hosts, de exemplu example.com,www.example.com.
9. Lasă limitele implicite dacă Google nu a aprobat limite mai mari.
10. Salvează configurația și curăță cache-ul.
11. Accesează Google Indexing API > Setup Assistant.
12. Verifică dacă asistentul arată credentials ca pregătite.
13. Apasă Test Google Credentials.
14. Adaugă service account email ca proprietar în Google Search Console, dacă nu ai făcut deja acest lucru.
15. Execută Test URL Metadata pentru un URL public dintr-un host permis.
16. Accesează Google Indexing API > Import URLs.
17. Adaugă un URL de test cu acțiunea URL_UPDATED.
18. Rulează cron Magento:

bin/magento cron:run

19. Verifică Google Indexing API > Indexing Queue.
20. Verifică Google Indexing API > API Logs.
21. Dacă totul funcționează corect, dezactivează Dry Run.
22. Adaugă din nou un URL de test și verifică răspunsul real Google.

13. Importul URL-urilor din panoul administrativ

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 administrativ.

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,
• status,
• prioritate,
• 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ă

Atenție: 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ă sarcini cron în grupul default.

Procesarea cozii

kowal_google_indexing_process_queue

Program:

*/5 * * * *

Sarcina 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 zilnică ș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

Program:

15 3 * * *

Sarcina ș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,
• status HTTP,
• body-ul răspunsului,
• durata requestului,
• data creării logului.

Tipuri de requesturi:

17. Mass Actions și butoane administrative

Modulul adaugă mecanisme de trimitere a URL-urilor din panoul administrativ.

Produse

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

Modulul omite produsele:

• dezactivate,
• invizibile individual.

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

Pagini CMS

Pe 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 de solicitare a indexării pe ecranele de editare:

• produs,
• categorie,
• pagină 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 de producție:

19. Probleme frecvente și diagnosticare

Credentials test failed

Verifică:

• dacă JSON-ul este corect,
• dacă JSON-ul provine dintr-un cont de serviciu,
• dacă include private_key și client_email,
• dacă câmpul type are valoarea service_account,
• dacă fișierul JSON nu a fost deteriorat în timpul lipirii.

Google returnează o eroare de permisiuni

Verifică:

• 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ă folosești proiectul Google Cloud corect și JSON-ul corect.

URL-ul este respins înainte de trimitere

Verifică mesajul de validare:

Coada nu se procesează

Verifică:

• 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 utilizate,
• dacă Daily Publish Limit și Requests Per Minute Limit nu sunt setate la 0.

Înregistrările ajung în retry

Verifică:

• statusul HTTP în înregistrarea din coadă,
• 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 numai în proiectele care folosesc amasty/blog și au nevoie de acțiune în masă pentru articolele de blog.