DataFirefly Indexing API: dokumentacja

Prezentacja

DataFirefly Indexing API automatycznie zgłasza produkty, kategorie i strony CMS Twojego sklepu PrestaShop do dwóch istniejących kanałów bezpośredniego zgłaszania: IndexNow przez relay api.indexnow.org, który jednym wywołaniem propaguje do Bing, Yandex, Naver i Seznam, oraz Google Indexing API (uwierzytelnianie Service Account OAuth2, natywne podpisywanie JWT RS256). Moduł podpina się do natywnych hooków PrestaShop, kolejkuje każdą modyfikację w kolejce z deduplikacją, a CRON przetwarza partie co kilka minut. Zachowujesz pełny dziennik zgłoszeń i pulpit ze wskaźnikiem akceptacji.

Wymagania

• PrestaShop 8.0 do 8.99 albo PrestaShop 9.x
• PHP 7.4 do 8.3
• Rozszerzenia PHP openssl (do podpisywania JWT RS256 dla Google) i curl (do zapytań HTTP)
• CRON systemowy albo zewnętrzna usługa CRON do wywoływania przetwarzania kolejki co 5 do 15 minut
• Opcjonalnie, dla Google: konto Google Cloud z projektem, w którym włączysz Indexing API i utworzysz Service Account, oraz zweryfikowana usługa Search Console dla Twojej domeny

Instalacja

Krok 1: pobranie

Pobierz ZIP dfindexingapi-1.0.0.zip ze swojego konta DataFirefly po zakupie.

Krok 2: instalacja z back office

1. Zaloguj się do back office PrestaShop
2. Przejdź do Moduły › Menedżer modułów › Zainstaluj moduł
3. Kliknij Wybierz plik i wskaż pobrany ZIP
4. Zatwierdź. PrestaShop rozpakuje i zainstaluje moduł
5. Po instalacji kliknij Konfiguruj

Krok 3: weryfikacja po instalacji

Przy instalacji moduł tworzy automatycznie:

• Dwie tabele SQL ps_df_indexapi_queue (kolejka) i ps_df_indexapi_log (dziennik)
• 32-znakowy alfanumeryczny klucz IndexNow
• 32-znakowy losowy token CRON
• 5 zakładek w menu administracyjnym: nadrzędna DataFirefly Indexing API, a pod nią Pulpit, Kolejka, Dziennik, Konfiguracja

Otwórz zakładkę Konfiguracja, aby przejść do kolejnego kroku.

Konfiguracja IndexNow

IndexNow to kanał do skonfigurowania jako pierwszy: bez Service Account, bez OAuth, bez limitu i bez ograniczeń co do typu strony. Wystarczy klucz opublikowany w katalogu głównym Twojej domeny.

Jak działa IndexNow

IndexNow to otwarty protokół forsowany przez Microsoft Bing i Yandex w 2021 roku, do którego dołączyły później Naver i Seznam. Generujesz klucz alfanumeryczny, publikujesz go w katalogu głównym domeny jako publicznie dostępny plik i wywołujesz api.indexnow.org z listą adresów URL. Serwer weryfikuje klucz, odczytując plik z Twojej domeny, a następnie propaguje adresy do uczestniczących wyszukiwarek. Karty produktów, kategorie i strony CMS mieszczą się w jego normalnym zakresie.

Metoda 1: przepisanie w pliku htaccess (zalecana)

To najprostsza metoda: moduł sam serwuje zawartość pliku klucza przez kontroler frontowy, a reguła w pliku .htaccess w katalogu głównym sklepu przepisuje żądanie do tego kontrolera.

