DataFirefly Indexing API — Dokumentation

Überblick

DataFirefly Indexing API übermittelt Produkte, Kategorien und CMS-Seiten Ihres PrestaShop-Shops automatisch an die beiden offiziellen direkten Übermittlungs-APIs: Google Indexing API (Service-Account-OAuth2-Authentifizierung, native JWT-RS256-Signatur) und IndexNow über das Relay api.indexnow.org, das in einem einzigen Aufruf an Bing, Yandex, Naver und Seznam weiterleitet. Das Modul greift in native PrestaShop-Hooks ein, reiht jede Änderung in eine deduplizierte Warteschlange ein, und ein CRON verarbeitet den Stapel alle paar Minuten. Sie behalten ein vollständiges Übermittlungsprotokoll und ein Akzeptanzraten-Dashboard.

Voraussetzungen

• PrestaShop 8.0 bis 8.99, oder PrestaShop 9.x
• PHP 7.4 bis 8.3
• PHP-Erweiterungen openssl (für Google JWT-RS256-Signatur) und curl (für HTTP-Anfragen)
• Ein System-CRON oder externer CRON-Dienst, um die Warteschlangenverarbeitung alle 5 bis 15 Minuten aufzurufen
• Optional — für Google: ein Google-Cloud-Konto mit einem Projekt zur Aktivierung der Indexing API und Erstellung eines Service Accounts, sowie eine verifizierte Search-Console-Property für Ihre Domain

Installation

Schritt 1 — Download

Laden Sie das ZIP dfindexingapi-1.0.0.zip nach dem Kauf aus Ihrem DataFirefly-Konto herunter.

Schritt 2 — Installation über das Back-Office

1. Melden Sie sich an Ihrem PrestaShop-Back-Office an
2. Gehen Sie zu Module › Modulmanager › Modul hochladen
3. Klicken Sie auf Datei auswählen und wählen Sie das heruntergeladene ZIP
4. Bestätigen Sie. PrestaShop entpackt und installiert das Modul
5. Klicken Sie nach der Installation auf Konfigurieren

Schritt 3 — Prüfungen nach der Installation

Bei der Installation erstellt das Modul automatisch:

• Die beiden SQL-Tabellen ps_df_indexapi_queue (Warteschlange) und ps_df_indexapi_log (Protokoll)
• Einen alphanumerischen IndexNow-Schlüssel mit 32 Zeichen
• Ein zufälliges CRON-Token mit 32 Zeichen
• 5 Admin-Menü-Tabs: übergeordnet DataFirefly Indexing API, dann Dashboard, Warteschlange, Protokoll, Konfiguration

Öffnen Sie den Tab Konfiguration, um zum nächsten Schritt zu gehen.

Google Indexing API konfigurieren

Die Google Indexing API erfordert einen Google-Cloud-Service-Account. Der Vorgang dauert etwa 5 Minuten.

Schritt 1 — Ein Google-Cloud-Projekt erstellen

1. Gehen Sie zu console.cloud.google.com und melden Sie sich an
2. Klicken Sie oben auf den Projektwähler, dann auf Neues Projekt
3. Geben Sie ihm einen Namen (z. B. Indexing API Shop) und erstellen Sie es
4. Wählen Sie das neu erstellte Projekt

Schritt 2 — Indexing API aktivieren

1. Gehen Sie im linken Menü zu APIs & Dienste › Bibliothek
2. Suchen Sie nach Indexing API
3. Klicken Sie auf Aktivieren

Schritt 3 — Service Account erstellen

1. Gehen Sie zu APIs & Dienste › Anmeldedaten
2. Klicken Sie auf Anmeldedaten erstellen › Dienstkonto
3. Geben Sie ihm einen Namen (z. B. indexing-api-prestashop)
4. Keine IAM-Rolle nötig — gehen Sie zum nächsten Schritt und schließen Sie die Erstellung ab
5. Klicken Sie in der Dienstkontenliste auf das erstellte Konto
6. Tab Schlüssel › Schlüssel hinzufügen › Neuen Schlüssel erstellen
7. Format JSON. Laden Sie die Datei herunter und bewahren Sie sie sicher auf — sie kann später nicht mehr abgerufen werden

