Google Indexing API dla Magento 2 - instalacja i konfiguracja

1. Ważne informacje przed wdrożeniem

Moduł integruje Magento 2 z Google Indexing API i pozwala dodawać adresy URL do centralnej kolejki zgłoszeń. Kolejka jest przetwarzana przez cron Magento, a każde zgłoszenie jest walidowane, deduplikowane, objęte limitami i logowane.

Zgodnie z dokumentacją Google, Indexing API jest oficjalnie przeznaczone przede wszystkim dla stron z danymi strukturalnymi:

• JobPosting,
• BroadcastEvent osadzone w VideoObject.

Użycie API dla produktów, kategorii, stron CMS lub wpisów blogowych nie gwarantuje indeksacji ani pozycji w wynikach wyszukiwania. Moduł należy traktować jako narzędzie techniczne do zgłaszania URL-i, a nie zamiennik sitemap XML, poprawnych canonicali, robots, hreflang, linkowania wewnętrznego i ogólnej jakości SEO.

Oficjalne materiały Google:

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

Przed instalacją upewnij się, że środowisko spełnia wymagania:

• Magento 2.4.x,
• PHP 8.1 lub nowszy,
• Composer,
• działający cron Magento,
• możliwość instalacji pakietu google/apiclient,
• dostęp administracyjny do Magento,
• projekt Google Cloud z włączonym Indexing API,
• właściwość w Google Search Console zweryfikowana dla domeny sklepu,
• konto usługi Google dodane jako właściciel w Google Search Console.

Moduł wymaga pakietu:

google/apiclient:^2.16

Pakiet jest zadeklarowany w composer.json modułu, więc Composer powinien zainstalować go automatycznie.

3. Instalacja modułu

3.1. Instalacja przez Composer z repozytorium VCS

Jeżeli moduł jest instalowany z prywatnego lub publicznego repozytorium Git, dodaj repozytorium do projektu Magento:

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

Jeżeli repozytorium jest prywatne, skonfiguruj token GitHub:

composer config --global --auth github-oauth.github.com <TWÓJ_TOKEN_GITHUB>

Zainstaluj pakiet:

composer require kowal/module-google-indexing-api

Włącz moduł:

bin/magento module:enable Kowal_GoogleIndexingApi

Wykonaj aktualizację schematu bazy:

bin/magento setup:upgrade

Wyczyść cache:

bin/magento cache:flush

W trybie produkcyjnym wykonaj dodatkowo:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3.2. Instalacja lokalna w app/code

Jeżeli moduł jest instalowany bez Composera jako kod lokalny, umieść go w katalogu:

app/code/Kowal/GoogleIndexingApi

Następnie doinstaluj zależność Google API Client w projekcie Magento:

composer require google/apiclient:^2.16

Włącz moduł i wykonaj standardowe komendy Magento:

bin/magento module:enable Kowal_GoogleIndexingApi
bin/magento setup:upgrade
bin/magento cache:flush

Dla produkcji:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3.3. Weryfikacja instalacji

Sprawdź, czy moduł jest aktywny:

bin/magento module:status Kowal_GoogleIndexingApi

Po poprawnej instalacji w panelu administracyjnym powinny być dostępne:

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

W bazie danych powinny powstać tabele:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Przygotowanie Google Cloud i Search Console

4.1. Utworzenie projektu Google Cloud

1. Przejdź do Google Cloud Console.
2. Utwórz nowy projekt albo wybierz istniejący projekt używany dla sklepu.
3. Włącz API:

Indexing API

Bez włączonego API moduł nie będzie mógł poprawnie wysyłać zgłoszeń.

4.2. Utworzenie konta usługi

1. W Google Cloud przejdź do IAM & Admin > Service Accounts.
2. Utwórz nowe konto usługi.
3. Wygeneruj klucz w formacie JSON.
4. Pobierz plik JSON i przechowuj go bezpiecznie.

Moduł wymaga, aby JSON zawierał co najmniej pola:

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

Pole type musi mieć wartość:

service_account

4.3. Dodanie konta usługi jako właściciela w Search Console

1. Otwórz Google Search Console.
2. Wybierz właściwość odpowiadającą domenie sklepu.
3. Upewnij się, że właściwość jest zweryfikowana.
4. Dodaj adres client_email z pliku JSON jako właściciela właściwości.

