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 meldingswachtrij. De wachtrij wordt verwerkt door Magento cron en elke melding wordt gevalideerd, gededupliceerd, aan limieten onderworpen en gelogd.

Volgens de documentatie van Google is Indexing API officieel vooral bedoeld voor pagina's met structured data:

• JobPosting,
• BroadcastEvent ingebed in VideoObject.

Gebruik van de API voor producten, categorieën, CMS-pagina's of blogberichten garandeert geen indexatie of positie in zoekresultaten. De module moet worden gezien als technisch hulpmiddel voor het melden van URL's, niet als vervanging voor XML-sitemaps, correcte canonicals, robots, hreflang, interne linking en 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 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 winkeldomein,
• Google-serviceaccount toegevoegd als eigenaar in Google Search Console.

De module vereist het pakket:

google/apiclient:^2.16

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

3. Installatie van de module

3.1. Installatie via Composer

Voeg de Kowal Composer-repository toe aan het Magento-project:

Toegangsgegevens voor de Composer-repository, het e-mailadres van de klant en de licentietoken, ontvangt u per e-mail na aankoop. Ze zijn ook beschikbaar in het klantpaneel na inloggen op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door de ontvangen token. Voer de opdrachten uit in de hoofdmap van Magento.

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

Configureer de toegangsgegevens voor de Kowal Composer-repository:

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

Installeer het pakket:

composer require kowal/module-google-indexing-api

Schakel de module in:

bin/magento module:enable Kowal_GoogleIndexingApi

Voer de databaseschema-update uit:

bin/magento setup:upgrade

Leeg de cache:

bin/magento cache:flush

Voer in productiemodus aanvullend 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 Google API Client-afhankelijkheid in het Magento-project:

composer require google/apiclient:^2.16

Schakel de module in 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 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 tabellen worden aangemaakt:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Google Cloud en Search Console voorbereiden

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 winkel wordt gebruikt.
3. Schakel de API in:

Indexing API

Zonder ingeschakelde API kan de module meldingen 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 JSON minimaal de volgende 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. Kies de property die overeenkomt met het winkeldomein.
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 van de Search Console-property is, kan Google rechtenfouten retourneren, bijvoorbeeld geen bevestiging van URL-eigendom.

5. Moduleconfiguratie 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 afzonderlijke 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 verzendt ze niet naar Google.

Aanbeveling:

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

Dry Run

Standaard:

Yes

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

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

Aanbeveling:

• voer 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 waaruit de module de JSON van het Google-serviceaccount haalt.

Beschikbare opties:

Aanbeveling:

• voor eenvoudige implementaties kan de versleutelde waarde in de configuratie worden gebruikt,
• voor omgevingen met toegangscontrole tot bestanden kan upload 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 JSON vóór opslag. Gecontroleerd worden:

• correctheid van het JSON-formaat,
• aanwezigheid van velden type, project_id, private_key, client_email,
• 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 het 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 identifier van het Google Cloud-project.

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

Aanbeveling:

• voer de waarde project_id uit het JSON-bestand in,
• gebruik afzonderlijke Google Cloud-projecten voor productie- en testomgevingen als een dergelijke scheiding in het project is aangenomen.

8. Sectie Queue and Limits

Daily Publish Limit

Standaard:

200

Bepaalt het maximale aantal publish-meldingen 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 op voor verzending tot het volgende dagelijkse venster.

Aanbeveling:

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

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 gebruikt, verwerkt cron geen volgende records in die run.

Aanbeveling:

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

Cron Batch Size

Standaard:

20

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

Het daadwerkelijke aantal verwerkte records wordt ook beperkt door:

• Daily Publish Limit,
• Requests Per Minute Limit,
• aantal records dat klaar is voor verzending,
• status en datum scheduled_at.

Aanbeveling:

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

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 voorkomen,
• de beheerder tijd te geven voor correctie van content,
• de API-limiet beter te beheren.

In de huidige implementatie wordt deze instelling gebruikt wanneer een melding 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 URL's plakt, wordt elk correct adres met deze vertraging gepland.

Aanbeveling:

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

Mass Action Indexing Lag (minutes)

Standaard:

15

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

• bulkacties voor producten,
• bulkacties voor CMS-pagina's,
• knoppen voor het melden van indexatie op bewerkingsschermen van product, categorie en CMS-pagina.

Aanbeveling:

• laat voor bulkoperaties 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, stelt de module status retry in, mits het aantal pogingen kleiner is dan Max Attempts. Na overschrijding van de limiet krijgt het record 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 oplopende vertraging. De vermenigvuldiger hangt af van het aantal pogingen en is maximaal beperkt tot 24. Daardoor worden volgende pogingen niet te agressief uitgevoerd.

Voorbeeld voor 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 het brontype niet op de lijst staat, slaat de scheduler de melding over en markeert deze als skipped.

