Google Indexing API voor Magento 2 - installatie en configuratie

1. Belangrijke informatie vóór implementatie

De module integreert Magento 2 met Google Indexing API en maakt het mogelijk URL-adressen toe te voegen aan een centrale aanmeldingswachtrij. De wachtrij wordt verwerkt door Magento cron en elke aanmelding wordt gevalideerd, gededupliceerd, onder limieten geplaatst en gelogd.

Volgens de documentatie van Google is Indexing API officieel in de eerste plaats bedoeld voor pagina's met gestructureerde gegevens:

• JobPosting,
• BroadcastEvent ingebed in VideoObject.

Het gebruik van de API voor producten, categorieën, CMS-pagina's of blogartikelen garandeert geen indexatie of positie in de zoekresultaten. De module moet worden behandeld als een technisch hulpmiddel voor het aanmelden van URL's en niet als vervanging voor sitemap XML, correcte canonical-tags, robots, hreflang, interne linking en de algemene SEO-kwaliteit.

Officiële Google-materialen:

• 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. Vereisten

Controleer vóór de installatie of de omgeving aan de vereisten voldoet:

• Magento 2.4.x,
• PHP 8.1 of nieuwer,
• Composer,
• werkende Magento cron,
• mogelijkheid om het pakket google/apiclient te installeren,
• beheerderstoegang tot Magento,
• Google Cloud-project met ingeschakelde Indexing API,
• property in Google Search Console geverifieerd voor het domein van de webshop,
• Google-serviceaccount toegevoegd als eigenaar in Google Search Console.

De module vereist het pakket:

google/apiclient:^2.16

Het pakket is gedeclareerd in composer.json van de module, dus Composer zou het automatisch moeten installeren.

3. Installatie van de module

3.1. Installatie via Composer vanuit een VCS-repository

Als de module wordt geïnstalleerd vanuit een private of publieke Git-repository, voeg dan de repository toe aan het Magento-project:

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

Als de repository privé is, configureer dan een GitHub-token:

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

Installeer het pakket:

composer require kowal/module-google-indexing-api

Activeer de module:

bin/magento module:enable Kowal_GoogleIndexingApi

Voer de update van het databaseschema uit:

bin/magento setup:upgrade

Leeg de cache:

bin/magento cache:flush

Voer in productiemodus bovendien het volgende uit:

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

3.2. Lokale installatie in app/code

Als de module zonder Composer als lokale code wordt geïnstalleerd, plaats deze dan in de map:

app/code/Kowal/GoogleIndexingApi

Installeer vervolgens de afhankelijkheid Google API Client in het Magento-project:

composer require google/apiclient:^2.16

Activeer de module en voer de standaard Magento-commando's uit:

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

Voor productie:

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

3.3. Verificatie van de installatie

Controleer of de module actief is:

bin/magento module:status Kowal_GoogleIndexingApi

Na een correcte installatie moeten in het beheerpaneel beschikbaar zijn:

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

In de database moeten de volgende tabellen zijn aangemaakt:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Voorbereiding van Google Cloud en Search Console

4.1. Een Google Cloud-project aanmaken

1. Ga naar Google Cloud Console.
2. Maak een nieuw project aan of kies een bestaand project dat voor de webshop wordt gebruikt.
3. Schakel de API in:

Indexing API

Zonder ingeschakelde API kan de module aanmeldingen niet correct verzenden.

4.2. Een serviceaccount aanmaken

1. Ga in Google Cloud naar IAM & Admin > Service Accounts.
2. Maak een nieuw serviceaccount aan.
3. Genereer een sleutel in JSON-formaat.
4. Download het JSON-bestand en bewaar het veilig.

De module vereist dat de JSON ten minste de velden bevat:

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

Het veld type moet de waarde hebben:

service_account

4.3. Het serviceaccount als eigenaar toevoegen in Search Console

1. Open Google Search Console.
2. Selecteer de property die overeenkomt met het domein van de webshop.
3. Zorg ervoor dat de property is geverifieerd.
4. Voeg het adres client_email uit het JSON-bestand toe als eigenaar van de property.

