DataFirefly Indexing API: volledige gids

Overzicht

DataFirefly Indexing API dient de producten, categorieën en CMS-pagina’s van uw PrestaShop-winkel automatisch in bij de twee bestaande kanalen voor directe indiening: IndexNow via het relais api.indexnow.org, dat in één aanroep doorstuurt naar Bing, Yandex, Naver en Seznam, en Google Indexing API (Service Account OAuth2-authenticatie, native JWT RS256-ondertekening). De module haakt in op de native PrestaShop-hooks, plaatst elke wijziging in een gededupliceerde wachtrij, en een CRON verwerkt de batch om de paar minuten. U behoudt een volledig logboek van de indieningen en een dashboard met het acceptatiepercentage.

Vereisten

• PrestaShop 8.0 tot 8.99, of PrestaShop 9.x
• PHP 7.4 tot 8.3
• PHP-extensies openssl (voor de JWT RS256-ondertekening van Google) en curl (voor de HTTP-requests)
• Een systeem-CRON of externe CRON-dienst om de wachtrijverwerking elke 5 tot 15 minuten aan te roepen
• Optioneel, voor Google: een Google Cloud-account met een project waarin u de Indexing API activeert en een Service Account aanmaakt, en een geverifieerde Search Console-property voor uw domein

Installatie

Stap 1: downloaden

Download de ZIP dfindexingapi-1.0.0.zip vanuit uw DataFirefly-account na aankoop.

Stap 2: installatie via de backoffice

1. Log in op uw PrestaShop-backoffice
2. Ga naar Modules › Modulebeheer › Een module installeren
3. Klik op Een bestand selecteren en kies de gedownloade ZIP
4. Bevestig. PrestaShop pakt de module uit en installeert hem
5. Klik na de installatie op Configureren

Stap 3: controles na de installatie

Bij de installatie maakt de module automatisch aan:

• De twee SQL-tabellen ps_df_indexapi_queue (wachtrij) en ps_df_indexapi_log (logboek)
• Een alfanumerieke IndexNow-sleutel van 32 tekens
• Een willekeurig CRON-token van 32 tekens
• 5 tabbladen in het beheermenu: hoofdmenu DataFirefly Indexing API, daarna Dashboard, Wachtrij, Logboek, Configuratie

Open het tabblad Configuratie voor de volgende stap.

Configuratie van IndexNow

IndexNow is het kanaal om als eerste te configureren: geen Service Account, geen OAuth, geen quotum, en geen enkele beperking op het paginatype. Alleen een sleutel die u in de root van uw domein publiceert.

IndexNow begrijpen

IndexNow is een open protocol dat in 2021 door Microsoft Bing en Yandex is gelanceerd en waar Naver en Seznam zich sindsdien bij hebben aangesloten. U genereert een alfanumerieke sleutel, publiceert die in de root van uw domein als een publiek toegankelijk bestand, en roept api.indexnow.org aan met een lijst URL’s. De server verifieert de sleutel door het bestand op uw domein te lezen en stuurt de URL’s daarna door naar de deelnemende zoekmachines. Productpagina’s, categorieën en CMS-pagina’s vallen binnen zijn normale bereik.

Methode 1: .htaccess-herschrijving (aanbevolen)

Dit is de eenvoudigste methode: de module serveert zelf de inhoud van het sleutelbestand via een frontend-controller, en een .htaccess-regel in de root van uw winkel herschrijft de request naar die controller.

1. Open in de configuratie van de module het tabblad IndexNow
2. Vink IndexNow inschakelen aan
3. Controleer het veld Host, dat moet overeenkomen met het domein van uw winkel zonder het protocol (bijvoorbeeld mijn-winkel.nl)
4. Sla op
5. Kopieer de .htaccess-snippet die op de configuratiepagina wordt getoond, dynamisch gegenereerd met uw huidige sleutel
6. Plak deze snippet bovenaan het .htaccess-bestand in de root van PrestaShop, direct na het blok RewriteEngine on
7. Klik op IndexNow testen in de configuratie: de module roept de URL van het sleutelbestand op uw domein aan en controleert of die de verwachte inhoud als text/plain teruggeeft

Methode 2: fysiek bestand

Kunt u het .htaccess-bestand niet aanpassen, maak dan handmatig een fysiek bestand in de root van het domein aan.

1. Haal uw IndexNow-sleutel op uit de configuratie van de module (veld IndexNow-sleutel)
2. Maak een bestand aan waarvan de naam exact de sleutel + .txt is (bijvoorbeeld a1b2c3d4e5f6.txt) in de root van uw domein
3. De inhoud van het bestand moet uitsluitend de sleutel zelf zijn, zonder regeleinde
4. Controleer of https://uw-domein.com/a1b2c3d4e5f6.txt de sleutel als text/plain teruggeeft
5. Klik op IndexNow testen

