# Shoppable Galeria Zdjęć Klientów: kompletny przewodnik

> Prezentacja Shoppable Galeria Zdjęć Klientów (dfugcgallery) wyświetla prawdziwe zdjęcia Twoich klientów na stronie głównej i pod kartami produktów, z klikalnymi hotspotami prowadzącymi do produktów widocznych na każdym zdjęciu. Zdjęcia pochodzą…

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

## Prezentacja

Shoppable Galeria Zdjęć Klientów (`dfugcgallery`) wyświetla prawdziwe zdjęcia Twoich klientów na stronie głównej i pod kartami produktów, z klikalnymi hotspotami prowadzącymi do produktów widocznych na każdym zdjęciu. Zdjęcia pochodzą z dwóch źródeł: uploadu zalogowanych klientów (zweryfikowani kupujący) oraz importu Twoich publikacji z Instagrama przez oficjalne API. Wszystko przechodzi przez kolejkę moderacji w zapleczu, gdzie umieszczasz też hotspoty produktowe.

## Instalacja

1. W panelu administracyjnym PrestaShop przejdź do **Moduły → Menedżer modułów → Zainstaluj moduł**.
2. Wybierz plik `dfugcgallery.zip` i zatwierdź.
3. Moduł automatycznie tworzy dwie tabele bazy danych, zakładkę administracyjną **Galeria UGC** (w sekcji Katalog) oraz zabezpieczony folder przechowywania obrazów.
4. Kliknij **Konfiguruj**, aby otworzyć ustawienia.

Moduł jest zgodny z PrestaShop 8.0 do 8.2 i 9.x, PHP minimum 8.0. Nie tworzy żadnego override i używa tylko natywnych hooków: `displayHome`, `displayFooterProduct`, `displayCustomerAccount` i `displayHeader`.

## Konfiguracja

Strona konfiguracji modułu skupia wszystkie ustawienia:

- **Galeria na stronie głównej**: włączenie i maksymalna liczba wyświetlanych zdjęć.
- **Galeria na karcie produktu**: włączenie i maksymalna liczba zdjęć w pasku pod każdą kartą.
- **Auto-akceptacja**: jeśli włączona, uploady klientów są publikowane natychmiast bez moderacji. Importy z Instagrama zawsze przechodzą moderację, niezależnie od tego ustawienia.
- **Maksymalny rozmiar pliku**: w megabajtach, stosowany do każdego wgrywanego zdjęcia.
- **Token Instagram**: token long-lived umożliwiający import Twoich publikacji (patrz następna sekcja).

## Połączenie z Instagramem

Import używa oficjalnego API „Instagram API with Instagram Login". Wymagana jest jednorazowa konfiguracja:

1. Wejdź na portal deweloperski Meta i utwórz aplikację typu Business.
2. Dodaj produkt **Instagram** i skonfiguruj „API setup with Instagram login".
3. Powiąż profesjonalne konto Instagram Twojego sklepu.
4. Wygeneruj **token long-lived** z uprawnieniem `instagram_business_basic`.
5. Wklej ten token w pole **Token Instagram** konfiguracji modułu i zapisz.

Moduł automatycznie odświeża token przed każdym importem. Dopóki uruchamiasz import co najmniej raz na 60 dni, token nigdy nie wygasa i nie musisz go już dotykać.

Aby importować, otwórz **Katalog → Galeria UGC** i kliknij przycisk **Importuj z Instagrama** na pasku narzędzi. Moduł pobiera Twoje ostatnie publikacje, pomija już zaimportowane duplikaty (deduplikacja po identyfikatorze mediów), bierze pierwszy obraz z karuzel i umieszcza wszystko w statusie „Oczekujące". Wideo i Reels są w tej wersji pomijane.

## Upload przez klientów

Zalogowani klienci mają link **Moje zdjęcia** w swoim koncie klienta. Strona wysyłki pozwala im:

- wysłać do 5 zdjęć na jedno zgłoszenie (jpg, png lub webp);
- opcjonalnie powiązać produkt, lista proponuje wyłącznie produkty z ich ważnych zamówień, co gwarantuje, że każde otagowane zdjęcie pochodzi od zweryfikowanego kupującego;
- dodać podpis;
- sprawdzać status swoich zdjęć (oczekujące, zaakceptowane, odrzucone) i usuwać je w każdej chwili.

Przed każdą wysyłką obowiązkowe jest wyraźne pole zgody. Usunięcie przez klienta kasuje pliki z serwera, nie tylko wpis w bazie: moduł jest zaprojektowany pod zgodność z RODO.

## Moderacja

Lista **Katalog → Galeria UGC** pokazuje wszystkie zdjęcia z miniaturą, źródłem (Upload lub Instagram), autorem, statusem i datą. Możesz:

- filtrować po źródle i statusie;
- akceptować, odrzucać lub usuwać każde zdjęcie jednym kliknięciem z akcji wiersza;
- stosować te akcje masowo przez pola wyboru;
- otwierać edytor hotspotów akcją **Zobacz**.

Tylko zaakceptowane zdjęcia pojawiają się w sklepie.

## Edytor hotspotów

Edytor pozwala powiązać produkty z konkretnymi miejscami na każdym zdjęciu:

1. Wyszukaj produkt po nazwie, indeksie lub identyfikatorze w polu wyszukiwania.
2. Wybierz go, a następnie **kliknij na zdjęciu** w wybranym miejscu, aby umieścić punkt.
3. Przeciągnij istniejący punkt, aby zmienić jego pozycję.
4. W razie potrzeby usuń punkt z listy bocznej.
5. Kliknij **Zapisz**, aby zachować pozycje.

Pozycje są zapisywane w procentach szerokości i wysokości obrazu: render jest identyczny na mobile, tablecie i desktopie. Po stronie sklepu każdy punkt dyskretnie pulsuje i po kliknięciu otwiera kartę produktu z nazwą, aktualną ceną sformatowaną według waluty odwiedzającego, obrazem głównym i bezpośrednim linkiem do karty.

Gdy klient otaguje produkt przy uploadzie, hotspot tworzony jest automatycznie na środku zdjęcia. Wystarczy przesunąć go we właściwe miejsce podczas moderacji.

## Wyświetlanie w sklepie

- **Strona główna**: responsywna siatka z odznaką liczby otagowanych produktów per zdjęcie i przyciskiem zachęty do dzielenia się.
- **Karta produktu**: poziomy pasek zdjęć klientów powiązanych z przeglądanym produktem.
- **Lightbox**: pełny ekran, nawigacja strzałkami i klawiaturą, animowane hotspoty, respektowana preferencja `prefers-reduced-motion`.

JavaScript frontu jest w vanilla, bez jQuery, a assety ładują się tylko na odpowiednich stronach. Obrazy są rekodowane do JPEG w dwóch rozmiarach (1600 px i miniatura 600 px) dla zachowania wydajności.

## Rozwiązywanie problemów

- **Import z Instagrama kończy się błędem**: sprawdź, czy token to ważny token long-lived powiązany z kontem profesjonalnym i czy uprawnienie odczytu mediów jest nadane. Wygasły token (ponad 60 dni bez importu) trzeba wygenerować ponownie z portalu Meta.
- **Wgrywane zdjęcie jest odrzucane przy wysyłce**: sprawdź format (tylko jpg, png, webp) oraz skonfigurowany maksymalny rozmiar.
- **Zdjęcia nie pojawiają się w sklepie**: wyświetlane są tylko zdjęcia w statusie „Zaakceptowane"; sprawdź też, czy dana galeria (strona główna lub karta produktu) jest włączona w konfiguracji.
- **Multisklep**: każdy sklep zarządza własną galerią; sprawdź wybrany kontekst sklepu w zapleczu.

## Deinstalacja

Deinstalacja usuwa tabele modułu, jego zakładkę administracyjną i konfigurację. Pliki obrazów z folderu uploadu również są usuwane razem ze skasowanymi zdjęciami.