1. W konfiguracji modułu otwórz zakładkę IndexNow
2. Zaznacz Włącz IndexNow
3. Sprawdź pole Host, które musi odpowiadać domenie sklepu bez protokołu (na przykład moj-sklep.pl)
4. Zapisz
5. Skopiuj snippet .htaccess wyświetlony na stronie konfiguracji, generowany dynamicznie z Twoim bieżącym kluczem
6. Wklej ten snippet na górze pliku .htaccess w katalogu głównym PrestaShop, zaraz za blokiem RewriteEngine on
7. Kliknij Testuj IndexNow w konfiguracji: moduł wywoła adres pliku klucza w Twojej domenie i sprawdzi, czy zwraca oczekiwaną zawartość jako text/plain

Metoda 2: plik fizyczny

Jeśli nie możesz modyfikować pliku .htaccess, utwórz ręcznie plik fizyczny w katalogu głównym domeny.

1. Odczytaj swój klucz IndexNow z konfiguracji modułu (pole Klucz IndexNow)
2. Utwórz plik o nazwie dokładnie klucz + .txt (na przykład a1b2c3d4e5f6.txt) w katalogu głównym domeny
3. Zawartością pliku ma być wyłącznie sam klucz, bez znaku końca linii
4. Sprawdź, czy https://twoja-domena.pl/a1b2c3d4e5f6.txt zwraca klucz jako text/plain
5. Kliknij Testuj IndexNow

Konfiguracja Google Indexing API

Google Indexing API wymaga konta usługi Google Cloud. Procedura zajmuje około 5 minut.

Krok 1: utworzenie projektu Google Cloud

1. Wejdź na console.cloud.google.com i zaloguj się
2. U góry kliknij selektor projektu, a następnie Nowy projekt
3. Nadaj mu nazwę (na przykład Indexing API Sklep) i utwórz go
4. Wybierz nowo utworzony projekt

Krok 2: włączenie Indexing API

1. W menu po lewej przejdź do API i usługi › Biblioteka
2. Wyszukaj Indexing API
3. Kliknij Włącz

Krok 3: utworzenie Service Account

1. Przejdź do API i usługi › Dane logowania
2. Kliknij Utwórz dane logowania › Konto usługi
3. Nadaj mu nazwę (na przykład indexing-api-prestashop)
4. Żadna rola IAM nie jest potrzebna: przejdź do kolejnego kroku i zakończ tworzenie
5. Na liście kont usługi kliknij utworzone konto
6. Zakładka Klucze › Dodaj klucz › Utwórz nowy klucz
7. Format JSON. Pobierz i zachowaj plik, później nie będzie już możliwy do odzyskania

Krok 4: dodanie Service Account do Search Console

1. Skopiuj adres e-mail konta usługi (w postaci nazwa@projekt.iam.gserviceaccount.com) z Google Cloud
2. Wejdź do Google Search Console
3. Wybierz swoją usługę (domenę sklepu)
4. Przejdź do Ustawienia › Użytkownicy i uprawnienia
5. Kliknij Dodaj użytkownika, wklej adres konta usługi i wybierz rolę Właściciel
6. Zatwierdź

Krok 5: wklejenie JSON do modułu

1. Otwórz pobrany plik JSON w edytorze tekstu
2. Skopiuj całą jego zawartość
3. W konfiguracji modułu, sekcja Google Indexing API, zaznacz Włącz Google Indexing API
4. Wklej pełny JSON w pole Service Account JSON
5. Zapisz

Krok 6: test połączenia

Kliknij przycisk Testuj Google na stronie konfiguracji. Moduł podpisze JWT RS256, wymieni go na token OAuth2 i wyświetli wynik. Jeśli wszystko jest poprawne, zobaczysz zielony komunikat Uwierzytelnienie OK. Ten test weryfikuje uwierzytelnienie, a nie uwzględnienie Twoich adresów przez Google.

Konfiguracja CRON-a

CRON to element, który uruchamia przetwarzanie kolejki. Bez regularnie wywoływanego CRON-a zgłoszenia się piętrzą, ale nigdy nie wychodzą.

Akcja process: przetwarzanie kolejki

Wywoływać co 5 do 15 minut. Moduł przetwarza konfigurowalną partię (domyślnie 50 zadań) z poszanowaniem deduplikacji i filtrów indeksowania, a następnie aktualizuje dziennik i kolejkę.