Voorbeeld van een serviceaccountadres:

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

Als het serviceaccount geen eigenaar is van de Search Console-property, kan Google rechtenfouten retourneren, bijvoorbeeld een ontbrekende bevestiging van eigendom van de URL.

5. Configuratie van de module in Magento

De configuratie bevindt zich in:

Stores > Configuration > Kowal > Google Indexing API

De configuratie ondersteunt Magento-scopes:

• Default Config,
• Website,
• Store View.

Daardoor kunnen er aparte instellingen zijn voor verschillende winkels of store views, als het project dat vereist.

6. Sectie General

Enable

Standaard:

No

Schakelt de werking van de module in of uit.

Wanneer het veld de waarde No heeft, verwerkt cron de wachtrij niet. Adressen kunnen in de database bestaan, maar de wachtrijprocessor zal ze niet naar Google verzenden.

Aanbeveling:

• zet tijdens de eerste configuratie No of laat Dry Run = Yes staan,
• zet na succesvolle tests Yes.

Dry Run

Standaard:

Yes

Testmodus. Wanneer Dry Run is ingeschakeld, verwerkt de module wachtrijrecords, slaat statussen en logs op, maar verzendt geen echte aanmelding naar Google.

Dit is de veiligste modus voor de eerste start, configuratietests en controle of URL's zoals verwacht in de wachtrij terechtkomen.

Aanbeveling:

• voer de eerste tests altijd uit met Dry Run = Yes,
• schakel Dry Run pas uit na controle van credentials, allowed hosts, wachtrij en logs.

7. Sectie Google Access Credentials

Credentials Source

Standaard:

Encrypted configuration value

Bepaalt waar de module de JSON van het Google-serviceaccount vandaan haalt.

Beschikbare opties:

Aanbeveling:

• voor eenvoudige implementaties kan een versleutelde waarde in de configuratie worden gebruikt,
• voor omgevingen met toegangscontrole tot bestanden kan het uploaden van een JSON-bestand handiger zijn.

Service Account JSON

Zichtbaar wanneer Credentials Source = Encrypted configuration value.

In dit veld moet de volledige inhoud van het JSON-bestand van het Google-serviceaccount worden geplakt.

De module valideert de JSON vóór het opslaan. Gecontroleerd worden:

• correctheid van het JSON-formaat,
• aanwezigheid van de velden type, project_id, private_key, client_email,
• de waarde type = service_account.

De waarde wordt opgeslagen als versleutelde Magento-configuratie.

Service Account JSON File

Zichtbaar wanneer Credentials Source = Uploaded JSON file.

Maakt het mogelijk een JSON-bestand van het Google-serviceaccount te uploaden.

De module:

• accepteert alleen bestanden met de extensie .json,
• valideert de inhoud van het bestand,
• controleert de vereiste velden type, project_id, private_key, client_email,
• slaat het bestand buiten de publieke map op, in var/google-indexing,
• probeert bestandsrechten op 0600 te zetten, als de bestandsdriver dat toestaat.

Het bestand wordt opgeslagen met een naam die afhankelijk is van de configuratiescope, bijvoorbeeld voor de globale scope:

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

Google Cloud Project ID

Tekstveld voor de identificatie van het Google Cloud-project.

In de huidige implementatie van de module is de hoofdautorisatie gebaseerd op de gegevens uit de JSON van het serviceaccount. Het veld Google Cloud Project ID heeft een informatieve functie en helpt de configuratie te structureren, vooral wanneer de webshop meerdere omgevingen of meerdere Google Cloud-projecten gebruikt.

Aanbeveling:

• voer de waarde project_id uit het JSON-bestand in,
• gebruik aparte Google Cloud-projecten voor productie- en testomgevingen als die scheiding in het project wordt toegepast.

8. Sectie Queue and Limits

Daily Publish Limit

Standaard:

200

Bepaalt het maximale aantal publish-aanmeldingen dat de module per dag kan uitvoeren.

De limiter telt requests van het type:

• publish,
• publish_dry_run.