Schritt 4 — Service Account zu Search Console hinzufügen

1. Kopieren Sie die Service-Account-E-Mail (Form name@projekt.iam.gserviceaccount.com) aus Google Cloud
2. Gehen Sie zu Google Search Console
3. Wählen Sie Ihre Property (Ihre Shop-Domain)
4. Gehen Sie zu Einstellungen › Nutzer und Berechtigungen
5. Klicken Sie auf Nutzer hinzufügen, fügen Sie die Service-Account-E-Mail ein, wählen Sie die Rolle Inhaber
6. Bestätigen

Schritt 5 — JSON in das Modul einfügen

1. Öffnen Sie die heruntergeladene JSON-Datei in einem Texteditor
2. Kopieren Sie ihren gesamten Inhalt
3. Aktivieren Sie in der Modulkonfiguration im Abschnitt Google Indexing API die Option Google Indexing API aktivieren
4. Fügen Sie das vollständige JSON in das Feld Service Account JSON ein
5. Speichern Sie

Schritt 6 — Verbindung testen

Klicken Sie auf der Konfigurationsseite auf die Schaltfläche Google testen. Das Modul signiert ein JWT RS256, tauscht es gegen ein OAuth2-Token aus und zeigt das Ergebnis an. Wenn alles in Ordnung ist, sehen Sie eine grüne Meldung Authentifizierung OK.

IndexNow konfigurieren

IndexNow ist einfacher zu konfigurieren: kein Service Account, kein OAuth, keine Quote. Nur ein Schlüssel, der im Stammverzeichnis Ihrer Domain veröffentlicht wird.

IndexNow verstehen

IndexNow ist ein offenes Protokoll, das 2021 von Microsoft Bing und Yandex vorangetrieben wurde, dem sich seitdem Naver und Seznam angeschlossen haben. Sie generieren einen alphanumerischen Schlüssel, veröffentlichen ihn im Stammverzeichnis Ihrer Domain als öffentlich zugängliche Datei, und rufen api.indexnow.org mit einer URL-Liste auf. Der Server verifiziert den Schlüssel durch Lesen der Datei auf Ihrer Domain und propagiert dann die URLs an die teilnehmenden Suchmaschinen.

Methode 1 — .htaccess-Umschreibung (empfohlen)

Dies ist die einfachste Methode: Das Modul stellt selbst den Inhalt der Schlüsseldatei über einen Frontend-Controller bereit, und eine .htaccess-Umschreibungsregel im Stammverzeichnis Ihres Shops leitet die Anfrage an diesen Controller weiter.

1. Öffnen Sie in der Modulkonfiguration den Tab IndexNow
2. Aktivieren Sie IndexNow aktivieren
3. Prüfen Sie das Feld Host — es muss Ihrer Shop-Domain ohne Protokoll entsprechen (z. B. mein-shop.de)
4. Speichern
5. Kopieren Sie das auf der Konfigurationsseite angezeigte .htaccess-Snippet — es wird dynamisch mit Ihrem aktuellen Schlüssel generiert
6. Fügen Sie dieses Snippet am Anfang der .htaccess-Datei im PrestaShop-Stammverzeichnis ein, direkt nach dem Block RewriteEngine on
7. Klicken Sie in der Konfiguration auf IndexNow testen — das Modul ruft die Schlüsseldatei-URL auf Ihrer Domain auf und prüft, ob der erwartete Inhalt als text/plain zurückgegeben wird

Methode 2 — Physische Datei

Wenn Sie die .htaccess nicht ändern können, erstellen Sie manuell eine physische Datei im Domain-Stammverzeichnis.

1. Holen Sie Ihren IndexNow-Schlüssel aus der Modulkonfiguration (Feld IndexNow-Schlüssel)
2. Erstellen Sie eine Datei, deren Name genau der Schlüssel + .txt ist (z. B. a1b2c3d4e5f6.txt) im Stammverzeichnis Ihrer Domain
3. Der Dateiinhalt darf nur der Schlüssel selbst sein, ohne Zeilenumbruch
4. Prüfen Sie, dass https://ihre-domain.com/a1b2c3d4e5f6.txt den Schlüssel als text/plain zurückgibt
5. Klicken Sie auf IndexNow testen

