# DataFirefly Allergens & Ingredients: kompletny przewodnik

> Prezentacja DataFirefly Allergens & Ingredients dostosowuje twój sklep PrestaShop 8 albo 9 do rozporządzenia (UE) nr 1169/2011: wyświetla 14 alergenów z załącznika II, strukturalną listę składników z automatycznym wyróżnianiem alergenów…

- Strona: <https://www.datafirefly.com/pl/documentation/dfallergens/>
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfallergens/index.md), [en](https://www.datafirefly.com/en/documentation/dfallergens/index.md), [es](https://www.datafirefly.com/es/documentation/dfallergens/index.md), [de](https://www.datafirefly.com/de/documentation/dfallergens/index.md), [it](https://www.datafirefly.com/it/documentation/dfallergens/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfallergens/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfallergens/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## Prezentacja

DataFirefly Allergens & Ingredients dostosowuje twój sklep PrestaShop 8 albo 9 do rozporządzenia (UE) nr 1169/2011: wyświetla 14 alergenów z załącznika II, strukturalną listę składników z automatycznym wyróżnianiem alergenów (artykuł 21) oraz udostępnia informację przed zakupem, czego wymaga artykuł 14 dla sprzedaży na odległość.

Moduł dokłada dwa wyróżniki: osobisty profil alergenów dla każdego klienta z alertem w czasie rzeczywistym na kartach produktu oraz automatyczne wzbogacenie Schema.org JSON-LD pod widoczność w wyszukiwarce.

## Wymagania i zgodność

- PrestaShop od 8.0.0 do 9.99.99
- PHP minimum 8.0
- MySQL 5.7+ albo MariaDB 10.3+
- Zgodny z multisklepem i wielojęzycznością
- Języki w zestawie: francuski, angielski, hiszpański, niemiecki

## Instalacja

1. W back office otwórz **Moduły → Menedżer modułów**.
2. Kliknij **Zainstaluj moduł** i wskaż plik `dfallergens-1.0.0.zip`.
3. Kliknij **Instaluj**. Moduł tworzy 5 tabel z prefiksem `df_` i wczytuje 14 alergenów z załącznika II w 4 językach.
4. W menu Moduły pojawia się nowa zakładka **DataFirefly Allergens** do zarządzania taksonomią alergenów.

Przy instalacji 14 oficjalnych alergenów jest wczytywanych wraz z ikonami SVG i nazwami po francusku, angielsku, hiszpańsku i niemiecku. Nie musisz wprowadzać niczego ręcznie.

## Konfiguracja

Otwórz **Moduły → Menedżer modułów → DataFirefly Allergens & Ingredients → Konfiguruj**. Dostępnych jest sześć ustawień:

- **Styl wyróżnienia**: sposób oznaczania alergenów na liście składników: pogrubienie (zalecane), wersaliki, podkreślenie albo kolor. Pogrubienie to najczęstszy styl na etykietach fizycznych.
- **Pokaż ikony**: włącza albo wyłącza piktogramy SVG obok nazwy każdego alergenu.
- **Pokaż ślady**: pokazuje albo ukrywa sekcję „Może zawierać śladowe ilości” (artykuł 36 ustęp 3).
- **Znaczniki JSON-LD**: wstrzykuje znaczniki Schema.org do sekcji head na objętych kartach produktu.
- **Profil klienta**: włącza funkcję profilu alergenów w koncie klienta oraz alerty na karcie produktu.
- **Pozycja wyświetlania**: osobna zakładka na karcie produktu, pod opisem albo pod ceną.

## Deklarowanie alergenów produktu

1. Otwórz kartę produktu w back office i przejdź do zakładki **Moduły** (PrestaShop 8) albo do sekcji modułu (PrestaShop 9).
2. W panelu **DataFirefly Allergens** każdy alergen ma trzy stany: _nie dotyczy_ (domyślny), _Zawiera_ albo _Ślady_.
3. Wybierz **Zawiera** dla alergenów obecnych w recepturze, a **Ślady** dla możliwych zanieczyszczeń krzyżowych.
4. Uzupełnij **listę składników** naturalnym językiem, w kolejności malejącej ilości, jak wymaga tego przepis. Moduł automatycznie wykrywa i wyróżnia alergeny oraz ich synonimy.
5. Opcjonalnie uzupełnij **pochodzenie** i **warunki przechowywania**.
6. Zapisz produkt.

Pola składników, pochodzenia i przechowywania są zapisywane per język i per sklep: przełączaj się selektorem języka na karcie produktu, żeby wprowadzić każdą wersję.

## Automatyczne wykrywanie po synonimach

Wyróżnianie nie ogranicza się do oficjalnej nazwy alergenu. Wewnętrzny słownik rozpoznaje popularne warianty w czterech językach:

- **Mleko**: mleko, masło, śmietana, kazeina, serwatka, laktoza
- **Gluten**: pszenica, orkisz, jęczmień, żyto, owies, kamut, słód
- **Siarczyny**: SO2, dwutlenek siarki, E220 do E228
- **Orzechy**: migdał, orzech laskowy, orzech włoski, nerkowiec, pekan, pistacja, makadamia

Wykrywanie stosuje granice słów zgodne z Unicode: francuskie „blé” jest wykrywane w „farine de blé”, ale nie w „établi”.

Słownik synonimów obejmuje francuski, angielski, hiszpański i niemiecki. Polskie nazwy składników nie są w nim zawarte, więc w polskiej liście składników używaj oficjalnych nazw alergenów z taksonomii modułu, żeby wyróżnienie zadziałało. Nazwy alergenów w polskim interfejsie uzupełnisz w menu DataFirefly Allergens, po dodaniu polskiego do języków sklepu.

## Profil alergenów klienta

Przy włączonej opcji każdy zalogowany klient ma w swoim koncie sekcję **Moje alergeny**. Wybiera w niej swoje alergeny i poziom nasilenia: do unikania, nietolerancja, ciężki albo anafilaktyczny.

Na każdej karcie produktu moduł porównuje zadeklarowane alergeny produktu z profilem klienta. Przy konflikcie nad ceną wyświetla się czerwony pasek alertu ze wskazaniem alergenu i zapisanego poziomu nasilenia.

Profil klienta to usługa wspomagająca decyzję. Nie zastępuje ani etykietowania wymaganego przepisami, ani czujności konsumenta: zawsze wyświetlaj pełną listę alergenów na każdej karcie.

## Znaczniki Schema.org JSON-LD

Kiedy produkt ma co najmniej jeden zadeklarowany alergen albo listę składników, moduł automatycznie wstrzykuje do sekcji head skrypt JSON-LD zawierający:

- `ingredients`: listę składników jako zwykły tekst
- `suitableForDiet`: wywnioskowane zgodne diety (na przykład GlutenFreeDiet, jeśli nie zadeklarowano alergenu glutenowego)
- `additionalProperty`: każdy alergen z propertyID INCO-1169-2011 i jego poziomem (zawiera albo ślady)

Znaczniki są generowane po stronie serwera w PHP, bez szablonu, z zabezpieczeniem przed wstrzyknięciami.

## Zarządzanie taksonomią alergenów

Menu **DataFirefly Allergens** w back office pozwala zmieniać nazwy i opisy 14 alergenów w każdym języku, włączać je i wyłączać pojedynczo oraz zmieniać ich kolejność wyświetlania. Domyślna kolejność odpowiada numeracji z załącznika II.

## Rozwiązywanie problemów

- **Blok alergenów się nie wyświetla**: sprawdź, czy produkt ma co najmniej jeden zadeklarowany alergen albo listę składników, oraz czy skonfigurowana pozycja wyświetlania odpowiada hookowi obsługiwanemu przez twój szablon.
- **Wszystkie alergeny pokazują się jako „Zawiera”**: upewnij się, że używasz finalnej wersji 1.0.0 modułu. Wyczyść dane produktu testowego, przestawiając wszystkie selektory na „nie dotyczy” i zapisując.
- **Wyróżnienie nie działa na jakimś terminie**: termin może nie występować w słowniku synonimów. Użyj oficjalnej nazwy alergenu na liście składników.
- **JSON-LD się nie pojawia**: sprawdź, czy opcja jest włączona w konfiguracji, i przejrzyj kod źródłowy karty produktu, szukając ciągu INCO-1169-2011.

## Deinstalacja

Deinstalacja usuwa 5 tabel modułu oraz wszystkie powiązane dane alergenów, składników i profili klientów. W razie potrzeby wcześniej wyeksportuj swoje dane.

## Odpowiedzialność prawna

Moduł dostarcza techniczne narzędzia wyświetlania. Zgodnie z artykułem 8 rozporządzenia 1169/2011 odpowiedzialność za prawidłowość informacji o żywności spoczywa na podmiocie działającym na rynku spożywczym, czyli na sprzedawcy.