Configuratie van de Google Indexing API

De Google Indexing API vereist een Google Cloud Service Account. De procedure duurt ongeveer 5 minuten.

Stap 1: een Google Cloud-project aanmaken

1. Ga naar console.cloud.google.com en log in
2. Klik bovenaan op de projectselector en daarna op Nieuw project
3. Geef het een naam (bijvoorbeeld Indexing API Winkel) en maak het aan
4. Selecteer het zojuist aangemaakte project

Stap 2: de Indexing API activeren

1. Ga in het linkermenu naar API’s en services › Bibliotheek
2. Zoek naar Indexing API
3. Klik op Inschakelen

Stap 3: een Service Account aanmaken

1. Ga naar API’s en services › Inloggegevens
2. Klik op Inloggegevens maken › Serviceaccount
3. Geef het een naam (bijvoorbeeld indexing-api-prestashop)
4. Er is geen enkele IAM-rol nodig: ga naar de volgende stap en rond de aanmaak af
5. Klik in de lijst met serviceaccounts op het aangemaakte account
6. Tabblad Sleutels › Sleutel toevoegen › Nieuwe sleutel maken
7. Formaat JSON. Download en bewaar het bestand, het kan daarna niet meer worden opgehaald

Stap 4: het Service Account toevoegen aan Search Console

1. Kopieer het e-mailadres van het Service Account (vorm naam@project.iam.gserviceaccount.com) vanuit Google Cloud
2. Ga naar Google Search Console
3. Selecteer uw property (het domein van uw winkel)
4. Ga naar Instellingen › Gebruikers en machtigingen
5. Klik op Gebruiker toevoegen, plak het e-mailadres van het Service Account en selecteer de rol Eigenaar
6. Bevestig

Stap 5: de JSON in de module plakken

1. Open het gedownloade JSON-bestand in een teksteditor
2. Kopieer de volledige inhoud
3. Vink in de configuratie van de module, sectie Google Indexing API, Google Indexing API inschakelen aan
4. Plak de volledige JSON in het veld Service Account JSON
5. Sla op

Stap 6: de verbinding testen

Klik op de knop Google testen op de configuratiepagina. De module ondertekent een JWT RS256, wisselt die in voor een OAuth2-token en toont het resultaat. Is alles correct, dan ziet u een groene melding Authenticatie OK. Deze test valideert de authenticatie, niet de verwerking van uw URL’s door Google.

Configuratie van de CRON

De CRON is het element dat de wachtrijverwerking draaiende houdt. Zonder regelmatig aangeroepen CRON stapelen de indieningen zich op, maar vertrekken ze nooit.

Actie process: verwerking van de wachtrij

Aan te roepen elke 5 tot 15 minuten. De module verwerkt een instelbare batch (standaard 50 jobs) met inachtneming van de deduplicatie en de indexeringsfilters, en werkt daarna het logboek en de wachtrij bij.

De exacte URL wordt in de configuratie getoond. Ze ziet er zo uit:

https://uw-domein.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=UW_TOKEN

Actie purge: opschoning van het logboek

Aan te roepen één keer per dag. De module verwijdert de verwerkte jobs en logs die ouder zijn dan de geconfigureerde bewaartermijn (standaard 30 dagen).

https://uw-domein.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=UW_TOKEN

Actie key: IndexNow-sleutelbestand

Alleen gebruikt door de .htaccess-herschrijving. Deze URL roept u nooit handmatig aan.

Uw systeem-CRON instellen

Voeg onder Linux/cPanel twee regels toe aan de crontab:

# Elke 10 minuten: verwerking van de wachtrij
*/10 * * * * curl -s "https://uw-domein.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=UW_TOKEN" > /dev/null

# Eén keer per dag om 3 uur: opschoning van het logboek
0 3 * * * curl -s "https://uw-domein.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=UW_TOKEN" > /dev/null

Beveiliging van het CRON-token

Het token is een geheim van 32 tekens dat bij de installatie wordt gegenereerd. Zonder het juiste token in de parameter token= geeft de controller HTTP 403 terug. U kunt het token op elk moment opnieuw genereren vanuit de configuratie (knop CRON-token opnieuw genereren); werk dan wel uw crontab-regels bij met het nieuwe token.

Het Dashboard

Het tabblad Dashboard is uw realtimeoverzicht. Het meet de technische gezondheid van de API-aanroepen, niet de daadwerkelijke indexering van uw pagina’s.

Wachtrijtellers

Vijf kaarten bovenaan de pagina:

• In afwachting: aangemaakte maar nog niet verwerkte jobs
• In verwerking: jobs vergrendeld door een actieve CRON
• Ingediend: met succes verwerkte jobs (historisch cumulatief, niet opgeschoond)
• Fout: jobs die na N maximale pogingen zijn mislukt
• Genegeerd: aangemaakte maar door een filter genegeerde jobs (bijvoorbeeld URL_DELETED bij IndexNow)

