Google Indexing API für Magento 2 - Installation und Konfiguration

1. Wichtige Informationen vor der Implementierung

Das Modul integriert Magento 2 mit der Google Indexing API und ermöglicht das Hinzufügen von URLs zu einer zentralen Übermittlungswarteschlange. Die Warteschlange wird durch Magento Cron verarbeitet, und jede Übermittlung wird validiert, dedupliziert, durch Limits begrenzt und protokolliert.

Gemäß der Google-Dokumentation ist die Indexing API offiziell vor allem für Seiten mit strukturierten Daten vorgesehen:

• JobPosting,
• BroadcastEvent eingebettet in VideoObject.

Die Nutzung der API für Produkte, Kategorien, CMS-Seiten oder Blogbeiträge garantiert weder Indexierung noch Positionen in den Suchergebnissen. Das Modul ist als technisches Werkzeug zur URL-Übermittlung zu verstehen und nicht als Ersatz für XML-Sitemaps, korrekte Canonicals, robots, hreflang, interne Verlinkung und allgemeine SEO-Qualität.

Offizielle Google-Materialien:

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

Stellen Sie vor der Installation sicher, dass die Umgebung die Anforderungen erfüllt:

• Magento 2.4.x,
• PHP 8.1 oder neuer,
• Composer,
• funktionierender Magento Cron,
• Möglichkeit zur Installation des Pakets google/apiclient,
• Administrationszugang zu Magento,
• Google Cloud-Projekt mit aktivierter Indexing API,
• Google Search Console-Property, die für die Shop-Domain verifiziert ist,
• Google-Servicekonto, das in Google Search Console als Eigentümer hinzugefügt wurde.

Das Modul benötigt das Paket:

google/apiclient:^2.16

Das Paket ist in der composer.json des Moduls deklariert, daher sollte Composer es automatisch installieren.

3. Installation des Moduls

3.1. Installation über Composer

Fügen Sie das Composer-Repository von Kowal zum Magento-Projekt hinzu:

Die Zugangsdaten zum Composer-Repository, also E-Mail-Adresse des Kunden und Lizenz-Token, erhalten Sie nach dem Kauf per E-Mail. Sie sind auch nach dem Login im Kundenbereich unter kowal.store verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch den erhaltenen Token. Führen Sie die Befehle im Magento-Stammverzeichnis aus.

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

Konfigurieren Sie die Zugangsdaten zum Composer-Repository von Kowal:

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

Installieren Sie das Paket:

composer require kowal/module-google-indexing-api

Aktivieren Sie das Modul:

bin/magento module:enable Kowal_GoogleIndexingApi

Führen Sie die Aktualisierung des Datenbankschemas aus:

bin/magento setup:upgrade

Leeren Sie den Cache:

bin/magento cache:flush

Führen Sie im Produktionsmodus zusätzlich aus:

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

3.2. Lokale Installation in app/code

Wenn das Modul ohne Composer als lokaler Code installiert wird, legen Sie es in folgendem Verzeichnis ab:

app/code/Kowal/GoogleIndexingApi

Installieren Sie anschließend die Abhängigkeit Google API Client im Magento-Projekt:

composer require google/apiclient:^2.16

Aktivieren Sie das Modul und führen Sie die Standardbefehle von Magento aus:

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

Für die Produktion:

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

3.3. Überprüfung der Installation

Prüfen Sie, ob das Modul aktiv ist:

bin/magento module:status Kowal_GoogleIndexingApi

Nach korrekter Installation sollten im Admin-Panel verfügbar sein:

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

In der Datenbank sollten folgende Tabellen erstellt werden:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Vorbereitung von Google Cloud und Search Console

4.1. Google Cloud-Projekt erstellen

1. Gehen Sie zur Google Cloud Console.
2. Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes Projekt aus, das für den Shop verwendet wird.
3. Aktivieren Sie die API:

Indexing API

Ohne aktivierte API kann das Modul Übermittlungen nicht korrekt senden.

4.2. Servicekonto erstellen

1. Gehen Sie in Google Cloud zu IAM & Admin > Service Accounts.
2. Erstellen Sie ein neues Servicekonto.
3. Generieren Sie einen Schlüssel im JSON-Format.
4. Laden Sie die JSON-Datei herunter und bewahren Sie sie sicher auf.

Das Modul erfordert, dass JSON mindestens folgende Felder enthält:

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