CRON konfigurieren

Der CRON ist das Element, das die Warteschlangenverarbeitung antreibt. Ohne einen regelmäßig aufgerufenen CRON stapeln sich die Übermittlungen, gehen aber nie hinaus.

Aktion process — Warteschlangenverarbeitung

Soll alle 5 bis 15 Minuten aufgerufen werden. Das Modul verarbeitet einen konfigurierbaren Stapel (Standard 50 Jobs) unter Befolgung der Deduplizierung und der Indexierungsfilter, dann aktualisiert es Protokoll und Warteschlange.

Die genaue URL wird in der Konfiguration angezeigt. Sie sieht so aus:

https://ihre-domain.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=IHR_TOKEN

Aktion purge — Protokollbereinigung

Soll einmal täglich aufgerufen werden. Das Modul löscht verarbeitete Jobs und Logs jenseits der konfigurierten Aufbewahrung (Standard 30 Tage).

https://ihre-domain.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=IHR_TOKEN

Aktion key — IndexNow-Schlüsseldatei

Wird nur von der .htaccess-Umschreibung verwendet. Sie rufen diese URL niemals manuell auf.

Ihren System-CRON konfigurieren

Fügen Sie unter Linux/cPanel zwei Zeilen in crontab hinzu:

# Alle 10 Minuten — Warteschlangenverarbeitung
*/10 * * * * curl -s "https://ihre-domain.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=IHR_TOKEN" > /dev/null

# Einmal täglich um 3 Uhr — Protokoll-Purge
0 3 * * * curl -s "https://ihre-domain.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=IHR_TOKEN" > /dev/null

Sicherheit des CRON-Tokens

Das Token ist ein bei der Installation generiertes 32-Zeichen-Geheimnis. Ohne das korrekte Token im Parameter token= antwortet der Controller mit HTTP 403. Sie können das Token jederzeit aus der Konfiguration erneuern (Schaltfläche CRON-Token erneuern) — denken Sie dann daran, Ihre crontab-Zeilen mit dem neuen Token zu aktualisieren.

Das Dashboard

Der Tab Dashboard ist Ihre Echtzeitübersicht.

Warteschlangenzähler

Fünf Karten oben auf der Seite:

• Ausstehend — erstellte, aber noch nicht verarbeitete Jobs
• In Bearbeitung — Jobs, die von einem aktiven CRON für die Verarbeitung gesperrt sind
• Übermittelt — erfolgreich verarbeitete Jobs (nicht gelöschte historische Kumulation)
• Fehler — Jobs, die nach N maximalen Wiederholungen fehlgeschlagen sind
• Übersprungen — erstellte, aber von einem Filter ignorierte Jobs (z. B. URL_DELETED für IndexNow)

Anbieterdiagnose

Zwei Karten zeigen den Konfigurationsstatus:

• Google Indexing API — aktiv, falsch konfiguriert oder deaktiviert. Zeigt an, ob das Service-Account-JSON vorhanden und gültig ist
• IndexNow — aktiv, falsch konfiguriert oder deaktiviert. Zeigt an, ob Schlüssel und Host konfiguriert sind

30-Tage-Akzeptanzrate

Kreuztabelle Anbieter × Status über die letzten 30 Tage, mit semantischer Färbung: grün über 90 %, orange zwischen 60 und 90 %, rot darunter. Wenn Google unter 90 % fällt, ist das in der Regel ein Zeichen dafür, dass Sie das Kontingent überschritten haben oder dass URLs nicht mehr erreichbar sind.

Tägliches Übermittlungsdiagramm

Chart.js-Diagramm, das zwei tägliche Kurven überlagert: insgesamt übermittelt und insgesamt akzeptiert. Nützlich, um schnell Einbrüche oder anormale Spitzen zu erkennen.

Die Warteschlange

Der Tab Warteschlange listet alle Jobs auf (pending, processing, submitted, error, skipped) mit nativen PrestaShop-Filtern nach Shop, Objekttyp, ID, Anbieter, Status, Datum.

Job-Status

