# Wirtualna przymierzalnia AI dla WooCommerce: dokumentacja

> Co robi wtyczka DF Google Try-On dodaje przycisk wirtualnej przymierzalni na kartach produktów WooCommerce. Klientka wgrywa zdjęcie albo używa kamery internetowej, a sztuczna inteligencja generuje obraz przedstawiający ją w danym…

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

## Co robi wtyczka

DF Google Try-On dodaje przycisk wirtualnej przymierzalni na kartach produktów WooCommerce. Klientka wgrywa zdjęcie albo używa kamery internetowej, a sztuczna inteligencja generuje obraz przedstawiający ją w danym ubraniu. Podgląd wyświetla się w modalu, bez opuszczania karty produktu.

**Ważne:** ta wtyczka korzysta z deweloperskiego API _Vertex AI Virtual Try-On_ od Google Cloud. To nie jest konsumencka przymierzalnia widoczna w Google Search i Google Shopping, której nie da się osadzić na witrynie zewnętrznej. Każde wygenerowanie obrazu jest płatne po stronie Google.

## Wymagania

- WordPress 6.2 lub nowszy, WooCommerce 7.0 lub nowszy
- PHP 7.4 lub nowszy, z włączonym rozszerzeniem OpenSSL
- Projekt Google Cloud z aktywnym rozliczeniem
- Włączone API Vertex AI w tym projekcie
- Konto usługi z rolą _Vertex AI User_

## Krok 1: przygotowanie Google Cloud

### Włączenie API Vertex AI

W konsoli Google Cloud wybierz swój projekt, przejdź do biblioteki API i włącz _Vertex AI API_. Sprawdź, czy rozliczenie w projekcie jest aktywne: bez niego wszystkie wywołania zakończą się niepowodzeniem.

### Utworzenie konta usługi

1. Otwórz sekcję IAM i administracja, a następnie Konta usługi.
2. Utwórz konto usługi (nazwa nie ma znaczenia, na przykład _woocommerce-tryon_).
3. Przypisz mu rolę **Vertex AI User**. Nie nadawaj szerszej roli, niż to konieczne.
4. W zakładce Klucze utwórz klucz typu JSON i pobierz plik.

Ten plik JSON zawiera klucz prywatny. Traktuj go jak hasło: nie umieszczaj w repozytorium, nie udostępniaj i ogranicz dostęp do swojej administracji WordPressa.

### Wybór regionu

Model musi być dostępny w regionie, który wskażesz. Wartość domyślna _us-central1_ jest najbezpieczniejsza. Jeśli chcesz region europejski, sprawdź wcześniej dostępność modelu Virtual Try-On w dokumentacji Google, ponieważ pokrycie regionalne się zmienia.

## Krok 2: instalacja wtyczki

1. W WordPressie przejdź do Wtyczki, Dodaj nową, Wyślij wtyczkę na serwer.
2. Wybierz dostarczony plik ZIP, zainstaluj i włącz.
3. Pojawia się nowe menu: WooCommerce, Google Try-On.

## Krok 3: konfiguracja

Wszystkie ustawienia znajdują się w WooCommerce, Google Try-On.

### Połączenie z Google

- **Identyfikator projektu GCP**: identyfikator projektu, a nie jego nazwa wyświetlana.
- **Region**: na przykład _us-central1_.
- **JSON konta usługi**: wklej całą zawartość pobranego pliku. Wtyczka waliduje JSON przy zapisie i odrzuca źle sformowany klucz.

Przy zapisie cache tokenu dostępu jest automatycznie czyszczony: zmiana klucza jest więc uwzględniana natychmiast.

### Wyświetlanie

- **Włącz przymierzalnię**: przełącznik główny. Dopóki jest odznaczony, po stronie sklepu nic się nie wyświetla.
- **Etykieta przycisku**: tekst wyświetlany na karcie produktu.
- **Kwalifikujące się kategorie**: ogranicza widżet do wybranych kategorii. Zostaw puste, aby dopuścić wszystkie produkty.

### Bezpieczeństwo i koszty

- **Filtr bezpieczeństwa**: poziom filtrowania stosowany przez Google do obrazów. Na sklepie publicznym zalecane jest ustawienie najbardziej restrykcyjne.
- **Znak wodny**: dodaje do generowanych obrazów znak wodny SynthID od Google. Zalecane, aby zasygnalizować, że to obraz syntetyczny.
- **Limit miesięczny**: maksymalna liczba udanych przymiarek w miesiącu kalendarzowym. Ustaw 0, aby nie limitować, ale pamiętaj, że każde wygenerowanie jest płatne.
- **Tekst zgody**: komunikat wyświetlany obok obowiązkowego pola wyboru.

Licznik bieżącego miesiąca wyświetlany jest u góry strony ustawień.

## Krok 4: sterowanie wyświetlaniem produkt po produkcie

Na karcie produktu, w zakładce Ogólne danych produktu, ustawienie _Wirtualna przymierzalnia_ oferuje trzy wartości:

- **Auto**: podąża za kategoriami skonfigurowanymi globalnie.
- **Zawsze wyświetlaj**: wymusza wyświetlenie, nawet poza kwalifikującymi się kategoriami.
- **Nigdy nie wyświetlaj**: ukrywa widżet niezależnie od konfiguracji globalnej.

Ubranie wysyłane do AI to główne zdjęcie produktu, pobierane po stronie serwera. Ostre zdjęcie samego ubrania, dobrze wyodrębnione i na jasnym tle, daje znacznie lepsze rezultaty niż zdjęcie na modelce albo rozbudowana aranżacja.