Das Feld type muss den Wert haben:

service_account

4.3. Servicekonto als Eigentümer in Search Console hinzufügen

1. Öffnen Sie Google Search Console.
2. Wählen Sie die Property aus, die der Shop-Domain entspricht.
3. Stellen Sie sicher, dass die Property verifiziert ist.
4. Fügen Sie die Adresse client_email aus der JSON-Datei als Eigentümer der Property hinzu.

Beispiel für eine Servicekonto-Adresse:

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

Wenn das Servicekonto nicht Eigentümer der Search Console-Property ist, kann Google Berechtigungsfehler zurückgeben, z. B. fehlende Bestätigung der URL-Eigentümerschaft.

5. Modulkonfiguration in Magento

Die Konfiguration befindet sich unter:

Stores > Configuration > Kowal > Google Indexing API

Die Konfiguration unterstützt Magento-Scopes:

• Default Config,
• Website,
• Store View.

Dadurch können separate Einstellungen für verschiedene Shops oder Store Views verwendet werden, wenn das Projekt dies erfordert.

6. Bereich General

Enable

Standardmäßig:

No

Aktiviert oder deaktiviert die Funktion des Moduls.

Wenn das Feld den Wert No hat, verarbeitet Cron die Warteschlange nicht. Adressen können in der Datenbank vorhanden sein, aber der Queue-Prozessor sendet sie nicht an Google.

Empfehlung:

• setzen Sie während der Erstkonfiguration No oder lassen Sie Dry Run = Yes,
• setzen Sie nach erfolgreichen Tests Yes.

Dry Run

Standardmäßig:

Yes

Testmodus. Wenn Dry Run aktiviert ist, verarbeitet das Modul Queue-Datensätze, speichert Status und Logs, sendet aber keine reale Übermittlung an Google.

Dies ist der sicherste Modus für den ersten Start, Konfigurationstests und die Prüfung, ob URLs wie erwartet in die Warteschlange gelangen.

7. Bereich Google Access Credentials

Credentials Source

Standardmäßig:

Encrypted configuration value

Legt fest, woher das Modul das JSON des Google-Servicekontos bezieht.

Verfügbare Optionen:

8. Bereich Queue and Limits

In diesem Bereich konfigurieren Sie Tages- und Minutenlimits, die Batch-Größe für Cron, Verzögerungen, Wiederholungen, zugelassene Quellentypen, zulässige URL-Hosts und die HTTPS-Anforderung. Standardwerte wie Daily Publish Limit 200, Requests Per Minute Limit 60, Cron Batch Size 20, Default Indexing Lag 15, Max Attempts 5 und Retry Delay 15 sollten nur im Rahmen der Google-Limits und der Projektanforderungen angepasst werden.

9. Bereich Auto-Indexing

Das Feld Enable Auto-Indexing ist für automatische Integrationen beim Speichern oder Löschen von Entitäten sowie zusätzliche URL-Provider vorbereitet. Im aktuellen Umfang stehen manuelle und administrative Mechanismen zum Hinzufügen von URLs zur Warteschlange zur Verfügung, darunter URL-Import, Mass Actions und Schaltflächen in Bearbeitungsformularen.

10. Bereich Logs

API Log Retention Days legt die Anzahl der Tage fest, für die API-Logs gespeichert werden. Standardmäßig beträgt der Wert 90. Der Cron zum Bereinigen der Logs wird täglich ausgeführt und entfernt Einträge, die älter sind als die in diesem Feld festgelegte Anzahl von Tagen.

11. Installations- und Konfigurationsassistent

Der Assistent befindet sich unter:

Google Indexing API > Setup Assistant

Er dient dazu, schnell zu prüfen, ob die Konfiguration auf Seiten von Magento und Google für den ersten Test bereit ist. Er zeigt den aktuellen Status des Moduls, Dry Run, Credentials, Service Account Email, Allowed Hosts und Queue an und ermöglicht Tests von Google Credentials und URL Metadata.

12. Erster Start Schritt für Schritt

Empfohlene Reihenfolge für den ersten Start: Modul installieren, setup:upgrade ausführen, Konfiguration öffnen, Enable = Yes setzen, Dry Run = Yes beibehalten, Credentials konfigurieren, Allowed URL Hosts ergänzen, Konfiguration speichern, Cache leeren, Setup Assistant prüfen, Google Credentials testen, Service Account Email in Google Search Console als Eigentümer hinzufügen, URL Metadata testen, eine Test-URL importieren, Magento Cron ausführen und Queue sowie API Logs prüfen. Wenn alles korrekt funktioniert, deaktivieren Sie Dry Run und prüfen Sie eine reale Google-Antwort.

