Typowe zastosowania API Upcart

Jak działa schemat API

Większość skryptów API Upcart podąża za tym samym prostym schematem: Nasłuchuj zdarzenia koszyka → Sprawdź warunek → Wykonaj akcję Na przykład: “Gdy koszyk się załaduje → sprawdź, czy jest pusty → ukryj przyklejony przycisk.” 💡 Pierwszy raz z API? Zacznij od Czym jest API?, zanim przejdziesz do poniższych przykładów.

Gdzie dodać swoje skrypty

Wszystkie poniższe skrypty trafiają do: Cart Editor → Settings → Custom HTML → Scripts (before load) Otocz każdy fragment tagami <script>...</script> i zapisz. Aby przetestować, otwórz konsolę Dev Tools przeglądarki (F12) i poszukaj komunikatów console.log.

Uwaga o starych i nowoczesnych callbackach

Upcart ma dwa sposoby nasłuchiwania zdarzeń koszyka:

Styl	Przykład	Status
Nowoczesny (zalecany)	`upcartSubscribeAddedToCart(fn)`	Aktualny
Starszy (przestarzały)	`upcartOnAddToCart = fn`	Nadal działa, loguje ostrzeżenie w konsoli

Wszystkie poniższe przykłady używają nowoczesnego API. Istniejące skrypty używające starego stylu będą nadal działać.

Przykład 1: Ukryj przycisk przyklejonego koszyka, gdy koszyk jest pusty

<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>

Jak to działa: upcartSubscribeCartLoaded uruchamia się za każdym razem, gdy koszyk się załaduje. Callback otrzymuje event z obiektem cart zawierającym tablicę items. Sumujemy quantity każdej pozycji, aby ustalić, czy koszyk jest pusty. ⚠️ WAŻNE: event.cart NIE ma właściwości item_count. Sumę musisz obliczyć, iterując po event.cart.items.

Przykład 2: Loguj, gdy produkt zostanie dodany do koszyka

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>

Właściwości dostępne w event.item:

Właściwość	Opis
`event.item.title`	Tytuł produktu
`event.item.quantityAdded`	Liczba sztuk dodanych w tej akcji
`event.item.quantity`	Łączna ilość tej pozycji obecnie w koszyku
`event.item.variantId`	ID wariantu Shopify
`event.item.handle`	Handle produktu
`event.item.productId`	ID produktu Shopify
`event.item.finalPrice`	Cena końcowa po zniżkach
`event.item.image`	Adres URL obrazka produktu

Przykład 3: Integracja z zewnętrzną aplikacją analityczną (np. TripleWhale)

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>

Uwaga: każda aplikacja firmy trzeciej jest inna. Skontaktuj się z zespołem wsparcia swojej aplikacji, aby poznać prawidłowy format zdarzeń.

Przykład 4: Automatyczne otwieranie koszyka po dodaniu produktu

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>

Uwaga: jeśli opcja “Open cart drawer on add to cart” jest już włączona w Cart Editor → Settings → Cart settings, ten skrypt nie jest potrzebny.

Funkcja	Kiedy się uruchamia	Co otrzymuje callback
`upcartSubscribeCartLoaded(fn)`	Załadowanie danych koszyka	`{ cart }` — cart ma `.items[]`, `.total`, `.currency`
`upcartSubscribeAddedToCart(fn)`	Dodanie produktu do koszyka	`{ item }` — item ma `.title`, `.variantId`, `.quantityAdded`, `.quantity`
`upcartSubscribeCartOpened(fn)`	Otwarcie cart drawera	`{}` (pusty obiekt)
`upcartSubscribeCartClosed(fn)`	Zamknięcie cart drawera	`{}` (pusty obiekt)
`upcartSubscribeCartUpdated(fn)`	Zmiana zawartości koszyka	`{ cart }`
`upcartSubscribeItemRemoved(fn)`	Usunięcie produktu	`{ item }`
`upcartSubscribeCheckoutClicked(fn)`	Kliknięcie przycisku checkoutu	`{ event }` — MouseEvent przeglądarki
`upcartSubscribeUpsellsAddedToCart(fn)`	Dodanie produktu upsell	`{ variant }` — ma `.id` i `.title`
`upcartSubscribeUpsellsRendered(fn)`	Wyrenderowanie upselli w koszyku	`{ item, element }` — item to produkt, element to węzeł DOM
`upcartSubscribeNotesTextChanged(fn)`	Aktualizacja notatek koszyka	`{ newNotesText, oldNotesText }` — nowy tekst notatek i poprzedni
`upcartSubscribeRewardsMilestonesCompletedChanged(fn)`	Zmiana statusu progu nagród	`{ numOfMilestonesCompleted, status }` — `status` to `"promotion"`, `"demotion"` lub `"initial-state"`