Diagnose van de providers

Twee kaarten tonen de configuratiestatus:

• Google Indexing API: actief, verkeerd geconfigureerd of uitgeschakeld. Geeft aan of de Service Account-JSON aanwezig en geldig is
• IndexNow: actief, verkeerd geconfigureerd of uitgeschakeld. Geeft aan of de sleutel en de host zijn geconfigureerd

Acceptatiepercentage over 30 dagen

Kruistabel provider × status over de laatste 30 dagen, met semantische kleuren: groen boven 90%, oranje tussen 60 en 90%, rood eronder. Zakt Google onder de 90%, dan is dat doorgaans een teken dat u het quotum hebt overschreden of dat URL’s niet meer bereikbaar zijn. Een acceptatiepercentage van 100% betekent dat uw meldingen zijn ontvangen, niet dat de URL’s zijn geïndexeerd.

Grafiek van de dagelijkse indieningen

Chart.js-grafiek met twee curven per dag: totaal ingediend en totaal geaccepteerd. Handig om dalingen of abnormale pieken snel op te sporen.

De Wachtrij

Het tabblad Wachtrij toont alle jobs (pending, processing, submitted, error, skipped) met native PrestaShop-filters op winkel, objecttype, ID, provider, status en datum.

Jobstatussen

• pending: aangemaakt, in afwachting van verwerking door de volgende CRON
• processing: vergrendeld door een actieve CRON (logische overgang om parallelle dubbele verwerking te vermijden)
• submitted: indiening bij de API geslaagd. De pogingenteller wordt bevroren
• error: alle pogingen zijn mislukt. Blijft raadpleegbaar met de exacte foutmelding die de API teruggaf
• skipped: aangemaakt en daarna genegeerd (bijvoorbeeld URL_DELETED bij IndexNow, of uitgeschakeld filter)

Individuele acties

Elke regel biedt:

• Opnieuw proberen: zet de job terug op pending en reset de pogingenteller
• Verwijderen: wist de job uit de wachtrij

Bulkacties

Knoppen bovenaan de lijst:

• Alle mislukte jobs opnieuw proberen: zet alle jobs met status error terug op pending
• Verwerkte jobs opschonen: verwijdert alle submitted/skipped, ongeacht hun leeftijd

Het Logboek

Het tabblad Logboek toont elke individuele indiening: provider, type, object-ID, ingediende URL, actie (URL_UPDATED of URL_DELETED), teruggegeven HTTP-code, indicator geaccepteerd/geweigerd, volledig antwoordbericht en datum. Filterbaar, sorteerbaar en exporteerbaar naar CSV via de standaard PrestaShop HelperList.

Indexeringsfilters

In de configuratie kunt u drie objecttypen onafhankelijk in- of uitschakelen:

• Producten: indiening bij aanmaak, wijziging, verwijdering, deactivering
• Categorieën: indiening bij aanmaak, wijziging, verwijdering. De categorieroot (ID 1 en 2) wordt uit voorzorg genegeerd
• CMS-pagina’s: indiening bij aanmaak, wijziging, verwijdering

Een filter uitschakelen stopt onmiddellijk het in de wachtrij plaatsen voor dat type, maar schoont de bestaande wachtrij niet op. Op een grote catalogus is het beperken van de filters aan Google-zijde de juiste reflex om het quotum van 200 URL’s per dag niet uit te putten.

Multistore

De module is native multistore. De configuratie (Google-sleutels, IndexNow-sleutel, host, activeringen) is per subwinkel onafhankelijk. De jobs en logs zijn gescoped per id_shop: eenzelfde product in twee subwinkels genereert twee aparte jobs met hun eigen canonieke URL’s.

Om elke subwinkel onafhankelijk te configureren, gebruikt u de multistore-selector bovenaan de admin voordat u de configuratie opent.

Beluisterde PrestaShop-hooks

De module registreert bij de installatie de volgende hooks:

• actionProductSave: aanmaak of wijziging van een product. Indien actief wordt URL_UPDATED in de wachtrij geplaatst; anders URL_DELETED
• actionProductDelete: definitieve verwijdering van een product. Plaatst URL_DELETED in de wachtrij
• actionObjectCmsAddAfter: aanmaak van een CMS-pagina
• actionObjectCmsUpdateAfter: wijziging van een CMS-pagina
• actionObjectCmsDeleteAfter: verwijdering van een CMS-pagina
• actionCategoryAdd: aanmaak van een categorie
• actionCategoryUpdate: wijziging van een categorie
• actionCategoryDelete: verwijdering van een categorie
• displayBackOfficeHeader: injectie van een CSS-fragment voor de styling van het dashboard