13. URL-Import aus dem Admin-Panel

Der manuelle Import befindet sich unter:

Google Indexing API > Import URLs

Das Formular enthält die Felder Action, Store View und URLs. Verfügbare Aktionen sind URL_UPDATED zum Melden hinzugefügter oder aktualisierter URLs und URL_DELETED zum Melden entfernter URLs.

14. Indexierungswarteschlange

Die Warteschlange befindet sich unter:

Google Indexing API > Indexing Queue

Jeder Queue-Datensatz enthält unter anderem URL, URL-Hash, Store ID, Website ID, Quellentyp, ID der Quellentität, Herkunft des Requests, Aktion URL_UPDATED oder URL_DELETED, Status, Priorität, Anzahl der Versuche, geplantes Versanddatum, Verarbeitungsdatum, letzte Fehlermeldung, Google-Antwort und Information created_by.

Queue-Status

Unterstützte Status sind scheduled, pending, processing, success, retry, failed_permanent und cancelled.

Aktionen auf Queue-Datensätzen

Verfügbare Aktionen sind Transmit Now, Retry und Cancel. Transmit Now führt einen realen Request aus, wenn Dry Run = No. Bei Dry Run = Yes wird ein Dry-Run-Log ohne realen Versand an Google gespeichert.

15. Cron

Das Modul fügt zwei Cron-Jobs in der Gruppe default hinzu: kowal_google_indexing_process_queue zur Verarbeitung der Warteschlange alle 5 Minuten und kowal_google_indexing_cleanup_logs zum Bereinigen der API-Logs gemäß API Log Retention Days.

16. API-Logs

Die Logs sind verfügbar unter:

Google Indexing API > API Logs

Das Log umfasst Queue-Datensatz-ID, Store ID, Request-Typ, Endpoint-URL, Payload, HTTP-Status, Antwort-Body, Dauer des Requests und Erstellungsdatum des Logs. Request-Typen sind publish, publish_dry_run und metadata.

17. Mass Actions und Administrationsschaltflächen

Das Modul fügt Mechanismen zur URL-Übermittlung aus dem Admin-Panel hinzu. Auf dem Produkt-Grid ist eine Massenaktion verfügbar, die Produkt-URLs zur Warteschlange hinzufügt. Auf dem CMS-Seiten-Grid ist eine Massenaktion zum Hinzufügen von Seiten-URLs verfügbar. Das Modul fügt außerdem Indexierungs-Schaltflächen auf den Bearbeitungsseiten von Produkt, Kategorie und CMS-Seite hinzu.

18. Empfohlene Startkonfiguration

Für die erste Produktionsimplementierung: Enable nach Speicherung von Credentials und Allowed Hosts auf Yes, Dry Run für Tests auf Yes, anschließend No, Daily Publish Limit 200, Requests Per Minute Limit 60 oder weniger, Cron Batch Size 20, Default Indexing Lag 15, Max Attempts 5, Retry Delay 15, Require HTTPS URLs Yes und API Log Retention Days 90.

19. Typische Probleme und Diagnose

Bei einem fehlgeschlagenen Credentials-Test prüfen Sie, ob JSON korrekt ist, aus einem Servicekonto stammt, private_key und client_email enthält, ob type den Wert service_account hat und ob die JSON-Datei beim Einfügen nicht beschädigt wurde. Bei Berechtigungsfehlern prüfen Sie die Search Console-Verifizierung, Eigentümerrechte für client_email, die passende Property, das richtige Google Cloud-Projekt und das richtige JSON. Wenn URLs vor dem Versand abgelehnt werden, prüfen Sie Validierungsmeldungen wie empty_url, url_too_long, url_not_absolute, https_required, invalid_scheme und host_not_allowed.

20. Optionale Integration mit Amasty Blog

Die Integration mit Amasty Blog ist als separates Modul vorgesehen:

Kowal_GoogleIndexingApiAmastyBlog

Paket:

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

Dieses Modul ist für die Hauptintegration nicht erforderlich. Es sollte nur in Projekten installiert werden, die amasty/blog verwenden und eine Massenaktion für Blogbeiträge benötigen.