Przykład adresu konta usługi:

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

Jeżeli konto usługi nie będzie właścicielem właściwości Search Console, Google może zwracać błędy uprawnień, np. brak potwierdzenia własności URL-a.

5. Konfiguracja modułu w Magento

Konfiguracja znajduje się w:

Stores > Configuration > Kowal > Google Indexing API

Konfiguracja obsługuje zakresy Magento:

• Default Config,
• Website,
• Store View.

Dzięki temu można mieć osobne ustawienia dla różnych sklepów lub widoków sklepu, jeżeli projekt tego wymaga.

6. Sekcja General

Enable

Domyślnie:

No

Włącza lub wyłącza działanie modułu.

Gdy pole ma wartość No, cron nie przetwarza kolejki. Adresy mogą istnieć w bazie, ale procesor kolejki nie będzie ich wysyłał do Google.

Rekomendacja:

• podczas pierwszej konfiguracji ustaw No albo zostaw Dry Run = Yes,
• po poprawnych testach ustaw Yes.

Dry Run

Domyślnie:

Yes

Tryb testowy. Gdy Dry Run jest włączony, moduł przetwarza rekordy kolejki, zapisuje statusy i logi, ale nie wysyła realnego zgłoszenia do Google.

To najbezpieczniejszy tryb do pierwszego uruchomienia, testów konfiguracji i sprawdzenia, czy URL-e trafiają do kolejki zgodnie z oczekiwaniami.

Rekomendacja:

• pierwsze testy wykonuj zawsze z Dry Run = Yes,
• wyłącz Dry Run dopiero po sprawdzeniu credentials, allowed hosts, kolejki i logów.

7. Sekcja Google Access Credentials

Credentials Source

Domyślnie:

Encrypted configuration value

Określa, skąd moduł pobiera JSON konta usługi Google.

Dostępne opcje:

Opcja	Wartość techniczna	Opis
Encrypted configuration value	config	JSON jest wklejany w konfiguracji Magento i zapisywany jako szyfrowana wartość sensitive config.
Uploaded JSON file	file	JSON jest wgrywany jako plik i zapisywany poza katalogiem pub, w var/google-indexing.

Rekomendacja:

• dla prostych wdrożeń można użyć wartości szyfrowanej w konfiguracji,
• dla środowisk z kontrolą dostępu do plików wygodniejszy może być upload pliku JSON.

Service Account JSON

Widoczne, gdy Credentials Source = Encrypted configuration value.

W tym polu należy wkleić pełną zawartość pliku JSON konta usługi Google.

Moduł waliduje JSON przed zapisem. Sprawdzane są:

• poprawność formatu JSON,
• obecność pól type, project_id, private_key, client_email,
• wartość type = service_account.

Wartość jest zapisywana jako szyfrowana konfiguracja Magento.

Service Account JSON File

Widoczne, gdy Credentials Source = Uploaded JSON file.

Pozwala wgrać plik JSON konta usługi Google.

Moduł:

• akceptuje tylko pliki z rozszerzeniem .json,
• waliduje zawartość pliku,
• sprawdza wymagane pola type, project_id, private_key, client_email,
• zapisuje plik poza katalogiem publicznym, w var/google-indexing,
• próbuje ustawić uprawnienia pliku na 0600, jeżeli pozwala na to sterownik plików.

Plik jest zapisywany z nazwą zależną od zakresu konfiguracji, np. dla zakresu globalnego:

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

Google Cloud Project ID

Pole tekstowe na identyfikator projektu Google Cloud.

W aktualnej implementacji modułu główna autoryzacja bazuje na danych z JSON konta usługi. Pole Google Cloud Project ID pełni funkcję informacyjną i porządkującą konfigurację, zwłaszcza gdy sklep korzysta z kilku środowisk lub kilku projektów Google Cloud.

Rekomendacja:

• wpisz wartość project_id z pliku JSON,
• używaj osobnych projektów Google Cloud dla środowisk produkcyjnych i testowych, jeżeli taka separacja jest przyjęta w projekcie.

8. Sekcja Queue and Limits

Daily Publish Limit

Domyślnie:

200

Określa maksymalną liczbę zgłoszeń publish, które moduł może wykonać w ciągu dnia.

Limiter liczy requesty typu:

• publish,
• publish_dry_run.

Jeżeli limit zostanie wykorzystany, procesor kolejki nie pobierze kolejnych rekordów do wysłania aż do kolejnego okna dziennego.

Rekomendacja:

• zostaw 200, jeżeli projekt korzysta z domyślnego limitu onboardingowego Google,
• zwiększ wartość tylko wtedy, gdy projekt Google Cloud ma zatwierdzony wyższy limit,
• ustawienie 0 blokuje wysyłkę, ponieważ dostępna liczba slotów wyniesie 0.

Requests Per Minute Limit

Domyślnie:

60

Określa maksymalną liczbę requestów publish na minutę.

Moduł porównuje tę wartość z liczbą requestów zapisanych w logach z ostatniej minuty. Jeżeli limit minutowy jest wykorzystany, cron nie przetworzy kolejnych rekordów w danym przebiegu.

Rekomendacja:

• dla typowego wdrożenia zostaw wartość domyślną,
• zmniejsz wartość, jeżeli chcesz bardziej konserwatywnie obciążać API,
• nie ustawiaj 0, chyba że chcesz tymczasowo zatrzymać wysyłkę.

Cron Batch Size

Domyślnie:

20

Określa maksymalną liczbę rekordów kolejki przetwarzanych w jednym przebiegu crona.

Rzeczywista liczba przetworzonych rekordów jest ograniczana również przez:

• Daily Publish Limit,
• Requests Per Minute Limit,
• liczbę rekordów gotowych do wysłania,
• status i datę scheduled_at.

Rekomendacja:

• 20 jest bezpieczną wartością startową,
• przy dużych kolejkach można zwiększyć wartość, ale tylko z uwzględnieniem limitów Google.

Default Indexing Lag (minutes)

Domyślnie:

15

Określa domyślne opóźnienie między dodaniem URL-a do kolejki a momentem, od którego może zostać wysłany.

Opóźnienie pomaga:

• ograniczyć duplikaty,
• uniknąć wysyłki po każdej drobnej zmianie,
• dać administratorowi czas na korektę treści,
• lepiej zarządzać limitem API.

W aktualnej implementacji to ustawienie jest używane wtedy, gdy zgłoszenie nie ma własnego opóźnienia.

Manual Form Indexing Lag (minutes)

Domyślnie:

15

Określa opóźnienie dla URL-i dodanych przez formularz:

Google Indexing API > Import URLs

Jeżeli administrator wklei listę URL-i ręcznie, każdy poprawny adres zostanie zaplanowany z tym opóźnieniem.

Rekomendacja:

• ustaw 0, jeżeli ręczny import ma trafiać do kolejki natychmiast,
• zostaw 15, jeżeli chcesz zachować bufor na deduplikację i kontrolę zgłoszeń.

Mass Action Indexing Lag (minutes)

Domyślnie:

15

Określa opóźnienie dla URL-i dodanych przez:

• akcje masowe produktów,
• akcje masowe stron CMS,
• przyciski zgłaszania indeksacji na ekranach edycji produktu, kategorii i strony CMS.

Rekomendacja:

• dla masowych operacji zostaw wartość 15 lub większą,
• dla małych sklepów i ręcznej pracy administracyjnej można rozważyć niższą wartość.

Max Attempts

Domyślnie:

5

Określa maksymalną liczbę prób wysłania jednego rekordu kolejki.

Jeżeli Google zwróci błąd tymczasowy, moduł ustawi status retry, o ile liczba prób jest mniejsza niż Max Attempts. Po przekroczeniu limitu rekord otrzyma status failed_permanent.

Błędy traktowane jako tymczasowe:

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

Retry Delay (minutes)

Domyślnie:

15

Podstawowe opóźnienie przed kolejną próbą wysyłki po błędzie tymczasowym.

Cron używa narastającego opóźnienia. Mnożnik zależy od liczby prób i jest ograniczony maksymalnie do 24. Dzięki temu kolejne próby nie są wykonywane zbyt agresywnie.

Przykład dla wartości 15:

Próba	Przybliżone opóźnienie
1	15 minut
2	30 minut
3	60 minut
4	120 minut

Allowed Source Types

Domyślnie:

manual,product,category,cms_page,amasty_blog_post

Lista dozwolonych typów źródeł, oddzielona przecinkami.