• pending — erstellt, wartet auf Verarbeitung durch den nächsten CRON
• processing — durch einen aktiven CRON gesperrt (logischer Übergang zur Vermeidung paralleler doppelter Verarbeitung)
• submitted — erfolgreiche Übermittlung an die API. Der Wiederholungszähler ist eingefroren
• error — alle Wiederholungen sind fehlgeschlagen. Bleibt mit der genauen Fehlermeldung der API sichtbar
• skipped — erstellt und dann ignoriert (z. B. URL_DELETED für IndexNow oder deaktivierter Filter)

Aktionen pro Zeile

Jede Zeile bietet:

• Wiederholen — setzt den Job auf pending zurück und setzt den Wiederholungszähler zurück
• Löschen — entfernt den Job aus der Warteschlange

Massenaktionen

Schaltflächen oben in der Liste:

• Alle fehlerhaften Jobs wiederholen — setzt alle Error-Jobs auf pending zurück
• Verarbeitete Jobs löschen — löscht alle submitted/skipped unabhängig vom Alter

Das Protokoll

Der Tab Protokoll listet jede einzelne durchgeführte Übermittlung auf: Anbieter, Typ, Objekt-ID, übermittelte URL, Aktion (URL_UPDATED oder URL_DELETED), zurückgegebener HTTP-Code, Akzeptanz/Ablehnungsanzeige, vollständige Antwortnachricht und Datum. Filterbar, sortierbar, als CSV exportierbar über die standardmäßige PrestaShop-HelperList.

Indexierungsfilter

In der Konfiguration können Sie unabhängig drei Objekttypen aktivieren oder deaktivieren:

• Produkte — Übermittlung bei Erstellung, Aktualisierung, Löschung, Deaktivierung
• Kategorien — Übermittlung bei Erstellung, Aktualisierung, Löschung. Die Kategoriestammverzeichnisse (ID 1 und 2) werden aus Sicherheitsgründen ignoriert
• CMS-Seiten — Übermittlung bei Erstellung, Aktualisierung, Löschung

Das Deaktivieren eines Filters stoppt sofort das Einreihen für diesen Typ, löscht aber nicht die bestehende Warteschlange.

Mehrere Shops

Das Modul unterstützt nativ mehrere Shops. Die Konfiguration (Google-Schlüssel, IndexNow-Schlüssel, Host, Aktivierungen) ist pro Sub-Shop unabhängig. Jobs und Logs sind nach id_shop abgegrenzt — dasselbe Produkt in zwei Sub-Shops erzeugt zwei eigenständige Jobs mit ihren eigenen kanonischen URLs.

Um jeden Sub-Shop unabhängig zu konfigurieren, verwenden Sie den Multistore-Selektor oben im Admin, bevor Sie die Konfiguration öffnen.

Abgehörte PrestaShop-Hooks

Das Modul registriert die folgenden Hooks bei der Installation:

• actionProductSave — Erstellung oder Aktualisierung eines Produkts. Wenn aktiv, wird URL_UPDATED eingereiht; sonst URL_DELETED
• actionProductDelete — endgültige Löschung eines Produkts. URL_DELETED eingereiht
• actionObjectCmsAddAfter — CMS-Seitenerstellung
• actionObjectCmsUpdateAfter — CMS-Seitenaktualisierung
• actionObjectCmsDeleteAfter — CMS-Seitenlöschung
• actionCategoryAdd — Kategorieerstellung
• actionCategoryUpdate — Kategorieaktualisierung
• actionCategoryDelete — Kategorielöschung
• displayBackOfficeHeader — CSS-Fragment-Injektion für das Dashboard-Styling

Jeder Hook erstellt die kanonische URL über das offizielle PrestaShop-Link-Objekt, was Ihre SEO-Friendly-URL-Einstellungen und mehrsprachige Sprachpräfixe respektiert.

Fehlerbehebung

Google-Test schlägt mit Code 401 fehl

Authentifizierung fehlgeschlagen. Prüfen Sie, dass:

• Das eingefügte Service-Account-JSON vollständig und wohlgeformt ist
• Die Indexing API in Google Cloud (Bibliothek) ordnungsgemäß aktiviert ist
• Die Server-Systemuhr korrekt ist — eine Abweichung von mehr als 5 Minuten macht das JWT ungültig