Funkcje bezpośrednich akcji

Funkcja	Co robi
`window.upcartOpenCart()`	Otwiera cart drawer
`window.upcartCloseCart()`	Zamyka cart drawer
`window.upcartRefreshCart()`	Odświeża dane koszyka
`window.upcartGetCart()`	Zwraca bieżący obiekt koszyka
`window.upcartRegisterAddToCart()`	Rejestruje add-to-cart dla kreatorów stron (Replo, PageFly itp.)
`window.upcartFormatMoney()`	Formatuje cenę zgodnie z formatem walutowym Twojego sklepu

Pełną dokumentację API znajdziesz w Upcart Public API Documentation.

Rozwiązywanie problemów

Skrypt się nie uruchamia? Sprawdź jeszcze raz umiejscowienie: powinien być w Scripts (before load), nie po załadowaniu.
Element nie został znaleziony? Upewnij się, że selektor (np. #upCartStickyButton) odpowiada rzeczywistemu ID elementu w Twoim koszyku.
Coś się zepsuło? Zakomentuj swój skrypt, dodając // na początku każdej linii, zapisz i odśwież.
Nadal utknięcie? Zobacz FAQ dotyczące API, aby poznać kolejne kroki rozwiązywania problemów.

Pierwsze kroki

Moduły koszyka

Ustawienia koszyka

Przyklejony przycisk koszyka

Multicart

Personalizacje

Analityka

Integracje i kompatybilność

Rozliczenia i konto

Rozwiązywanie problemów

Jak działa schemat API

Gdzie dodać swoje skrypty

Uwaga o starych i nowoczesnych callbackach

Przykład 1: Ukryj przycisk przyklejonego koszyka, gdy koszyk jest pusty

Przykład 2: Loguj, gdy produkt zostanie dodany do koszyka

Przykład 3: Integracja z zewnętrzną aplikacją analityczną (np. TripleWhale)

Przykład 4: Automatyczne otwieranie koszyka po dodaniu produktu

Funkcje bezpośrednich akcji

Rozwiązywanie problemów

​Jak działa schemat API

​Gdzie dodać swoje skrypty

​Uwaga o starych i nowoczesnych callbackach

​Przykład 1: Ukryj przycisk przyklejonego koszyka, gdy koszyk jest pusty

​Przykład 2: Loguj, gdy produkt zostanie dodany do koszyka

​Przykład 3: Integracja z zewnętrzną aplikacją analityczną (np. TripleWhale)

​Przykład 4: Automatyczne otwieranie koszyka po dodaniu produktu

​Szybki przegląd: funkcje subskrypcji (nowoczesne API)

​Funkcje bezpośrednich akcji

​Rozwiązywanie problemów

Jak działa schemat API

Gdzie dodać swoje skrypty

Uwaga o starych i nowoczesnych callbackach

Przykład 1: Ukryj przycisk przyklejonego koszyka, gdy koszyk jest pusty

Przykład 2: Loguj, gdy produkt zostanie dodany do koszyka

Przykład 3: Integracja z zewnętrzną aplikacją analityczną (np. TripleWhale)

Przykład 4: Automatyczne otwieranie koszyka po dodaniu produktu

Szybki przegląd: funkcje subskrypcji (nowoczesne API)

Funkcje bezpośrednich akcji

Rozwiązywanie problemów