Widżet JS

Widżet to Web Component: działa w każdym sklepie, bez Reacta i innych bibliotek. Szklany przycisk kładziesz na zdjęciu produktu. Dotknięcie otwiera jedno okno, które płynnie przechodzi przez kolejne kroki:

• zgody (raz);
• zdjęcie (raz);
• czekanie;
• wynik ze znaczkiem AI;
• ocenę kciukiem;
• galerię wcześniejszych przymiarek.

Na telefonie okno wysuwa się od dołu, a na komputerze pojawia się na środku. Po zamknięciu okna przymiarka trwa dalej, a przycisk pokazuje postęp.

Instalacja

<script src="https://cdn.przymierz.online/przymierz.js" defer></script>

<div class="product-photo" style="position: relative">
  <img src="sukienka.jpg" alt="">
  <przymierz-button product-id="SKU-123" style="position: absolute; right: 12px; bottom: 12px"></przymierz-button>
</div>

<script>
  addEventListener("DOMContentLoaded", () =>
    Przymierz.init({
      tokenUrl: "/api/przymierz-token",   // endpoint w Twoim backendzie
      apiBase: "https://api.przymierz.online",
      locale: "pl",                        // albo "en"
      theme: { primary: "#1f1b2e" },
    }),
  );
</script>

Na wąskich kartach daj przyciskowi szerokość zdjęcia: left: 10px; right: 10px; display: flex; justify-content: flex-end. Wtedy napis się skróci i nie wyjdzie poza zdjęcie.

Endpoint tokenu w Twoim backendzie

Widżet woła POST tokenUrl (z ciasteczkami Twojego sklepu). Twój backend rozpoznaje zalogowaną klientkę i zwraca odpowiedź z POST /v1/session-tokens:

@app.post("/api/przymierz-token")
async def przymierz_token(user = Depends(current_user)):
    r = await http.post(f"{API}/v1/session-tokens",
                        json={"external_user_id": user.id},
                        headers={"Authorization": f"Bearer {os.environ['PRZYMIERZ_KEY']}"})
    return r.json()  # {"token": ..., "expires_at": ...}

Atrybuty

Atrybut	Opis
product-id	external_product_id produktu (wymagany)
priority	browse (domyślnie), live, preview
variant	compact (domyślnie): kółko, napis rozwija się na start, przy czekaniu i przy gotowym wyniku. full: stała kapsuła z napisem
label	Własny tekst przycisku na start

Na live’ie

Podmieniaj product-id na aktualnie pokazywany produkt:

document.querySelector("#live-try-on").setAttribute("product-id", live.currentProductId);

Po zmianie produktu:

• przycisk przełącza się i rozwija napis;
• jeśli klientka ma już wynik dla tego produktu (np. z zapowiedzi), od razu pokazuje „Gotowe” z miniaturą;
• przymiarka poprzedniego produktu kończy się w tle i trafia do galerii.

Zdarzenia

document.addEventListener("przymierz:result", (e) => analytics.track("tryon", e.detail.productId));
document.addEventListener("przymierz:feedback", (e) => analytics.track("tryon_rated", e.detail.rating, e.detail.reasons));
document.addEventListener("przymierz:error", (e) => console.warn(e.detail.code));
document.addEventListener("przymierz:save", (e) => analytics.track("tryon_saved", e.detail.method));
document.addEventListener("przymierz:share", (e) => analytics.track("tryon_shared", e.detail.method));

Przycisku do koszyka w widżecie nie ma. O zakupie decyduje Twój sklep.

Zapis i udostępnianie

Pod wynikiem są dwa przyciski: Zapisz (na komputerze Pobierz) i Udostępnij. Obraz ma mały znaczek „Obraz AI · nazwa butiku” i oznaczenie AI w metadanych (szczegóły).

Gdzie	Zapisz	Udostępnij
Android, komputer	Pobiera plik JPG	Arkusz systemowy; bez niego menu „Kopiuj obraz” i „Pobierz”
iPhone i iPad w przeglądarce	Obraz na pełnym ekranie z podpowiedzią „Przytrzymaj zdjęcie i wybierz Dodaj do Zdjęć” (Safari nie pozwala stronie zapisać obrazu w Zdjęciach)	Arkusz systemowy

Zdarzenia przychodzą tylko po udanej akcji, z detail = { tryonId, productId, method }:

Zdarzenie	method
przymierz:save	download (pobranie), ios-viewer (otwarty podgląd na iPhonie)
przymierz:share	share (arkusz systemowy), copy (obraz w schowku)

Zamknięcie arkusza udostępniania bez wyboru nie wysyła zdarzenia.

Języki

Okno przymiarki mówi w 20 językach: polski, angielski, ukraiński, niemiecki, czeski, słowacki, litewski, łotewski, estoński, węgierski, rumuński, bułgarski, chorwacki, słoweński, francuski, hiszpański, włoski, portugalski, niderlandzki, szwedzki. Domyślnie bierze język przeglądarki klientki. Klientka zmienia go w menu „···” → „Zmień język”, a wybór zostaje zapamiętany w jej przeglądarce.

Przymierz.init({
  tokenUrl: "/przymierz-token",
  apiBase: "https://api.przymierz.online",
  locale: "auto",                 // domyślnie; albo np. "pl", gdy sklep chce zacząć od polskiego
  locales: ["pl", "en", "uk"],    // opcjonalnie: tylko te języki na liście
  allowLocaleChange: true,        // false chowa wiersz „Zmień język” w menu
  privacyUrl: "https://sklep.pl/polityka-prywatnosci", // link w „O przymiarce AI”
});
document.addEventListener("przymierz:locale", (e) => console.log(e.detail.locale));

Kolejność: wybór klientki, potem locale z init, potem język przeglądarki, na końcu polski.

Informacja o AI jest zawsze widoczna i nie da się jej wyłączyć: zdanie pod wynikiem („Obraz wygenerowany przez AI. Kolor, krój i dopasowanie mogą się różnić od rzeczywistości.”), zdanie pod zgodami i ekran „O przymiarce AI” w menu. Zasady dla klientek: Zasady przymiarki.

Wygląd i dostępność

Wygląd okna ustawisz w theme albo zmiennymi CSS na stronie:

theme	Zmienna CSS	Co zmienia
primary	--przymierz-primary	Kolor głównego przycisku w oknie
primaryInk	--przymierz-primary-ink	Kolor tekstu na tym przycisku
radius	--przymierz-radius	Zaokrąglenie okna, np. "24px"
font	--przymierz-font	Krój pisma, np. "Inter, sans-serif"
Style widżetu nie mieszają się ze stylami sklepu (Shadow DOM).

Ustawienia systemu:

• przy Ogranicz przezroczystość i Zwiększ kontrast (oraz w przeglądarkach bez backdrop-filter) widżet rysuje jednolite tło zamiast szkła;
• przy Ogranicz ruch wyłącza animacje.