Als de limiet is verbruikt, haalt de wachtrijprocessor geen volgende records meer op om te verzenden tot het volgende dagelijkse venster.

Aanbeveling:

• laat 200 staan als het project gebruikmaakt van de standaard onboardinglimiet van Google,
• verhoog de waarde alleen wanneer het Google Cloud-project een goedgekeurde hogere limiet heeft,
• de instelling 0 blokkeert verzending, omdat het beschikbare aantal slots 0 zal zijn.

Requests Per Minute Limit

Standaard:

60

Bepaalt het maximale aantal publish-requests per minuut.

De module vergelijkt deze waarde met het aantal requests dat in de logs van de laatste minuut is opgeslagen. Als de minuutlimiet is bereikt, verwerkt cron in die run geen volgende records.

Aanbeveling:

• laat voor een typische implementatie de standaardwaarde staan,
• verlaag de waarde als u de API conservatiever wilt belasten,
• stel 0 niet in, tenzij u het verzenden tijdelijk wilt stoppen.

Cron Batch Size

Standaard:

20

Bepaalt het maximale aantal wachtrijrecords dat in één cron-run wordt verwerkt.

Het werkelijke aantal verwerkte records wordt ook beperkt door:

• Daily Publish Limit,
• Requests Per Minute Limit,
• het aantal records dat klaar is om te verzenden,
• de status en datum scheduled_at.

Aanbeveling:

• 20 is een veilige startwaarde,
• bij grote wachtrijen kan de waarde worden verhoogd, maar alleen rekening houdend met de limieten van Google.

Default Indexing Lag (minutes)

Standaard:

15

Bepaalt de standaardvertraging tussen het toevoegen van een URL aan de wachtrij en het moment waarop deze kan worden verzonden.

De vertraging helpt om:

• duplicaten te beperken,
• verzending na elke kleine wijziging te vermijden,
• de beheerder tijd te geven om content te corrigeren,
• de API-limiet beter te beheren.

In de huidige implementatie wordt deze instelling gebruikt wanneer de aanmelding geen eigen vertraging heeft.

Manual Form Indexing Lag (minutes)

Standaard:

15

Bepaalt de vertraging voor URL's die via het formulier zijn toegevoegd:

Google Indexing API > Import URLs

Als de beheerder handmatig een lijst met URL's plakt, wordt elk correct adres met deze vertraging ingepland.

Aanbeveling:

• stel 0 in als handmatige import direct in de wachtrij moet komen,
• laat 15 staan als u een buffer wilt behouden voor deduplicatie en controle van aanmeldingen.

Mass Action Indexing Lag (minutes)

Standaard:

15

Bepaalt de vertraging voor URL's die zijn toegevoegd via:

• mass actions voor producten,
• mass actions voor CMS-pagina's,
• knoppen voor indexatie-aanmelding op de bewerkingsschermen van product, categorie en CMS-pagina.

Aanbeveling:

• laat voor bulkbewerkingen de waarde 15 of hoger staan,
• voor kleine winkels en handmatig beheer kan een lagere waarde worden overwogen.

Max Attempts

Standaard:

5

Bepaalt het maximale aantal verzendpogingen voor één wachtrijrecord.

Als Google een tijdelijke fout retourneert, zet de module de status op retry, zolang het aantal pogingen lager is dan Max Attempts. Na overschrijding van de limiet krijgt het record de status failed_permanent.

Fouten die als tijdelijk worden behandeld:

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

Retry Delay (minutes)

Standaard:

15

Basisvertraging vóór de volgende verzendpoging na een tijdelijke fout.

Cron gebruikt een oplopende vertraging. De vermenigvuldigingsfactor hangt af van het aantal pogingen en is maximaal begrensd op 24. Daardoor worden volgende pogingen niet te agressief uitgevoerd.

Voorbeeld voor de waarde 15:

Allowed Source Types

Standaard:

manual,product,category,cms_page,amasty_blog_post

Lijst met toegestane brontypen, gescheiden door komma's.

Ondersteunde waarden:

Als een brontype niet in de lijst staat, slaat de scheduler de aanmelding over en markeert deze als skipped.

