Integracja z platformą Shoper

Koszyk.pro integruje się ze sklepami na platformie Shoper przez OAuth 2.0 oraz opcjonalny widget JavaScript. Poniżej znajdziesz szczegółową instrukcję konfiguracji.

Jak połączyć sklep

Połączenie sklepu Shoper z Koszyk.pro zajmuje kilka minut. Wykonaj poniższe kroki:

  1. Zaloguj się do swojego konta w Koszyk.pro.
  2. Przejdź do sekcji „Sklepy" i kliknij przycisk „Dodaj sklep".
  3. Wybierz platformę Shoper z listy dostępnych integracji.
  4. Podaj adres URL swojego sklepu — musi zaczynać się od https:// (np. https://mójsklep.shoper.pl). Adresy HTTP nie są akceptowane ze względów bezpieczeństwa.
  5. Kliknij „Autoryzuj" — zostaniesz przekierowany na stronę Shoper, gdzie musisz zaakceptować uprawnienia aplikacji. Koszyk.pro wymaga uprawnień do odczytu koszyków i zamówień — nie modyfikuje żadnych danych w Twoim sklepie.
  6. Gotowe! Po pomyślnej autoryzacji zostaniesz przekierowany z powrotem do Koszyk.pro. Sklep pojawi się na liście ze statusem „Aktywny", a pierwsza synchronizacja koszyków rozpocznie się automatycznie.

Synchronizacja koszyków

Koszyk.pro automatycznie pobiera koszyki z Twojego sklepu Shoper i wykrywa te, które zostały porzucone.

Jak działa polling

Co 15 minut nasz system odpytuje API Shoper (/webapi/rest/carts) i pobiera aktualne koszyki. Każdy koszyk identyfikowany jest przez pole id z API Shoper, które zapisywane jest jako platform_cart_id w naszym systemie.

Detekcja porzucenia

Koszyk uznawany jest za porzucony, gdy:

  • Upłynął skonfigurowany czas od utworzenia lub ostatniej aktualizacji koszyka.
  • Klient nie złożył zamówienia — Koszyk.pro sprawdza to, dopasowując zamówienia po adresie email klienta.

Tryb hybrydowy (API + Widget JS)

Dla najlepszych rezultatów zalecamy użycie obu źródeł danych jednocześnie:

  • API (polling) — daje pewność, że żaden koszyk nie zostanie pominięty, nawet jeśli klient ma zablokowany JavaScript.
  • Widget JS — dostarcza dane w czasie rzeczywistym (email ze strony checkout, zdarzenia dodania do koszyka) i pozwala szybciej zidentyfikować klienta.

Gdy dane napływają z obu źródeł, system inteligentnie je łączy (merge), zachowując najświeższe informacje z każdego źródła.

Widget JS

Widget JavaScript zbiera zdarzenia po stronie przeglądarki klienta i przesyła je do Koszyk.pro w czasie rzeczywistym. Dzięki temu możesz identyfikować klientów nawet zanim zakończą zamówienie.

Instalacja

Wklej poniższy snippet w szablonie stopki swojego sklepu Shoper (plik footer.tpl w edytorze szablonów): 

      <script>
    window.koszyk = window.koszyk || { q: [] };
    window.koszyk.q = window.koszyk.q || [];
    window.koszyk.q.push(['init', 'TWOJ_TOKEN', { platform: 'shoper' }]);
  </script>
  <script async src="https://app.koszyk.pro/widget/koszyk-widget.min.js"></script>

Wartość TWOJ_TOKEN znajdziesz w panelu Koszyk.pro, w ustawieniach sklepu.

Co zbiera widget

  • Zdarzenia koszyka — nasłuchuje na natywne eventy Shoper: Shop:cart:add (dodanie produktu) i Shop:cart:update (zmiana koszyka). Po każdym zdarzeniu pobiera aktualny stan koszyka (produkty, ceny, ilości) i przesyła go do Koszyk.pro.
  • Adres email — na stronach checkout (/checkout, /zamowienie) widget automatycznie przechwytuje email wpisany przez klienta w polach formularza i identyfikuje sesję.
  • Sesja klienta — widget generuje unikalny identyfikator sesji (cookie kp_sid, ważny 30 dni) i przypisuje do niego wszystkie zdarzenia. Pozwala to powiązać koszyk z klientem nawet bez podania emaila.
  • Zdarzenie checkout — gdy klient wchodzi na stronę realizacji zamówienia, widget wysyła event checkout_started z danymi koszyka.

Popup do zbierania emaili

Widget może wyświetlać popup z prośbą o podanie adresu email. Popup można skonfigurować w panelu Koszyk.pro i ustawić wyzwalacze:

  • Exit intent — popup pojawia się, gdy kursor myszy opuści obszar strony (próba zamknięcia karty).
  • Dodanie do koszyka — popup wyświetla się po dodaniu produktu do koszyka.

Wygląd popupu (kolory, nagłówek, treść przycisku) można dostosować w konfiguracji widgetu. Popup wyświetla się maksymalnie raz na sesję.

FAQ

Mój sklep ma status „Błąd"

Najczęstszą przyczyną jest wygaśnięty token OAuth. Tokeny Shoper mają ograniczony czas ważności. Aby naprawić problem:

  1. Przejdź do listy sklepów w panelu Koszyk.pro.
  2. Kliknij sklep ze statusem „Błąd".
  3. Kliknij przycisk „Re-autoryzuj" i ponownie zaakceptuj uprawnienia na stronie Shoper.

Koszyki nie synchronizują się

Sprawdź kolejno:

  • Status sklepu — synchronizacja działa tylko dla sklepów ze statusem „Aktywny". Jeśli status to „Błąd", wykonaj re-autoryzację (patrz wyżej).
  • Ostatnia synchronizacja — w panelu sklepu widoczna jest data ostatniej udanej synchronizacji. Jeśli jest bardzo stara, może to oznaczać problem z połączeniem.
  • Adres URL sklepu — upewnij się, że adres sklepu jest poprawny i używa protokołu https://.

Widget nie działa

Sprawdź kolejno:

  • Konsola przeglądarki — otwórz narzędzia deweloperskie (F12) i sprawdź zakładkę Console. Jeśli widget załadował się prawidłowo, zobaczysz komunikat [KoszykPro] Initialized for platform: shoper.
  • Token — upewnij się, że w snippecie podany jest prawidłowy token sklepu (dostępny w panelu Koszyk.pro).
  • Pozycja snippeta — snippet powinien znajdować się w pliku footer.tpl (stopka szablonu), aby ładował się na każdej podstronie sklepu.