> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Typowe zastosowania API Upcart

> Dowiedz się, jak wykorzystać Public API Upcart w praktyce dzięki gotowym do skopiowania przykładom.

<div id="how-the-api-pattern-works">
  ## Jak działa schemat API
</div>

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?](/pl/upcart/what_is_an_api), zanim przejdziesz do poniższych przykładów.

***

<div id="where-to-add-your-scripts">
  ## Gdzie dodać swoje skrypty
</div>

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`.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## Uwaga o starych i nowoczesnych callbackach
</div>

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ć.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## Przykład 1: Ukryj przycisk przyklejonego koszyka, gdy koszyk jest pusty
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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`.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## Przykład 2: Loguj, gdy produkt zostanie dodany do koszyka
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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                 |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## Przykład 3: Integracja z zewnętrzną aplikacją analityczną (np. TripleWhale)
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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ń.

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## Przykład 4: Automatyczne otwieranie koszyka po dodaniu produktu
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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.

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## Szybki przegląd: funkcje subskrypcji (nowoczesne API)
</div>

| 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"` |

***

<div id="direct-action-functions">
  ## Funkcje bezpośrednich akcji
</div>

| 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](https://rokt.notion.site/upcart-public-api).

***

<div id="troubleshooting">
  ## Rozwiązywanie problemów
</div>

* **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](/pl/upcart/upcart_api_frequently_asked_questions), aby poznać kolejne kroki rozwiązywania problemów.