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

# Распространенные способы использования API Upcart

> Узнайте, как применять Public API Upcart на практике с готовыми примерами для копирования.

<div id="how-the-api-pattern-works">
  ## Как работает паттерн API
</div>

Большинство скриптов API Upcart следуют одному и тому же простому паттерну:

Слушать событие корзины → Проверить условие → Выполнить действие

Например: «Когда корзина загружается → проверить, пуста ли она → скрыть закрепленную кнопку».

💡 **Впервые работаете с API?** Начните со статьи [Что такое API?](/ru/upcart/what_is_an_api), прежде чем переходить к примерам ниже.

***

<div id="where-to-add-your-scripts">
  ## Куда добавлять ваши скрипты
</div>

Все скрипты ниже размещаются в:

**Cart Editor → Settings → Custom HTML → Scripts (before load)**

Оберните каждый сниппет в теги `<script>...</script>` и сохраните. Для тестирования откройте консоль Dev Tools вашего браузера (`F12`) и ищите сообщения `console.log`.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## Замечание об устаревших и современных колбэках
</div>

В Upcart есть два способа слушать события корзины:

| Стиль                       | Пример                           | Статус                                             |
| --------------------------- | -------------------------------- | -------------------------------------------------- |
| Современный (рекомендуется) | `upcartSubscribeAddedToCart(fn)` | Актуальный                                         |
| Устаревший (deprecated)     | `upcartOnAddToCart = fn`         | Всё еще работает, выводит предупреждение в консоль |

Все примеры ниже используют современный API. Существующие скрипты в старом стиле продолжат работать.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## Пример 1: скрыть кнопку закрепленной корзины, когда корзина пуста
</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>
```

**Как это работает:** `upcartSubscribeCartLoaded` срабатывает при каждой загрузке корзины. Колбэк получает `event` с объектом `cart`, содержащим массив `items`. Мы суммируем `quantity` каждого товара, чтобы определить, пуста ли корзина.

⚠️ **ВАЖНО:** у `event.cart` НЕТ свойства `item_count`. Вы должны вычислить итог, перебирая `event.cart.items`.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## Пример 2: логирование добавления товара в корзину
</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>
```

**Свойства, доступные в `event.item`:**

| Свойство                   | Описание                                       |
| -------------------------- | ---------------------------------------------- |
| `event.item.title`         | Название товара                                |
| `event.item.quantityAdded` | Количество единиц, добавленных в этом действии |
| `event.item.quantity`      | Общее количество этого товара в корзине сейчас |
| `event.item.variantId`     | ID варианта Shopify                            |
| `event.item.handle`        | Handle товара                                  |
| `event.item.productId`     | ID товара Shopify                              |
| `event.item.finalPrice`    | Итоговая цена после скидок                     |
| `event.item.image`         | URL изображения товара                         |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## Пример 3: интеграция со сторонним аналитическим приложением (например, 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>
```

> **Примечание:** каждое стороннее приложение отличается. Уточните правильный формат события у команды поддержки вашего приложения.

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## Пример 4: автоматическое открытие корзины после добавления товара
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

> **Примечание:** если опция «Open cart drawer on add to cart» уже включена в **Cart Editor → Settings → Cart settings**, этот скрипт вам не нужен.

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## Краткий справочник: функции подписки (современный API)
</div>

| Функция                                                | Когда срабатывает                    | Что получает колбэк                                                                                            |
| ------------------------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `upcartSubscribeCartLoaded(fn)`                        | Данные корзины загружаются           | `{ cart }` — у cart есть `.items[]`, `.total`, `.currency`                                                     |
| `upcartSubscribeAddedToCart(fn)`                       | Товар добавлен в корзину             | `{ item }` — у item есть `.title`, `.variantId`, `.quantityAdded`, `.quantity`                                 |
| `upcartSubscribeCartOpened(fn)`                        | Cart drawer открывается              | `{}` (пустой объект)                                                                                           |
| `upcartSubscribeCartClosed(fn)`                        | Cart drawer закрывается              | `{}` (пустой объект)                                                                                           |
| `upcartSubscribeCartUpdated(fn)`                       | Содержимое корзины меняется          | `{ cart }`                                                                                                     |
| `upcartSubscribeItemRemoved(fn)`                       | Товар удален                         | `{ item }`                                                                                                     |
| `upcartSubscribeCheckoutClicked(fn)`                   | Нажата кнопка оформления заказа      | `{ event }` — MouseEvent браузера                                                                              |
| `upcartSubscribeUpsellsAddedToCart(fn)`                | Добавлен товар апселла               | `{ variant }` — имеет `.id` и `.title`                                                                         |
| `upcartSubscribeUpsellsRendered(fn)`                   | Апселлы отображаются в корзине       | `{ item, element }` — item — товар, element — DOM-узел                                                         |
| `upcartSubscribeNotesTextChanged(fn)`                  | Примечания корзины обновлены         | `{ newNotesText, oldNotesText }` — новая строка примечаний и предыдущая                                        |
| `upcartSubscribeRewardsMilestonesCompletedChanged(fn)` | Меняется статус этапа вознаграждений | `{ numOfMilestonesCompleted, status }` — `status` может быть `"promotion"`, `"demotion"` или `"initial-state"` |

***

<div id="direct-action-functions">
  ## Функции прямых действий
</div>

| Функция                            | Что делает                                                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| `window.upcartOpenCart()`          | Открывает cart drawer                                                                |
| `window.upcartCloseCart()`         | Закрывает cart drawer                                                                |
| `window.upcartRefreshCart()`       | Обновляет данные корзины                                                             |
| `window.upcartGetCart()`           | Возвращает текущий объект корзины                                                    |
| `window.upcartRegisterAddToCart()` | Регистрирует добавление в корзину для конструкторов страниц (Replo, PageFly и т. д.) |
| `window.upcartFormatMoney()`       | Форматирует цену в денежном формате вашего магазина                                  |

Полную документацию API см. в [документации Upcart Public API](https://rokt.notion.site/upcart-public-api).

***

<div id="troubleshooting">
  ## Устранение неполадок
</div>

* **Скрипт не выполняется?** Перепроверьте размещение: он должен находиться в *Scripts (before load)*, а не after load.
* **Элемент не найден?** Убедитесь, что селектор (например, `#upCartStickyButton`) соответствует фактическому ID элемента в вашей корзине.
* **Что-то сломалось?** Закомментируйте свой скрипт, добавив `//` в начало каждой строки, сохраните и обновите страницу.
* **Все еще не получается?** Дополнительные шаги по устранению неполадок см. в [FAQ по API](/ru/upcart/upcart_api_frequently_asked_questions).