Aanbeveling:

• laat de standaardwaarden staan als de webshop alle standaardbronnen gebruikt,
• verwijder bronnen die u niet in de wachtrij wilt toelaten.

Allowed URL Hosts

Standaard:

leeg

Lijst met toegestane URL-hosts, gescheiden door komma's.

Voorbeeld:

example.com,www.example.com

Als de lijst is ingevuld, accepteert de module alleen adressen die tot de opgegeven hosts behoren. Als een URL een andere host heeft, retourneert de validatie de fout:

host_not_allowed

Aanbeveling:

• vul deze lijst in productie altijd in,
• voeg alle hosts toe die door de webshop worden gebruikt, bijvoorbeeld het hoofddomein, de www-versie, store view-domeinen en taaldomeinen,
• voeg geen testdomeinen toe aan de productieconfiguratie.

Require HTTPS URLs

Standaard:

Yes

Forceert dat aangemelde URL-adressen het schema https gebruiken.

Als dit veld is ingeschakeld, wordt een adres met http afgewezen met de fout:

https_required

Aanbeveling:

• laat voor productiewebshops Yes staan,
• gebruik No alleen in uitzonderlijke testomgevingen.

9. Sectie Auto-Indexing

Enable Auto-Indexing

Standaard:

No

Dit veld is voorbereid voor automatische integraties voor het opslaan of verwijderen van entiteiten en aanvullende URL-providers.

In de huidige scope van de module zijn handmatige en administratieve mechanismen beschikbaar om URL's aan de wachtrij toe te voegen, waaronder URL-import, Mass Actions en knoppen op bewerkingsformulieren.

Aanbeveling:

• laat No staan als auto-indexing niet in het project is geïmplementeerd,
• schakel dit pas in wanneer het project ondersteuning bevat voor automatische entiteitsgebeurtenissen die deze configuratie gebruiken.

10. Sectie Logs

API Log Retention Days

Standaard:

90

Bepaalt het aantal dagen dat API-logs worden bewaard.

De cron die logs opschoont, draait dagelijks om:

03:15

Hij verwijdert items die ouder zijn dan het aantal dagen dat in dit veld is ingesteld.

Aanbeveling:

• 90 dagen is een redelijke waarde voor diagnose,
• bij een groot aantal requests kan de retentie worden verlaagd,
• bij SEO-audits kan de retentie worden verhoogd, rekening houdend met de grootte van de logtabel.

11. Installatie- en configuratieassistent

De assistent bevindt zich in:

Google Indexing API > Setup Assistant

Het doel ervan is om snel te controleren of de configuratie aan de Magento- en Google-zijde klaar is voor de eerste test.

11.1. Sectie Current Status

De assistent toont de huidige status van de belangrijkste elementen:

Als Credentials de status Missing or invalid heeft, moet u teruggaan naar de configuratie en de JSON of het credentials-bestand corrigeren.

Als Allowed Hosts Not configured toont, beperkt de module geen hosts. Technisch kan dit werken, maar voor productie wordt aanbevolen de hosts van de webshop expliciet in te vullen.

11.2. Sectie Setup Steps

De assistent toont een lijst met stappen die nodig zijn vóór de eerste echte request:

1. Een Google Cloud-project aanmaken of kiezen.
2. Indexing API inschakelen en een JSON key voor het serviceaccount aanmaken.
3. De JSON plakken of het JSON-bestand uploaden in de Magento-configuratie.
4. Het service account email toevoegen als eigenaar in Google Search Console.
5. Tests uitvoeren en vervolgens één URL importeren met Dry Run ingeschakeld.

De assistent bevat links naar:

• Google Cloud voor Indexing API,
• moduleconfiguratie in Magento,
• Google Search Console.

11.3. Test Google Credentials

De knop:

Test Google Credentials

controleert of Magento de gegevens van het serviceaccount kan gebruiken om een OAuth-token te verkrijgen voor de scope:

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

Een positief resultaat betekent dat:

• de JSON correct is,
• de private key kan worden gebruikt,
• Google een OAuth-token heeft uitgegeven.