Obsługiwane wartości:

Wartość	Znaczenie
manual	URL dodany ręcznie przez formularz importu.
product	URL produktu.
category	URL kategorii.
cms_page	URL strony CMS.
amasty_blog_post	URL wpisu Amasty Blog, jeżeli używany jest osobny moduł integracyjny.

Jeżeli typ źródła nie znajduje się na liście, scheduler pominie zgłoszenie i oznaczy je jako skipped.

Rekomendacja:

• zostaw wartości domyślne, jeżeli sklep korzysta ze wszystkich standardowych źródeł,
• usuń źródła, których nie chcesz dopuszczać do kolejki.

Allowed URL Hosts

Domyślnie:

puste

Lista dozwolonych hostów URL, oddzielona przecinkami.

Przykład:

example.com,www.example.com

Jeżeli lista jest uzupełniona, moduł przyjmie tylko adresy należące do wskazanych hostów. Jeżeli URL ma inny host, walidacja zwróci błąd:

host_not_allowed

Rekomendacja:

• na produkcji zawsze uzupełnij tę listę,
• dodaj wszystkie hosty używane przez sklep, np. domenę główną, wersję www, domeny store view i domeny językowe,
• nie dodawaj domen testowych do konfiguracji produkcyjnej.

Require HTTPS URLs

Domyślnie:

Yes

Wymusza, aby zgłaszane adresy URL używały schematu https.

Jeżeli pole jest włączone, adres z http zostanie odrzucony z błędem:

https_required

Rekomendacja:

• dla produkcyjnych sklepów zostaw Yes,
• No stosuj tylko w wyjątkowych środowiskach testowych.

9. Sekcja Auto-Indexing

Enable Auto-Indexing

Domyślnie:

No

Pole jest przygotowane pod automatyczne integracje zapisu lub usuwania encji oraz dodatkowych providerów URL-i.

W aktualnym zakresie modułu dostępne są ręczne i administracyjne mechanizmy dodawania URL-i do kolejki, m.in. import URL-i, Mass Actions oraz przyciski na formularzach edycji.

Rekomendacja:

• zostaw No, jeżeli auto-indexing nie został wdrożony w projekcie,
• włącz dopiero wtedy, gdy projekt zawiera obsługę automatycznych zdarzeń encji korzystającą z tej konfiguracji.

10. Sekcja Logs

API Log Retention Days

Domyślnie:

90

Określa liczbę dni przechowywania logów API.

Cron czyszczący logi działa codziennie o:

03:15

Usuwa wpisy starsze niż liczba dni ustawiona w tym polu.

Rekomendacja:

• 90 dni jest rozsądną wartością diagnostyczną,
• przy dużej liczbie requestów można zmniejszyć retencję,
• przy audytach SEO można zwiększyć retencję, pamiętając o rozmiarze tabeli logów.

11. Asystent instalacji i konfiguracji

Asystent znajduje się w:

Google Indexing API > Setup Assistant

Jego celem jest szybkie sprawdzenie, czy konfiguracja po stronie Magento i Google jest gotowa do pierwszego testu.

11.1. Sekcja Current Status

Asystent pokazuje bieżący stan najważniejszych elementów:

Pole	Znaczenie
Module	Informuje, czy moduł jest włączony w konfiguracji.
Dry Run	Informuje, czy aktywny jest tryb testowy bez realnej wysyłki do Google.
Credentials	Pokazuje, czy moduł potrafi odczytać i sparsować credentials Google.
Service Account Email	Wyświetla client_email z JSON konta usługi. Ten adres należy dodać jako właściciela w Search Console.
Allowed Hosts	Pokazuje listę hostów dopuszczonych w konfiguracji.
Queue	Pokazuje liczbę rekordów w statusach scheduled, pending, retry i failed_permanent.

Jeżeli Credentials ma status Missing or invalid, należy wrócić do konfiguracji i poprawić JSON lub plik credentials.

Jeżeli Allowed Hosts pokazuje Not configured, moduł nie ogranicza hostów. Technicznie może to działać, ale produkcyjnie zalecane jest jawne wpisanie hostów sklepu.

11.2. Sekcja Setup Steps

Asystent wyświetla listę kroków potrzebnych przed pierwszym realnym requestem:

1. Utworzenie lub wybór projektu Google Cloud.
2. Włączenie Indexing API i utworzenie JSON key dla konta usługi.
3. Wklejenie JSON albo wgranie pliku JSON w konfiguracji Magento.
4. Dodanie service account email jako właściciela w Google Search Console.
5. Uruchomienie testów, a następnie import jednego URL-a przy włączonym Dry Run.

Asystent zawiera linki do:

• Google Cloud dla Indexing API,
• konfiguracji modułu w Magento,
• Google Search Console.

11.3. Test Google Credentials

Przycisk:

Test Google Credentials

sprawdza, czy Magento potrafi użyć danych konta usługi do uzyskania tokenu OAuth dla zakresu:

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

Pozytywny wynik oznacza, że:

• JSON jest poprawny,
• klucz prywatny może zostać użyty,
• Google wydał token OAuth.

Negatywny wynik może oznaczać:

• niepoprawny JSON,
• błędny lub uszkodzony private_key,
• brak wymaganego pola w JSON,
• problem z komunikacją z Google,
• użycie klucza, który nie jest kluczem konta usługi.

Ten test nie potwierdza jeszcze, że konto usługi ma dostęp właścicielski do domeny w Search Console. Do tego potrzebny jest test URL metadata albo realne zgłoszenie testowego URL-a.

11.4. Test URL Metadata

Formularz:

Test URL Metadata

pozwala wpisać publiczny URL z dozwolonego hosta i wykonać request metadata do Google Indexing API.

Przed wysłaniem requestu moduł:

• normalizuje URL,
• sprawdza, czy URL jest absolutny,
• sprawdza schemat http lub https,
• przy włączonym Require HTTPS URLs wymaga https,
• sprawdza Allowed URL Hosts, jeżeli zostały skonfigurowane.

Możliwe wyniki:

Wynik	Znaczenie
Sukces HTTP 2xx	Google zwrócił metadata dla URL-a.
HTTP 404	Często oznacza, że URL nie ma jeszcze wcześniejszego skutecznego zgłoszenia przez Indexing API. To nie musi oznaczać błędnej konfiguracji.
Błąd walidacji przed requestem	URL nie spełnia warunków modułu, np. zły host, brak HTTPS albo nieabsolutny adres.
Błąd HTTP inny niż 404	Należy sprawdzić komunikat Google, uprawnienia Search Console, credentials i limity.

Metadata test nie tworzy nowego zgłoszenia publish. Służy do diagnostyki połączenia i statusu URL-a.

12. Pierwsze uruchomienie krok po kroku

Rekomendowana kolejność pierwszego uruchomienia:

1. Zainstaluj moduł i uruchom setup:upgrade.
2. W Magento przejdź do Stores > Configuration > Kowal > Google Indexing API.
3. Ustaw Enable = Yes.
4. Zostaw Dry Run = Yes.
5. Wybierz źródło credentials.
6. Wklej JSON konta usługi albo wgraj plik JSON.
7. Uzupełnij Google Cloud Project ID wartością project_id z JSON.
8. Uzupełnij Allowed URL Hosts, np. example.com,www.example.com.
9. Zostaw domyślne limity, jeżeli Google nie zatwierdził wyższych limitów.
10. Zapisz konfigurację i wyczyść cache.
11. Przejdź do Google Indexing API > Setup Assistant.
12. Sprawdź, czy asystent pokazuje credentials jako gotowe.
13. Kliknij Test Google Credentials.
14. Dodaj service account email jako właściciela w Google Search Console, jeżeli nie zostało to jeszcze wykonane.
15. Wykonaj Test URL Metadata dla publicznego URL-a z dozwolonego hosta.
16. Przejdź do Google Indexing API > Import URLs.
17. Dodaj jeden testowy URL z akcją URL_UPDATED.
18. Uruchom cron Magento:

bin/magento cron:run

19. Sprawdź Google Indexing API > Indexing Queue.
20. Sprawdź Google Indexing API > API Logs.
21. Jeżeli wszystko działa poprawnie, wyłącz Dry Run.
22. Dodaj ponownie jeden testowy URL i sprawdź realną odpowiedź Google.

13. Import URL-i z panelu administracyjnego

Import ręczny znajduje się w:

Google Indexing API > Import URLs

Formularz zawiera pola:

