dfgoogletryon: moduł wirtualnej przymierzalni AI (Google Vertex AI)

Prezentacja

dfgoogletryon dodaje widżet wirtualnej przymierzalni na kartach produktów PrestaShop 8 i 9. Klient przesyła zdjęcie (lub korzysta z kamery) i widzi siebie w ubraniu z karty produktu, dzięki generatywnemu modelowi Google Vertex AI Virtual Try-On. Wszystkie wywołania do Google są proxowane po stronie serwera: klucz konta usługi nigdy nie trafia do przeglądarki. Moduł obejmuje zgodę RODO, brak przechowywania zdjęć, znak wodny SynthID oraz zabezpieczenia przed niekontrolowanymi kosztami.

Czym to się różni od try-on w Google Shopping?

Google oferuje dwie różne rzeczy, których nie należy mylić:

• Przymierzanie odzieży w Merchant Center: znaczek widoczny wyłącznie w wyszukiwarce Google i Google Shopping. Nie da się go osadzić w Twoim sklepie i nie udostępnia żadnego API dla karty produktu.
• Vertex AI Virtual Try-On: generatywne API, z którego korzysta ten moduł. To jedyny element pozwalający na widżet przymierzania bezpośrednio na stronach produktów.

Wymagania

• PrestaShop 8.0 do 9.x
• PHP 8.1, 8.2, 8.3 lub 8.4
• Rozszerzenia PHP: curl, openssl, gd
• Projekt Google Cloud z aktywnym rozliczaniem
• Włączone API Vertex AI w tym projekcie
• Konto usługi z rolą Użytkownik Vertex AI oraz jego klucz JSON

Krok 1: przygotowanie Google Cloud

1. Otwórz console.cloud.google.com i utwórz (lub wybierz) projekt. Zanotuj jego identyfikator projektu.
2. Włącz rozliczanie w projekcie (menu Płatności).
3. Włącz API Vertex AI: wyszukaj „Vertex AI API” (aiplatform.googleapis.com) w bibliotece interfejsów API i kliknij Włącz.

Krok 2: utworzenie konta usługi

1. Przejdź do Administracja > Konta usługi.
2. Kliknij Utwórz konto usługi i nadaj mu nazwę (na przykład tryon-prestashop).
3. Przypisz mu rolę Użytkownik Vertex AI (roles/aiplatform.user).
4. Po utworzeniu otwórz je, zakładka Klucze > Dodaj klucz > Utwórz klucz > JSON. Plik JSON zostanie pobrany.

Krok 3: instalacja modułu

1. Pobierz dfgoogletryon.zip ze swojego konta klienta.
2. W panelu administracyjnym PrestaShop: Moduły > Menedżer modułów > Załaduj moduł.
3. Prześlij plik ZIP i kliknij Zainstaluj.
4. Podczas instalacji moduł zapisuje ustawienia domyślne oraz tekst zgody, a następnie podpina się pod hooki displayProductAdditionalInfo (przycisk na karcie produktu) i actionFrontControllerSetMedia (ładowanie zasobów, tylko na stronie produktu).

Krok 4: konfiguracja modułu

Otwórz konfigurację modułu. Wypełnij sekcję Google Cloud / Vertex AI:

• GCP Project ID: identyfikator projektu zanotowany w kroku 1.
• Region: lokalizacja Vertex AI, na przykład us-central1.
• Model ID: domyślnie virtual-try-on-preview-08-04 (można też użyć virtual-try-on-001).
• Service-account JSON key: wklej pełną zawartość pliku JSON pobranego w kroku 2.

Następnie kliknij Save & test authentication. Moduł podpisuje JWT, uzyskuje token OAuth i potwierdza komunikatem „Authentication OK”, jeśli wszystko jest poprawne.

Ustawienia generowania i bezpieczeństwa

Sekcja Generation & safety:

• Images per try-on: od 1 do 4 obrazów generowanych na przymierzanie. Każdy obraz jest rozliczany przez Google.
• SynthID watermark: dodaje niewidoczny znak wodny AI do wygenerowanych obrazów (zalecane).
• Safety setting: poziom filtrowania (block_low_and_above, block_medium_and_above, block_only_high, block_none). Domyślnie block_medium_and_above.
• Person generation: allow_adult zalecane dla sklepu odzieżowego.
• Max generations per session: limit generowań na sesję klienta, chroniący przed nadużyciami.
• Cooldown between generations (seconds): minimalny odstęp między dwoma przymierzeniami w tej samej sesji.

Sekcja Display:

• Enable widget: włącza lub wyłącza widżet globalnie.
• Restrict to category IDs: lista identyfikatorów kategorii oddzielonych przecinkami. Zostaw puste, aby wyświetlać na wszystkich produktach, albo wpisz kategorie odzieżowe, aby widżet pojawiał się tylko tam, gdzie ma sens.
• Consent text (GDPR): tekst wyświetlany obok obowiązkowego pola zgody.

Działanie po stronie klienta

1. Na kwalifikującej się karcie produktu pojawia się przycisk Try it on.
2. Klient otwiera okno modalne, przesyła zdjęcie (JPEG, PNG lub WebP) albo robi zdjęcie kamerą.
3. Zdjęcie jest zmniejszane w przeglądarce (maks. 1024 px, JPEG) przed wysłaniem, co redukuje opóźnienie i koszt.
4. Klient zaznacza pole zgody, a następnie klika Generate try-on.
5. Moduł przekazuje zdjęcie oraz obraz okładkowy produktu do Vertex AI, po czym wyświetla wygenerowane obrazy.

Prywatność i RODO

Kontrola kosztów

Każdy wygenerowany obraz jest rozliczany przez Google zgodnie z cennikiem Vertex AI za obraz. Aby koszty pozostały przewidywalne:

• Ogranicz Images per try-on do 1 na początek.
• Ustaw rozsądny Max generations per session (domyślnie 5).
• Korzystaj z Cooldown, aby zapobiec spamowaniu generowaniem.
• Ogranicz wyświetlanie do kategorii odzieżowych przez Restrict to category IDs.

Dobre praktyki dla zdjęcia produktu

Moduł wysyła obraz okładkowy produktu jako referencję ubrania. Jakość przymierzania jest znacznie lepsza przy czystym packshocie ubrania (neutralne tło, dobrze widoczny produkt) niż przy zdjęciu lifestylowym z modelem. Najlepsze rezultaty dają góry, doły oraz części jednoczęściowe (sukienki).

Rozwiązywanie problemów

• „Authentication failed” przy teście: sprawdź identyfikator projektu, poprawność klucza JSON, włączenie API Vertex AI oraz rolę Użytkownik Vertex AI na koncie usługi.
• Brak wygenerowanych obrazów: żądanie mogło zostać odfiltrowane przez ustawienia bezpieczeństwa. Spróbuj innego zdjęcia albo złagodź Safety setting. Sprawdź też saldo rozliczeń Google Cloud.
• Przycisk się nie pojawia: upewnij się, że Enable widget jest włączone i że produkt należy do dozwolonej kategorii (pole Restrict to category IDs).
• Błąd sieci / timeout: upewnij się, że serwer pozwala na wychodzące połączenia HTTPS do oauth2.googleapis.com i REGION-aiplatform.googleapis.com.
• „You have reached the maximum number of try-ons”: osiągnięto limit na sesję; to oczekiwane zachowanie. W razie potrzeby dostosuj Max generations per session.

Odinstalowanie

Odinstalowanie usuwa ustawienia modułu, w tym klucz konta usługi i zbuforowany token. Moduł nie przechowuje żadnych zdjęć klientów, więc nie ma nic więcej do wyczyszczenia.