Dokładny adres jest wyświetlany w konfiguracji. Wygląda tak:

https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=TWOJ_TOKEN

Akcja purge: czyszczenie dziennika

Wywoływać raz dziennie. Moduł usuwa przetworzone zadania i logi powyżej skonfigurowanej retencji (domyślnie 30 dni).

https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=TWOJ_TOKEN

Akcja key: plik klucza IndexNow

Używana wyłącznie przez przepisanie w pliku .htaccess. Tego adresu nigdy nie wywołujesz ręcznie.

Konfiguracja CRON-a systemowego

W Linuksie lub cPanelu dodaj dwie linie w crontab:

# Co 10 minut: przetwarzanie kolejki
*/10 * * * * curl -s "https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=TWOJ_TOKEN" > /dev/null

# Raz dziennie o 3:00: czyszczenie dziennika
0 3 * * * curl -s "https://twoja-domena.pl/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=TWOJ_TOKEN" > /dev/null

Bezpieczeństwo tokenu CRON

Token to 32-znakowy sekret generowany przy instalacji. Bez poprawnego tokenu w parametrze token= kontroler zwraca HTTP 403. Token możesz zregenerować w dowolnym momencie z konfiguracji (przycisk Zregeneruj token CRON), pamiętając wtedy o aktualizacji linii crontab nowym tokenem.

Pulpit

Zakładka Pulpit to Twój przegląd w czasie rzeczywistym. Mierzy techniczną kondycję wywołań API, a nie faktyczną indeksację Twoich stron.

Liczniki kolejki

Pięć kart u góry strony:

• Oczekujące: zadania utworzone, ale jeszcze nieprzetworzone
• W trakcie: zadania zablokowane w przetwarzaniu przez aktywny CRON
• Zgłoszone: zadania przetworzone pomyślnie (suma historyczna nieusunięta)
• Błąd: zadania, które zawiodły po N maksymalnych próbach
• Pominięte: zadania utworzone, ale pominięte przez filtr (na przykład URL_DELETED w IndexNow)

Diagnostyka dostawców

Dwie karty pokazują stan konfiguracji:

• Google Indexing API: aktywny, źle skonfigurowany albo wyłączony. Wskazuje, czy JSON Service Account jest obecny i poprawny
• IndexNow: aktywny, źle skonfigurowany albo wyłączony. Wskazuje, czy klucz i host są skonfigurowane

Wskaźnik akceptacji 30 dni

Tabela krzyżowa dostawca × status z ostatnich 30 dni, z kolorowaniem semantycznym: zielony powyżej 90 %, pomarańczowy między 60 a 90 %, czerwony poniżej. Jeśli Google spada poniżej 90 %, zwykle oznacza to przekroczenie limitu albo brak dostępności części adresów. Wskaźnik akceptacji 100 % oznacza, że Twoje powiadomienia zostały odebrane, a nie że adresy zostały zaindeksowane.

Wykres dziennych zgłoszeń

Wykres Chart.js nakładający dwie krzywe dzienne: łącznie zgłoszone i łącznie zaakceptowane. Przydatny do szybkiego wychwycenia spadków lub nietypowych szczytów.

Kolejka

Zakładka Kolejka listuje wszystkie zadania (pending, processing, submitted, error, skipped) z natywnymi filtrami PrestaShop po sklepie, typie obiektu, ID, dostawcy, statusie i dacie.

Statusy zadań

• pending: utworzone, oczekuje na przetworzenie przez kolejny CRON
• processing: zablokowane przez aktywny CRON (przejście logiczne zapobiegające podwójnemu przetwarzaniu równolegle)
• submitted: zgłoszenie do API powiodło się. Licznik prób jest zamrożony
• error: wszystkie próby zawiodły. Pozostaje do wglądu z dokładnym komunikatem błędu zwróconym przez API
• skipped: utworzone, a następnie pominięte (na przykład URL_DELETED w IndexNow albo wyłączony filtr)