Aanbeveling:

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

Allowed URL Hosts

Standaard:

puste

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 de URL een andere host heeft, retourneert validatie de fout:

host_not_allowed

Aanbeveling:

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

Require HTTPS URLs

Standaard:

Yes

Dwingt af dat gemelde URL-adressen het schema https gebruiken.

Als het veld is ingeschakeld, wordt een adres met http geweigerd met de fout:

https_required

Aanbeveling:

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

9. Sectie Auto-Indexing

Enable Auto-Indexing

Standaard:

No

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

Binnen het huidige bereik 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 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

Deze verwijdert vermeldingen ouder dan het aantal dagen dat in dit veld is ingesteld.

Aanbeveling:

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

11. Installatie- en configuratieassistent

De assistent bevindt zich in:

Google Indexing API > Setup Assistant

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

11.1. Sectie Current Status

De assistent toont de huidige status van de belangrijkste onderdelen:

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

Als Allowed Hosts Not configured toont, beperkt de module hosts niet. Technisch kan dit werken, maar voor productie wordt expliciet invullen van winkelhosts aanbevolen.

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. JSON plakken of het JSON-bestand uploaden in de Magento-configuratie.
4. Service account email toevoegen als eigenaar in Google Search Console.
5. Tests uitvoeren en daarna één URL importeren met ingeschakelde Dry Run.

De assistent bevat links naar:

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

11.3. Test Google Credentials

Knop:

Test Google Credentials

controleert of Magento de serviceaccountgegevens kan gebruiken om een OAuth-token te verkrijgen voor het bereik:

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

Een positief resultaat betekent dat:

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

Een negatief resultaat kan betekenen:

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

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

11.4. Test URL Metadata

Formulier:

Test URL Metadata

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

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

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

Mogelijke resultaten:

Metadata test maakt geen nieuwe publish-melding. Deze dient voor diagnostiek van verbinding en URL-status.

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. Stel Enable = Yes in.
4. Laat Dry Run = Yes staan.
5. Kies de credentials-bron.
6. Plak de JSON van het serviceaccount of upload het JSON-bestand.
7. Vul Google Cloud Project ID met de waarde project_id uit JSON.
8. Vul Allowed URL Hosts in, bijvoorbeeld example.com,www.example.com.
9. Laat 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 credentials als gereed toont.
13. Klik op Test Google Credentials.
14. Voeg service account email toe als eigenaar in Google Search Console als dit nog niet is gedaan.
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 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 Dry Run uit.
22. Voeg opnieuw één test-URL toe en controleer het echte antwoord van Google.

13. URL's importeren vanuit het beheerpaneel

Handmatige import bevindt zich in:

Google Indexing API > Import URLs

Het formulier bevat velden:

Beschikbare acties:

Na verzending 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 meer:

• URL,
• URL-hash,
• store ID,
• website ID,
• brontype,
• ID van bronentiteit,
• herkomst van de request,
• actie URL_UPDATED of URL_DELETED,
• status,
• prioriteit,
• aantal pogingen,
• maximaal aantal pogingen,
• datum van geplande verzending,
• verwerkingsdatum,
• laatste foutcode,
• laatste foutreden,
• laatste foutmelding,
• Google-antwoord,
• 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 groep default.

Wachtrij verwerken

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 records scheduled naar pending als scheduled_at <= now.
4. Controleert beschikbare slots in dag- en minuutlimieten.
5. Haalt records pending en retry op.
6. Sorteert ze op prioriteit en geplande verzenddatum.
7. Verzendt de request naar Google of voert dry-run uit.
8. Slaat antwoord, status en API-log op.

Logs opschonen

kowal_google_indexing_cleanup_logs

Schema:

15 3 * * *

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

API Log Retention Days

16. API-logs

Logs zijn beschikbaar in:

Google Indexing API > API Logs

De log omvat:

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

Requesttypen:

17. Mass Actions en beheerknoppen

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

Producten

Op het productgrid is een bulkactie 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 bulkactie 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 voor indexatiemeldingen toe op bewerkingsschermen van:

• product,
• categorie,
• CMS-pagina.

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

18. Aanbevolen startconfiguratie

Voor de eerste productie-implementatie:

19. Veelvoorkomende problemen en diagnostiek

Credentials test failed

Controleer:

• of JSON correct is,
• of JSON afkomstig is van een serviceaccount,
• of het private_key en client_email bevat,
• of 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 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 geweigerd vóór verzending

Controleer de validatiemelding:

De wachtrij wordt niet verwerkt

Controleer:

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

Records gaan naar retry

Controleer:

• HTTP-status in het wachtrijrecord,
• API-log,
• Google-antwoord,
• of limiet 429 voorkomt,
• of er tijdelijke fouten 5xx 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 bulkactie voor blogberichten nodig hebben.