## Jak to działa od strony technicznej

Ścieżka przymiarki wygląda tak:

1. Klientka otwiera modal i podaje zdjęcie, przez wgranie albo przechwycenie z kamery. Obraz jest skalowany w przeglądarce, po dłuższym boku, przed jakimkolwiek wysłaniem.
2. Zaznacza obowiązkowe pole zgody: bez niego serwer odrzuca żądanie.
3. Serwer weryfikuje token bezpieczeństwa, produkt, ograniczenie per adres IP i limit miesięczny.
4. Wtyczka podpisuje token JWT w RS256 kluczem prywatnym konta usługi, wymienia go na token dostępu OAuth2, a następnie cache'uje aż do zbliżającego się wygaśnięcia.
5. Zdjęcie i obraz produktu trafiają do modelu Vertex AI, który zwraca wygenerowany obraz.
6. Obraz wraca do przeglądarki i wyświetla się w modalu.

Obraz ubrania nigdy nie pochodzi z przeglądarki: zawsze jest odczytywany po stronie serwera z karty produktu. To uniemożliwia odwiedzającemu wykorzystanie usługi do przymierzenia dowolnego obrazu.

## Dane osobowe i RODO

Zdjęcie klientki jest daną osobową. Wtyczka jest odpowiednio zaprojektowana:

- Zdjęcie nigdy nie jest zapisywane na Twoim serwerze, ani w bibliotece mediów, ani w bazie danych. Przechodzi przez pamięć na czas wywołania.
- Wygenerowany obraz wraca wprost do przeglądarki i również nie jest przechowywany.
- Przed jakimkolwiek przetwarzaniem należy zaznaczyć wyraźne pole zgody, którego treść sam redagujesz.
- Zdjęcie przekazywane jest do Google, które działa jako podmiot przetwarzający. Wspomnij o tym transferze w swojej polityce prywatności, wskazując cel i odbiorcę.

Wtyczka nie przechowuje żadnych obrazów, ale to na Tobie spoczywa udokumentowanie tego przetwarzania w rejestrze i polityce prywatności oraz sprawdzenie warunków korzystania z Google Cloud obowiązujących w Twoim projekcie.

## Panowanie nad kosztami

Każda udana przymiarka odpowiada wygenerowaniu obrazu, płatnemu po stronie Google. Wbudowane są trzy zabezpieczenia:

- Limit miesięczny, który po osiągnięciu blokuje nowe generowania.
- Ograniczenie per adres IP, które zapobiega wywołaniom seriami.
- Wyłączne użycie obrazu produktu po stronie serwera, co uniemożliwia nadużycie usługi.

Licznik resetuje się automatycznie z każdym nowym miesiącem kalendarzowym. Równolegle obserwuj budżet w konsoli Google Cloud, gdzie możesz ustawić alerty rozliczeniowe.

## Rozwiązywanie problemów

### Przycisk się nie pojawia

Sprawdź po kolei: przełącznik główny jest włączony, identyfikator projektu i JSON są uzupełnione, produkt należy do kwalifikującej się kategorii albo ma wymuszone Zawsze wyświetlaj, a produkt ma główne zdjęcie.

### Komunikat o błędzie uwierzytelniania

Klucz JSON jest nieprawidłowy, niekompletny albo konto usługi nie ma roli Vertex AI User. Wklej ponownie cały plik i sprawdź rolę w konsoli Google Cloud. Sprawdź też, czy rozszerzenie OpenSSL jest dostępne na Twoim hostingu.

### Żaden obraz nie został wygenerowany

Model może odrzucić zdjęcie zbyt ciemne, nieostre, wykadrowane na twarz albo z wieloma osobami. Poproś o zdjęcie ostre, dobrze doświetlone, najlepiej całej sylwetki i na wprost. Bardzo restrykcyjny filtr bezpieczeństwa również może blokować niektóre obrazy.

### Błąd regionu albo nie znaleziono modelu

Model nie jest dostępny we wpisanym regionie. Wróć do _us-central1_ i sprawdź dostępność regionalną modelu w dokumentacji Google.

### Usługa zgłasza pełne obłożenie

Limit miesięczny został osiągnięty. Zwiększ go w ustawieniach albo poczekaj do kolejnego miesiąca. Licznik bieżącego miesiąca widoczny jest u góry strony ustawień.

## Częste pytania

### Czy trzeba instalować Composera?

Nie. Wtyczka używa natywnego autoloadera i podpisuje uwierzytelnianie Google w czystym PHP, przez OpenSSL.

### Czy wtyczka jest zgodna z HPOS?

Tak, zgodność z wydajnym magazynem zamówień jest zadeklarowana.

### Czy działa na urządzeniach mobilnych?

Tak. Przechwytywanie korzysta z przedniej kamery, gdy przeglądarka na to pozwala, a wgranie zdjęcia pozostaje zawsze dostępne.

### Czy można przymierzać coś innego niż ubrania?

Model jest trenowany na noszonych ubraniach. Wyniki na akcesoriach, obuwiu i przedmiotach są znacznie mniej wiarygodne. Ogranicz widżet do swoich kategorii odzieżowych.

### Co się dzieje, gdy odinstaluję wtyczkę?

Deinstalacja usuwa ustawienia, token w cache i liczniki miesięczne. Ustawienie per produkt zostaje zachowane, aby nic nie przepadło przy ponownej instalacji.