Pole	Opis
Action	Typ zgłoszenia do Google: dodanie/aktualizacja albo usunięcie.
Store View	Store view, do którego ma być przypisane zgłoszenie. Dostępna jest też opcja globalna Use global/no store.
URLs	Lista absolutnych URL-i, po jednym adresie w linii.

Dostępne akcje:

Akcja w formularzu	Wartość API	Znaczenie
Submit URLs for indexing	URL_UPDATED	Informuje Google, że URL został dodany albo zaktualizowany.
Delete URLs from indexing	URL_DELETED	Informuje Google, że URL został usunięty i może zostać usunięty z indeksu.

Po wysłaniu formularza moduł pokaże podsumowanie:

• dodane,
• zaktualizowane,
• zdeduplikowane,
• niepoprawne,
• pominięte.

Pierwsze 10 komunikatów walidacyjnych jest pokazywane jako notice w panelu administracyjnym.

14. Kolejka indeksowania

Kolejka znajduje się w:

Google Indexing API > Indexing Queue

Każdy rekord kolejki zawiera m.in.:

• URL,
• hash URL-a,
• store ID,
• website ID,
• typ źródła,
• ID encji źródłowej,
• pochodzenie requestu,
• akcję URL_UPDATED lub URL_DELETED,
• status,
• priorytet,
• liczbę prób,
• maksymalną liczbę prób,
• datę planowanej wysyłki,
• datę przetworzenia,
• ostatni kod błędu,
• ostatni powód błędu,
• ostatni komunikat błędu,
• odpowiedź Google,
• informację created_by.

Statusy kolejki

Status	Znaczenie
scheduled	URL jest zaplanowany, ale czeka jeszcze na datę scheduled_at.
pending	URL jest gotowy do przetworzenia przez cron.
processing	URL jest aktualnie przetwarzany.
success	Google zwrócił odpowiedź sukcesu.
retry	Wystąpił błąd tymczasowy i rekord czeka na kolejną próbę.
failed_permanent	Wysyłka zakończyła się trwale albo przekroczono maksymalną liczbę prób.
cancelled	Rekord został ręcznie anulowany.

Akcje na rekordach kolejki

Akcja	Działanie
Transmit Now	Ustawia rekord jako pilny, blokuje go, wysyła natychmiast przez klienta Google i zapisuje wynik.
Retry	Ustawia rekord jako pending, czyści blokadę i planuje ponowną próbę od razu.
Cancel	Ustawia status cancelled i czyści blokadę.

Uwaga: Transmit Now wykonuje realny request, jeżeli Dry Run = No. Przy Dry Run = Yes zostanie zapisany log dry-run bez realnej wysyłki do Google.

15. Cron

Moduł dodaje dwa zadania cron w grupie default.

Przetwarzanie kolejki

kowal_google_indexing_process_queue

Harmonogram:

*/5 * * * *

Zadanie uruchamia procesor kolejki co 5 minut.

Procesor:

1. Sprawdza, czy moduł jest włączony.
2. Zwalnia stare blokady rekordów processing starsze niż 30 minut.
3. Przenosi rekordy scheduled do pending, jeżeli scheduled_at <= now.
4. Sprawdza dostępne sloty w limitach dziennym i minutowym.
5. Pobiera rekordy pending i retry.
6. Sortuje je według priorytetu i daty planowanej wysyłki.
7. Wysyła request do Google albo wykonuje dry-run.
8. Zapisuje odpowiedź, status i log API.

Czyszczenie logów

kowal_google_indexing_cleanup_logs

Harmonogram:

15 3 * * *

Zadanie usuwa logi API starsze niż liczba dni ustawiona w polu:

API Log Retention Days

16. Logi API

Logi są dostępne w:

Google Indexing API > API Logs

Log obejmuje:

• ID rekordu kolejki,
• store ID,
• typ requestu,
• URL endpointu,
• payload,
• status HTTP,
• body odpowiedzi,
• czas trwania requestu,
• datę utworzenia logu.

Typy requestów:

Typ	Znaczenie
publish	Realne zgłoszenie URL-a do Google.
publish_dry_run	Przetworzenie w trybie dry-run bez realnego requestu do Google.
metadata	Test metadata dla URL-a.

17. Mass Actions i przyciski administracyjne

