Google Indexing API dla Magento 2
Wymaga zmian w szablonie
Nie
Drobne zmiany
Znaczące zmiany
Wymaga znajomości kodowania
Nie
Podstawowa
Zaawansowana
Trudność konfiguracji
Wpływ na wydajność
Zgodność ze standardami Magento
Aktualna wersja modułu v1.0.14
Szybsze informowanie Google o zmianach w sklepie
Moduł Kowal Google Indexing API dla Magento 2 pomaga sprawniej zgłaszać do Google adresy URL, które zostały dodane, zmienione albo powinny zostać usunięte z indeksu. Zamiast czekać wyłącznie na standardowe ponowne odwiedzenie strony przez robota Google, administrator może przekazać wybrane adresy do kolejki obsługiwanej przez Google Indexing API.
Rozwiązanie jest szczególnie przydatne w sklepach, w których często zmieniają się treści, oferta, dostępność produktów, strony CMS, landing pages albo wpisy blogowe. Moduł porządkuje cały proces: zbiera adresy z różnych miejsc Magento, sprawdza je, usuwa duplikaty, kontroluje limity i zapisuje historię komunikacji z Google.
Google Indexing API jest oficjalnie przeznaczone głównie dla stron z danymi strukturalnymi
JobPostingorazBroadcastEvent. Zgłoszenie URL-a przez API nie gwarantuje indeksacji, pozycji w wynikach ani przyjęcia każdego adresu przez Google. Moduł jest narzędziem wspierającym techniczne zgłaszanie URL-i, a nie zamiennikiem poprawnego SEO technicznego, sitemap XML, canonicali, robots, hreflang i linkowania wewnętrznego.
Najważniejsze korzyści
Lepsza kontrola nad zgłaszaniem adresów
Moduł daje administratorowi jedno miejsce do zarządzania URL-ami oczekującymi na wysłanie do Google. Produkty, kategorie, strony CMS, ręczny import URL-i i przyszłe źródła mogą korzystać z tej samej kolejki. Dzięki temu nie trzeba budować osobnych integracji dla każdego typu treści.
Mniej ręcznej pracy po zmianach w sklepie
Adresy można dodawać do kolejki bezpośrednio z panelu administracyjnego Magento. Moduł udostępnia akcje masowe oraz przyciski na ekranach edycji wybranych encji, dlatego administrator może szybko zlecić indeksację pojedynczej strony lub większej grupy adresów.
Bezpieczniejsze wykorzystanie limitów API
Google Indexing API działa z limitami. Moduł uwzględnia limity dzienne i minutowe, rozmiar paczki przetwarzanej przez cron oraz opóźnienie wysyłki. Dzięki temu adresy nie są wysyłane chaotycznie i łatwiej ograniczyć ryzyko niepotrzebnego zużycia dostępnego limitu.
Mniej duplikatów i powtarzalnych zgłoszeń
Przed zapisaniem adresu moduł normalizuje URL, waliduje go i sprawdza, czy taki sam adres nie czeka już w aktywnej kolejce. Jeżeli podobne zgłoszenie już istnieje, system może je zaktualizować albo oznaczyć jako zdeduplikowane. To ogranicza bałagan w kolejce i zmniejsza liczbę zbędnych requestów do Google.
Większa przejrzystość dla zespołu
Każde zgłoszenie ma status, źródło, akcję, priorytet, liczbę prób, termin planowanej wysyłki oraz informacje o odpowiedzi Google. Administrator widzi, które adresy czekają, które zostały wysłane poprawnie, które wymagają ponowienia, a które zakończyły się trwałym błędem.
Łatwiejsza diagnostyka problemów
Moduł zapisuje logi komunikacji z Google API, w tym typ requestu, adres endpointu, payload, status HTTP, treść odpowiedzi i czas trwania. Ułatwia to analizę błędów po stronie konfiguracji, uprawnień, limitów albo samych zgłaszanych URL-i.
Gotowość na rozwój sklepu
Architektura modułu opiera się na wspólnym schedulerze i kolejce. Nowe źródła URL-i nie muszą komunikować się z Google bezpośrednio. Wystarczy, że przekażą adresy do kolejki, a istniejący procesor zajmie się walidacją, harmonogramem, limitami, ponowieniami i logowaniem.
Jak działa moduł w praktyce
Moduł działa jako warstwa pośrednia między Magento a Google Indexing API.
- Administrator albo integracja wybiera adresy URL do zgłoszenia.
- Moduł normalizuje i waliduje URL-e, m.in. pod kątem schematu, hosta i dopuszczonych źródeł.
- Poprawne adresy trafiają do centralnej kolejki z odpowiednim statusem, akcją i terminem wysyłki.
- Cron Magento cyklicznie pobiera rekordy gotowe do przetworzenia.
- Procesor kolejki respektuje limity, priorytety, opóźnienia i blokady rekordów.
- Moduł wysyła zgłoszenie do Google Indexing API albo wykonuje przetwarzanie w trybie dry-run.
- Odpowiedź Google zostaje zapisana przy rekordzie kolejki oraz w logach API.
- W przypadku błędów tymczasowych moduł może zaplanować ponowienie z opóźnieniem.
Dzięki temu wysyłka URL-i nie zależy od pojedynczego kliknięcia ani od bezpośredniego requestu z panelu administracyjnego. Cały proces jest kolejkowany, audytowalny i odporniejszy na chwilowe problemy z API.
Główne funkcje
- centralna kolejka URL-i dla różnych źródeł treści,
- obsługa akcji
URL_UPDATEDorazURL_DELETED, - ręczny import wielu URL-i z poziomu panelu administracyjnego,
- akcje masowe dla produktów i stron CMS,
- przyciski zgłaszania indeksacji na ekranach edycji produktu, kategorii i strony CMS,
- opcjonalna integracja z Amasty Blog jako osobny moduł,
- normalizacja i walidacja adresów URL,
- whitelist dozwolonych hostów,
- obsługa store view i identyfikacja źródła zgłoszenia,
- deduplikacja aktywnych zgłoszeń,
- opóźnienie wysyłki, czyli indexing lag,
- priorytety i akcja
Transmit Now, - przetwarzanie przez cron,
- kontrola limitu dziennego i minutowego,
- ponawianie błędów tymczasowych z opóźnieniem,
- statusy kolejki:
scheduled,pending,processing,success,retry,failed_permanent,cancelled, - tryb dry-run do bezpiecznych testów bez wysyłania realnych requestów,
- logi API oraz retencja logów,
- test credentials i metadata w asystencie konfiguracji.
Dla kogo jest ten moduł
Moduł sprawdzi się w sklepach Magento 2, które:
- często aktualizują ofertę produktową,
- publikują lub zmieniają wiele stron CMS,
- prowadzą działania SEO na wielu typach treści,
- potrzebują kontroli nad tym, które URL-e zostały zgłoszone do Google,
- chcą ograniczyć ręczne zarządzanie zgłoszeniami,
- pracują w środowisku multistore lub multilanguage,
- potrzebują czytelnego audytu requestów do Google.
To rozwiązanie jest szczególnie wartościowe dla zespołów e-commerce, SEO i administracyjnych, które chcą mieć wspólny, uporządkowany proces zgłaszania zmian w sklepie do Google.
Przykładowe zastosowania
Nowe lub zmienione produkty
Po dodaniu nowego produktu albo istotnej zmianie istniejącego administrator może przekazać jego adres do kolejki. Moduł zadba o zapis zgłoszenia, właściwe opóźnienie, deduplikację i późniejszą wysyłkę.
Aktualizacja stron CMS i landing pages
Gdy zespół marketingowy publikuje nową kampanię, promocję albo stronę informacyjną, URL może zostać dodany do kolejki bez ręcznej pracy poza Magento.
Porządkowanie adresów po zmianach w serwisie
Moduł obsługuje nie tylko zgłoszenia aktualizacji, ale również akcję URL_DELETED. Dzięki temu można przekazywać Google informację o adresach, które powinny zostać usunięte z indeksu, o ile dany scenariusz jest zgodny z zasadami wykorzystania API.
Masowe działania SEO
Przy większych zmianach w sklepie, takich jak aktualizacja wielu produktów, migracja treści albo odświeżenie kategorii, administrator może skorzystać z akcji masowych i obserwować postęp w kolejce.
Efekt biznesowy
Wdrożenie modułu daje zespołowi większą kontrolę nad technicznym zgłaszaniem zmian do Google. Zamiast rozproszonych, ręcznych i trudnych do zweryfikowania działań powstaje jeden proces: adres trafia do kolejki, przechodzi walidację, zostaje wysłany z poszanowaniem limitów, a wynik jest widoczny w panelu administracyjnym.
Najważniejszą wartością modułu jest uporządkowanie pracy wokół indeksowania: mniej przypadkowych requestów, mniej duplikatów, lepsza diagnostyka i czytelniejsza odpowiedzialność za to, co zostało zgłoszone do Google.
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,BroadcastEventosadzone wVideoObject.
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 composer https://repo.kowal.store
Jeżeli repozytorium jest prywatne, skonfiguruj token GitHub:
composer config http-basic.repo.kowal.store <YOUR E-MAIL> <YOUR-TOKEN>
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
- Przejdź do Google Cloud Console.
- Utwórz nowy projekt albo wybierz istniejący projekt używany dla sklepu.
- 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
- W Google Cloud przejdź do
IAM & Admin > Service Accounts. - Utwórz nowe konto usługi.
- Wygeneruj klucz w formacie JSON.
- 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
- Otwórz Google Search Console.
- Wybierz właściwość odpowiadającą domenie sklepu.
- Upewnij się, że właściwość jest zweryfikowana.
- Dodaj adres
client_emailz 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
Noalbo zostawDry 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 Rundopiero 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_idz 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
0blokuje wysyłkę, ponieważ dostępna liczba slotów wyniesie0.
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:
20jest 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ść
15lub 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, Nostosuj 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:
90dni 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:
- Utworzenie lub wybór projektu Google Cloud.
- Włączenie Indexing API i utworzenie JSON key dla konta usługi.
- Wklejenie JSON albo wgranie pliku JSON w konfiguracji Magento.
- Dodanie service account email jako właściciela w Google Search Console.
- 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
httplubhttps, - przy włączonym
Require HTTPS URLswymagahttps, - 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:
- Zainstaluj moduł i uruchom
setup:upgrade. - W Magento przejdź do
Stores > Configuration > Kowal > Google Indexing API. - Ustaw
Enable = Yes. - Zostaw
Dry Run = Yes. - Wybierz źródło credentials.
- Wklej JSON konta usługi albo wgraj plik JSON.
- Uzupełnij
Google Cloud Project IDwartościąproject_idz JSON. - Uzupełnij
Allowed URL Hosts, np.example.com,www.example.com. - Zostaw domyślne limity, jeżeli Google nie zatwierdził wyższych limitów.
- Zapisz konfigurację i wyczyść cache.
- Przejdź do
Google Indexing API > Setup Assistant. - Sprawdź, czy asystent pokazuje credentials jako gotowe.
- Kliknij
Test Google Credentials. - Dodaj service account email jako właściciela w Google Search Console, jeżeli nie zostało to jeszcze wykonane.
- Wykonaj
Test URL Metadatadla publicznego URL-a z dozwolonego hosta. - Przejdź do
Google Indexing API > Import URLs. - Dodaj jeden testowy URL z akcją
URL_UPDATED. - Uruchom cron Magento:
bin/magento cron:run
- Sprawdź
Google Indexing API > Indexing Queue. - Sprawdź
Google Indexing API > API Logs. - Jeżeli wszystko działa poprawnie, wyłącz
Dry Run. - 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_UPDATEDlubURL_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:
- Sprawdza, czy moduł jest włączony.
- Zwalnia stare blokady rekordów
processingstarsze niż 30 minut. - Przenosi rekordy
scheduleddopending, jeżelischeduled_at <= now. - Sprawdza dostępne sloty w limitach dziennym i minutowym.
- Pobiera rekordy
pendingiretry. - Sortuje je według priorytetu i daty planowanej wysyłki.
- Wysyła request do Google albo wykonuje dry-run.
- 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_keyiclient_email, - czy pole
typema 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_emailkonta 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
pendingalboretry, - czy
scheduled_atnie jest w przyszłości, - czy limity dzienne lub minutowe nie są wykorzystane,
- czy
Daily Publish LimitiRequests Per Minute Limitnie są ustawione na0.
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 AttemptsiRetry Delaysą 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.
Napisz własną recenzję
