Akcje indywidualne

Każdy wiersz oferuje:

• Ponów: przywraca zadanie do statusu pending i resetuje licznik prób
• Usuń: kasuje zadanie z kolejki

Akcje masowe

Przyciski u góry listy:

• Ponów wszystkie zadania w błędzie: przywraca do statusu pending wszystkie zadania ze statusem error
• Wyczyść przetworzone zadania: usuwa wszystkie submitted i skipped niezależnie od ich wieku

Dziennik

Zakładka Dziennik listuje każde wykonane zgłoszenie: dostawca, typ, ID obiektu, zgłoszony adres URL, akcja (URL_UPDATED albo URL_DELETED), zwrócony kod HTTP, wskaźnik zaakceptowane lub odrzucone, pełny komunikat odpowiedzi i data. Filtrowalny, sortowalny, eksportowalny do CSV przez standardowy HelperList PrestaShop.

Filtry indeksowania

W konfiguracji możesz niezależnie włączać i wyłączać trzy typy obiektów:

• Produkty: zgłoszenie przy utworzeniu, modyfikacji, usunięciu, dezaktywacji
• Kategorie: zgłoszenie przy utworzeniu, modyfikacji, usunięciu. Kategorie główne (ID 1 i 2) są pomijane dla bezpieczeństwa
• Strony CMS: zgłoszenie przy utworzeniu, modyfikacji, usunięciu

Wyłączenie filtra natychmiast zatrzymuje kolejkowanie dla tego typu, ale nie czyści istniejącej kolejki. Na dużym katalogu ograniczenie filtrów po stronie Google to właściwy odruch, aby nie wyczerpać limitu 200 adresów dziennie.

Multistore

Moduł jest natywnie wielosklepowy. Konfiguracja (klucze Google, klucz IndexNow, host, aktywacje) jest niezależna per podsklep. Zadania i logi są ograniczone po id_shop: ten sam produkt w dwóch podsklepach generuje dwa osobne zadania z własnymi adresami kanonicznymi.

Aby skonfigurować każdy podsklep niezależnie, użyj selektora multistore u góry panelu administracyjnego przed otwarciem konfiguracji.

Nasłuchiwane hooki PrestaShop

Moduł rejestruje przy instalacji następujące hooki:

• actionProductSave: utworzenie lub modyfikacja produktu. Jeśli aktywny, kolejkuje URL_UPDATED, w przeciwnym razie URL_DELETED
• actionProductDelete: trwałe usunięcie produktu. Kolejkuje URL_DELETED
• actionObjectCmsAddAfter: utworzenie strony CMS
• actionObjectCmsUpdateAfter: modyfikacja strony CMS
• actionObjectCmsDeleteAfter: usunięcie strony CMS
• actionCategoryAdd: utworzenie kategorii
• actionCategoryUpdate: modyfikacja kategorii
• actionCategoryDelete: usunięcie kategorii
• displayBackOfficeHeader: wstrzyknięcie fragmentu CSS do stylizacji pulpitu

Każdy hook buduje adres kanoniczny przez oficjalny obiekt Link PrestaShop, co respektuje Twoje ustawienia przyjaznych adresów SEO i wielojęzyczne prefiksy językowe.

Rozwiązywanie problemów

Test Google kończy się kodem 401

Uwierzytelnienie się nie powiodło. Sprawdź, czy:

• Wklejony JSON Service Account jest kompletny i poprawnie sformowany
• Indexing API jest faktycznie włączone w Google Cloud (biblioteka)
• Zegar systemowy serwera jest poprawny: przesunięcie większe niż 5 minut unieważnia JWT

Test Google kończy się kodem 403

Uwierzytelnienie się udaje, ale Google odrzuca żądanie. Typowa przyczyna: Service Account nie został dodany jako Właściciel usługi w Search Console. Zweryfikuj ponownie krok 4 konfiguracji Google.

Test IndexNow kończy się niepowodzeniem