Moduł dodaje mechanizmy zgłaszania URL-i z panelu administracyjnego.

Produkty

Na gridzie produktów dostępna jest akcja masowa dodająca URL-e produktów do kolejki.

Moduł pomija produkty:

• wyłączone,
• niewidoczne indywidualnie.

URL-e są generowane na podstawie URL rewrites dla aktywnych store view.

Strony CMS

Na gridzie stron CMS dostępna jest akcja masowa dodająca URL-e stron do kolejki.

Moduł pomija strony nieaktywne.

Jeżeli strona CMS jest przypisana do wszystkich store view, moduł rozwiązuje URL-e dla wszystkich store view.

Produkt, kategoria i strona CMS - przyciski na formularzu edycji

Moduł dodaje przyciski zgłaszania indeksacji na ekranach edycji:

• produktu,
• kategorii,
• strony CMS.

Przycisk rozwiązuje URL-e encji dla store view i dodaje je do kolejki jako URL_UPDATED.

18. Rekomendowana konfiguracja startowa

Dla pierwszego wdrożenia produkcyjnego:

Pole	Rekomendacja
Enable	Yes po zapisaniu credentials i allowed hosts.
Dry Run	Yes na czas testów, później No.
Credentials Source	Encrypted configuration value albo Uploaded JSON file, zgodnie z polityką projektu.
Google Cloud Project ID	project_id z JSON.
Daily Publish Limit	200, chyba że Google zatwierdził wyższy limit.
Requests Per Minute Limit	60 albo mniej przy ostrożnym wdrożeniu.
Cron Batch Size	20.
Default Indexing Lag	15.
Manual Form Indexing Lag	0-15, zależnie od sposobu pracy administratorów.
Mass Action Indexing Lag	15.
Max Attempts	5.
Retry Delay	15.
Allowed Source Types	manual,product,category,cms_page,amasty_blog_post.
Allowed URL Hosts	Wszystkie produkcyjne hosty sklepu.
Require HTTPS URLs	Yes.
Enable Auto-Indexing	No, chyba że projekt wdraża automatyczne providery.
API Log Retention Days	90.

19. Typowe problemy i diagnostyka

Credentials test failed

Sprawdź:

• czy JSON jest poprawny,
• czy JSON pochodzi z konta usługi,
• czy zawiera private_key i client_email,
• czy pole type ma wartość service_account,
• czy plik JSON nie został uszkodzony podczas wklejania.

Google zwraca błąd uprawnień

Sprawdź:

• czy domena jest zweryfikowana w Search Console,
• czy client_email konta usługi jest dodany jako właściciel,
• czy testowany URL należy do tej samej właściwości Search Console,
• czy używasz właściwego projektu Google Cloud i właściwego JSON.

URL jest odrzucany przed wysyłką

Sprawdź komunikat walidacji:

Komunikat	Przyczyna
empty_url	Pusty URL.
url_too_long	URL ma więcej niż 2048 znaków.
url_not_absolute	URL nie ma schematu lub hosta.
https_required	Włączono wymóg HTTPS, a URL używa HTTP.
invalid_scheme	Schemat nie jest http ani https.
host_not_allowed	Host URL-a nie znajduje się w Allowed URL Hosts.

Kolejka się nie przetwarza

Sprawdź:

• czy Enable = Yes,
• czy działa cron Magento,
• czy rekordy mają status pending albo retry,
• czy scheduled_at nie jest w przyszłości,
• czy limity dzienne lub minutowe nie są wykorzystane,
• czy Daily Publish Limit i Requests Per Minute Limit nie są ustawione na 0.

Rekordy trafiają do retry

Sprawdź:

• status HTTP w rekordzie kolejki,
• log API,
• odpowiedź Google,
• czy nie występuje limit 429,
• czy nie ma chwilowych błędów 5xx,
• czy Max Attempts i Retry Delay są ustawione zgodnie z oczekiwaniami.

20. Opcjonalna integracja z Amasty Blog

Integracja z Amasty Blog jest przewidziana jako osobny moduł:

Kowal_GoogleIndexingApiAmastyBlog

Pakiet:

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

Ten moduł nie jest wymagany do działania głównej integracji. Należy instalować go tylko w projektach, które używają amasty/blog i potrzebują akcji masowej dla wpisów blogowych.