Elke hook bouwt de canonieke URL via het officiële Link-object van PrestaShop, wat uw SEO friendly URL-voorkeuren en de meertalige taalprefixen respecteert.

Probleemoplossing

De Google-test mislukt met code 401

De authenticatie is mislukt. Controleer of:

• De geplakte Service Account-JSON volledig en correct gevormd is
• De Indexing API daadwerkelijk is ingeschakeld in Google Cloud (bibliotheek)
• De systeemklok van de server correct is: een afwijking van meer dan 5 minuten maakt de JWT ongeldig

De Google-test mislukt met code 403

De authenticatie slaagt, maar Google weigert de request. Gebruikelijke oorzaak: het Service Account is niet als Eigenaar aan de Search Console-property toegevoegd. Controleer stap 4 van de Google-configuratie opnieuw.

De IndexNow-test mislukt

De server api.indexnow.org kon het sleutelbestand op uw domein niet lezen. Mogelijke oorzaken:

• De .htaccess-snippet is niet geplakt, of op de verkeerde plek (hij moet na RewriteEngine on staan)
• Het fysieke bestand is niet aangemaakt of heeft niet de juiste naam (moet exact de sleutel + .txt zijn)
• De inhoud van het bestand komt niet overeen met de sleutel (typfout, extra regeleinde)
• De webserver serveert het bestand met het verkeerde Content-Type (moet text/plain zijn)
• De firewall of de CDN blokkeert de requests van de IndexNow-robot

Open https://uw-domein.com/UW_SLEUTEL.txt in een browser in privénavigatie: u moet uitsluitend de sleutel in platte tekst zien.

Jobs blijven hangen in de status processing

Dat betekent dat een CRON de jobs heeft vergrendeld maar het lock nooit heeft vrijgegeven (het proces is bijvoorbeeld gedood door een PHP-timeout). U kunt ze handmatig deblokkeren via phpMyAdmin:

UPDATE ps_df_indexapi_queue SET status = 'pending', attempts = 0 WHERE status = 'processing';

Doet het probleem zich regelmatig voor, verhoog dan de PHP max_execution_time van uw hosting, of verklein de batchgrootte in de configuratie van de module.

Het Google-quotum is overschreden

Google antwoordt met code 429 of de melding Quota exceeded. Het standaardquotum is 200 URL’s per dag per Service Account.

Drie realistische opties:

• 24 uur wachten, het quotum wordt dagelijks gereset
• De indexeringsfilters aan Google-zijde beperken tot de typen die er voor u echt toe doen (bijvoorbeeld alleen producten, met categorieën en CMS uitgeschakeld)
• Een tweede Service Account aanmaken en afwisselen, elk Service Account heeft zijn eigen quotum van 200 URL’s per dag

Ter herinnering: IndexNow heeft geen quotum. Is volume uw voornaamste beperking, dan is dat het kanaal om op te steunen.

Volledige reset

Om van nul te herbeginnen (nuttig bij een migratie of een complex probleem):

1. De-installeer de module via Modules › Modulebeheer
2. Herinstalleer: de tabellen worden opnieuw aangemaakt, de IndexNow-sleutel en het CRON-token worden opnieuw gegenereerd
3. Configureer Google en IndexNow opnieuw
4. Werk de .htaccess-snippet bij met de nieuwe sleutel
5. Werk de crontab-regels bij met het nieuwe token

Bekende beperkingen

• Google Indexing API officieel beperkt tot JobPosting-pagina’s of BroadcastEvent in een VideoObject. De API accepteert de andere typen en antwoordt 200, maar die code bevestigt alleen de ontvangst van de melding. Voor een productcatalogus is IndexNow het hoofdkanaal en Google een gelogde aanvulling
• Google-quotum geplafonneerd op 200 URL’s per dag per Service Account, in de praktijk zonder verhogingsmogelijkheid voor e-commerce (zie de sectie Probleemoplossing)
• IndexNow ondersteunt geen URL_DELETED: het protocol beschouwt een 404 of 410 op de URL als de juiste manier om een verwijdering te signaleren. De module negeert dus de IndexNow-jobs met URL_DELETED (Google dient ze wel in)
• Productvarianten worden niet afzonderlijk ingediend: de canonieke URL van het hoofdproduct volstaat, Google consolideert de varianten vanzelf
• Categorieroot genegeerd (ID 1 en 2) om niet-relevante URL’s niet in te dienen
• De module vervangt geen XML-sitemap: de sitemap blijft het officiële ontdekkingskanaal en moet schoon en actueel blijven. De directe indiening komt daar bovenop, ze vervangt hem niet

Support

Voor elke technische vraag: support@datafirefly.com, antwoord binnen 24 werkuren in het Frans of Engels. Inbegrepen gedurende 12 maanden na aankoop.