Google-Test schlägt mit Code 403 fehl

Die Authentifizierung gelingt, aber Google lehnt die Anfrage ab. Häufige Ursache: Der Service Account wurde nicht als Inhaber der Search-Console-Property hinzugefügt. Prüfen Sie Schritt 4 der Google-Konfiguration erneut.

IndexNow-Test schlägt fehl

Der Server api.indexnow.org konnte die Schlüsseldatei auf Ihrer Domain nicht lesen. Mögliche Ursachen:

• Das .htaccess-Snippet wurde nicht eingefügt oder an der falschen Stelle eingefügt (muss nach RewriteEngine on stehen)
• Die physische Datei wurde nicht erstellt oder hat den falschen Namen (muss genau der Schlüssel + .txt sein)
• Der Dateiinhalt stimmt nicht mit dem Schlüssel überein (Tippfehler, zusätzlicher Zeilenumbruch)
• Der Webserver stellt die Datei mit dem falschen Content-Type bereit (muss text/plain sein)
• Die Firewall oder das CDN blockiert IndexNow-Robot-Anfragen

Öffnen Sie https://ihre-domain.com/IHR_SCHLUESSEL.txt in einem privaten Browserfenster — Sie müssen nur den Schlüssel als reinen Text sehen.

Jobs bleiben im processing-Status hängen

Dies bedeutet, dass ein CRON die Jobs gesperrt, aber das Lock nie freigegeben hat (z. B. der Prozess wurde durch ein PHP-Timeout beendet). Sie können sie manuell über phpMyAdmin entsperren:

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

Wenn das Problem regelmäßig wieder auftritt, erhöhen Sie die PHP max_execution_time Ihres Hostings oder reduzieren Sie die Stapelgröße in der Modulkonfiguration.

Google-Quote überschritten

Google antwortet mit Code 429 oder der Meldung Quota exceeded. Drei Optionen:

• 24 Stunden warten — die Quote wird täglich zurückgesetzt
• Eine Quotenerhöhung bei Google über die Cloud Console (Kontingente und Systemlimits) beantragen. Begründen Sie, dass Ihr E-Commerce-Shop mehr tägliche Übermittlungen benötigt
• Einen zweiten Service Account erstellen und abwechseln — jeder Service Account hat seine eigene Quote von 200 URLs/Tag

Vollständiger Reset

Um von vorne anzufangen (nützlich bei Migration oder komplexem Problem):

1. Modul über Module › Manager deinstallieren
2. Neu installieren — Tabellen werden neu erstellt, IndexNow-Schlüssel und CRON-Token werden neu generiert
3. Google und IndexNow neu konfigurieren
4. .htaccess-Snippet mit dem neuen Schlüssel aktualisieren
5. Crontab-Zeilen mit dem neuen Token aktualisieren

Bekannte Einschränkungen

• IndexNow verarbeitet kein URL_DELETED — das Protokoll betrachtet einen 404 oder 410 auf der URL als korrekten Weg, eine Löschung zu signalisieren. Das Modul ignoriert daher IndexNow-Jobs in URL_DELETED (Google übermittelt sie ordnungsgemäß)
• Google-Quote begrenzt auf 200 URLs/Tag pro Service Account standardmäßig
• Produktvarianten nicht einzeln übermittelt — die kanonische URL des Hauptprodukts reicht aus, Google konsolidiert die Varianten natürlich
• Kategoriestammverzeichnisse ignoriert (ID 1 und 2), um die Übermittlung nicht relevanter URLs zu vermeiden
• Google Indexing API offiziell beschränkt auf JobPosting- oder BroadcastEvent-Seiten — die API akzeptiert andere Typen und antwortet mit 200, aber Google kann die endgültige Indexierung ignorieren. Für die meisten Shops bleibt IndexNow in der Praxis die wirkungsvollste Lösung

Support

Für technische Fragen: support@datafirefly.com — Antwort innerhalb von 24 Werkstunden auf Deutsch, Englisch oder Französisch. Im Kauf für 12 Monate enthalten.