Een negatief resultaat kan betekenen:

• onjuiste JSON,
• onjuiste of beschadigde private_key,
• ontbrekend vereist veld in de JSON,
• probleem met communicatie met Google,
• gebruik van een sleutel die geen serviceaccountsleutel is.

Deze test bevestigt nog niet dat het serviceaccount eigenaarsrechten heeft voor het domein in Search Console. Daarvoor is een URL metadata-test of een echte aanmelding van een test-URL nodig.

11.4. Test URL Metadata

Het formulier:

Test URL Metadata

maakt het mogelijk een publieke URL van een toegestane host in te voeren en een metadata-request uit te voeren naar Google Indexing API.

Vóór het verzenden van de request doet de module het volgende:

• normaliseert de URL,
• controleert of de URL absoluut is,
• controleert het schema http of https,
• vereist bij ingeschakelde Require HTTPS URLs het schema https,
• controleert Allowed URL Hosts als deze zijn geconfigureerd.

Mogelijke resultaten:

De metadata-test maakt geen nieuwe publish-aanmelding aan. Deze dient voor diagnose van de verbinding en de status van de URL.

12. Eerste start stap voor stap

Aanbevolen volgorde voor de eerste start:

1. Installeer de module en voer setup:upgrade uit.
2. Ga in Magento naar Stores > Configuration > Kowal > Google Indexing API.
3. Zet Enable = Yes.
4. Laat Dry Run = Yes staan.
5. Kies de bron van de credentials.
6. Plak de JSON van het serviceaccount of upload het JSON-bestand.
7. Vul Google Cloud Project ID in met de waarde project_id uit de JSON.
8. Vul Allowed URL Hosts in, bijvoorbeeld example.com,www.example.com.
9. Laat de standaardlimieten staan als Google geen hogere limieten heeft goedgekeurd.
10. Sla de configuratie op en leeg de cache.
11. Ga naar Google Indexing API > Setup Assistant.
12. Controleer of de assistent de credentials als gereed toont.
13. Klik op Test Google Credentials.
14. Voeg het service account email toe als eigenaar in Google Search Console, als dit nog niet is gebeurd.
15. Voer Test URL Metadata uit voor een publieke URL van een toegestane host.
16. Ga naar Google Indexing API > Import URLs.
17. Voeg één test-URL toe met de actie URL_UPDATED.
18. Start Magento cron:

bin/magento cron:run

19. Controleer Google Indexing API > Indexing Queue.
20. Controleer Google Indexing API > API Logs.
21. Als alles correct werkt, schakel dan Dry Run uit.
22. Voeg opnieuw één test-URL toe en controleer de echte reactie van Google.

13. URL-import vanuit het beheerpaneel

Handmatige import bevindt zich in:

Google Indexing API > Import URLs

Het formulier bevat de velden:

Beschikbare acties:

Na het verzenden van het formulier toont de module een samenvatting:

• toegevoegd,
• bijgewerkt,
• gededupliceerd,
• ongeldig,
• overgeslagen.

De eerste 10 validatiemeldingen worden als notice in het beheerpaneel getoond.

14. Indexatiewachtrij

De wachtrij bevindt zich in:

Google Indexing API > Indexing Queue

Elk wachtrijrecord bevat onder andere:

• URL,
• URL-hash,
• store ID,
• website ID,
• brontype,
• ID van de bronentiteit,
• herkomst van de request,
• actie URL_UPDATED of URL_DELETED,
• status,
• prioriteit,
• aantal pogingen,
• maximaal aantal pogingen,
• geplande verzenddatum,
• verwerkingsdatum,
• laatste foutcode,
• laatste foutreden,
• laatste foutmelding,
• reactie van Google,
• informatie created_by.

Wachtrijstatussen

Acties op wachtrijrecords

Let op: Transmit Now voert een echte request uit als Dry Run = No. Bij Dry Run = Yes wordt een dry-run-log opgeslagen zonder echte verzending naar Google.

15. Cron

De module voegt twee cron-taken toe in de groep default.

Verwerking van de wachtrij