Serwer api.indexnow.org nie mógł odczytać pliku klucza w Twojej domenie. Możliwe przyczyny:

• Snippet .htaccess nie został wklejony albo został wklejony w złym miejscu (musi być po RewriteEngine on)
• Plik fizyczny nie został utworzony albo nie ma poprawnej nazwy (musi to być dokładnie klucz + .txt)
• Zawartość pliku nie odpowiada kluczowi (literówka, dodatkowy znak końca linii)
• Serwer WWW serwuje plik z niewłaściwym Content-Type (musi być text/plain)
• Firewall albo CDN blokuje żądania robota IndexNow

Otwórz https://twoja-domena.pl/TWOJ_KLUCZ.txt w przeglądarce w trybie prywatnym: powinieneś zobaczyć wyłącznie klucz jako czysty tekst.

Zadania utykają w statusie processing

Oznacza to, że CRON zablokował zadania, ale nigdy nie zwolnił blokady (na przykład proces został ubity przez timeout PHP). Możesz je odblokować ręcznie przez phpMyAdmin:

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

Jeśli problem powtarza się regularnie, zwiększ max_execution_time PHP na swoim hostingu albo zmniejsz rozmiar partii w konfiguracji modułu.

Limit Google został przekroczony

Google odpowiada kodem 429 albo komunikatem Quota exceeded. Domyślny limit to 200 adresów dziennie na Service Account.

Trzy realistyczne opcje:

• Odczekać 24 h, limit resetuje się codziennie
• Ograniczyć filtry indeksowania po stronie Google do typów, które naprawdę się dla Ciebie liczą (na przykład same produkty, z wyłączeniem kategorii i CMS)
• Utworzyć drugie Service Account i naprzemiennie z nich korzystać, każde ma własny limit 200 adresów dziennie

Przypomnienie: IndexNow nie ma żadnego limitu. Jeśli wolumen jest Twoim głównym ograniczeniem, to na tym kanale należy się oprzeć.

Pełny reset

Aby zacząć od zera (przydatne przy migracji albo złożonym problemie):

1. Odinstaluj moduł z Moduły › Menedżer
2. Zainstaluj ponownie: tabele zostaną odtworzone, a klucz IndexNow i token CRON zregenerowane
3. Skonfiguruj ponownie Google i IndexNow
4. Zaktualizuj snippet .htaccess nowym kluczem
5. Zaktualizuj linie crontab nowym tokenem

Znane ograniczenia

• Google Indexing API oficjalnie ograniczone do stron JobPosting albo BroadcastEvent w VideoObject. API przyjmuje inne typy i odpowiada 200, ale ten kod potwierdza wyłącznie odebranie powiadomienia. Dla katalogu produktowego IndexNow jest kanałem głównym, a Google uzupełnieniem zapisywanym w dzienniku
• Limit Google zamknięty na 200 adresach dziennie na Service Account, bez realnej możliwości zwiększenia dla e-commerce (patrz sekcja Rozwiązywanie problemów)
• IndexNow nie obsługuje URL_DELETED: protokół zakłada, że 404 albo 410 na adresie jest właściwym sposobem zasygnalizowania usunięcia. Moduł pomija więc zadania IndexNow z URL_DELETED (Google z kolei je zgłasza)
• Warianty produktu nie są zgłaszane osobno: adres kanoniczny produktu głównego wystarcza, Google naturalnie konsoliduje warianty
• Kategorie główne pomijane (ID 1 i 2), aby nie zgłaszać nieistotnych adresów
• Moduł nie zastępuje sitemapy XML: sitemapa pozostaje oficjalnym kanałem odkrywania i musi być czysta i aktualna. Bezpośrednie zgłaszanie dokłada się do niej, a nie ją zastępuje

Wsparcie

W sprawach technicznych: support@datafirefly.com, odpowiedź w ciągu 24 godzin roboczych po francusku lub angielsku. W cenie przez 12 miesięcy po zakupie.