kowal_google_indexing_process_queue

Schema:

*/5 * * * *

De taak start de wachtrijprocessor elke 5 minuten.

De processor:

1. Controleert of de module is ingeschakeld.
2. Geeft oude locks vrij van processing-records ouder dan 30 minuten.
3. Verplaatst scheduled-records naar pending als scheduled_at <= now.
4. Controleert beschikbare slots binnen de dag- en minuutlimieten.
5. Haalt pending- en retry-records op.
6. Sorteert ze op prioriteit en geplande verzenddatum.
7. Verzendt een request naar Google of voert dry-run uit.
8. Slaat reactie, status en API-log op.

Logs opschonen

kowal_google_indexing_cleanup_logs

Schema:

15 3 * * *

De taak verwijdert API-logs die ouder zijn dan het aantal dagen ingesteld in het veld:

API Log Retention Days

16. API-logs

De logs zijn beschikbaar in:

Google Indexing API > API Logs

Een log bevat:

• ID van het wachtrijrecord,
• store ID,
• requesttype,
• endpoint-URL,
• payload,
• HTTP-status,
• response body,
• duur van de request,
• aanmaakdatum van de log.

Requesttypen:

17. Mass Actions en beheerdersknoppen

De module voegt mechanismen toe om URL's aan te melden vanuit het beheerpaneel.

Producten

Op het productgrid is een mass action beschikbaar die product-URL's aan de wachtrij toevoegt.

De module slaat producten over die:

• uitgeschakeld zijn,
• niet individueel zichtbaar zijn.

URL's worden gegenereerd op basis van URL rewrites voor actieve store views.

CMS-pagina's

Op het grid van CMS-pagina's is een mass action beschikbaar die pagina-URL's aan de wachtrij toevoegt.

De module slaat inactieve pagina's over.

Als een CMS-pagina aan alle store views is toegewezen, lost de module URL's op voor alle store views.

Product, categorie en CMS-pagina - knoppen op het bewerkingsformulier

De module voegt knoppen toe voor indexatie-aanmelding op de bewerkingsschermen van:

• product,
• categorie,
• CMS-pagina.

De knop lost de URL's van de entiteit op voor de store view en voegt ze aan de wachtrij toe als URL_UPDATED.

18. Aanbevolen startconfiguratie

Voor de eerste productie-implementatie:

19. Veelvoorkomende problemen en diagnose

Credentials test failed

Controleer:

• of de JSON correct is,
• of de JSON van een serviceaccount afkomstig is,
• of deze private_key en client_email bevat,
• of het veld type de waarde service_account heeft,
• of het JSON-bestand niet is beschadigd tijdens het plakken.

Google retourneert een rechtenfout

Controleer:

• of het domein is geverifieerd in Search Console,
• of de client_email van het serviceaccount als eigenaar is toegevoegd,
• of de geteste URL tot dezelfde Search Console-property behoort,
• of u het juiste Google Cloud-project en de juiste JSON gebruikt.

URL wordt afgewezen vóór verzending

Controleer het validatiebericht:

De wachtrij wordt niet verwerkt

Controleer:

• of Enable = Yes,
• of Magento cron werkt,
• of records de status pending of retry hebben,
• of scheduled_at niet in de toekomst ligt,
• of dag- of minuutlimieten niet zijn verbruikt,
• of Daily Publish Limit en Requests Per Minute Limit niet op 0 staan.

Records gaan naar retry

Controleer:

• de HTTP-status in het wachtrijrecord,
• de API-log,
• de reactie van Google,
• of er geen 429-limiet optreedt,
• of er geen tijdelijke 5xx-fouten zijn,
• of Max Attempts en Retry Delay volgens verwachting zijn ingesteld.

20. Optionele integratie met Amasty Blog

Integratie met Amasty Blog is voorzien als aparte module:

Kowal_GoogleIndexingApiAmastyBlog

Pakket:

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

Deze module is niet vereist voor de werking van de hoofdintegratie. Installeer deze alleen in projecten die amasty/blog gebruiken en een mass action voor blogartikelen nodig hebben.