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

# Upcart API 常见用法

> 通过可直接复制粘贴的实用示例，了解如何使用 Upcart 的 Public API。

<div id="how-the-api-pattern-works">
  ## API 模式的工作原理
</div>

大多数 Upcart API 脚本都遵循同一个简单模式：

监听购物车事件 → 检查条件 → 执行操作

例如："当购物车加载时 → 检查购物车是否为空 → 隐藏悬浮按钮。"

💡 \*\*刚接触 API？\*\*在深入下面的示例之前，请先阅读[什么是 API？](/zh/upcart/what_is_an_api)。

***

<div id="where-to-add-your-scripts">
  ## 在哪里添加脚本
</div>

以下所有脚本均添加到：

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

将每个代码片段包裹在 `<script>...</script>` 标签中并保存。测试时，打开浏览器的开发者工具控制台（`F12`），查看是否有 `console.log` 消息。

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## 关于旧版与新版回调的说明
</div>

Upcart 有两种监听购物车事件的方式：

| 风格      | 示例                               | 状态            |
| ------- | -------------------------------- | ------------- |
| 新版（推荐）  | `upcartSubscribeAddedToCart(fn)` | 当前版本          |
| 旧版（已弃用） | `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`     | Shopify 款式 ID  |
| `event.item.handle`        | 商品 handle      |
| `event.item.productId`     | Shopify 商品 ID  |
| `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>
```

> \*\*注意：\*\*如果已在 **Cart Editor → Settings → Cart settings** 中启用了 "Open cart drawer on add to cart"，则不需要此脚本。

***

<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)`                   | 点击 checkout 按钮时 | `{ event }`——浏览器 MouseEvent                                                                       |
| `upcartSubscribeUpsellsAddedToCart(fn)`                | 添加 upsell 商品时   | `{ variant }`——具有 `.id` 和 `.title`                                                                |
| `upcartSubscribeUpsellsRendered(fn)`                   | upsell 在购物车中渲染时 | `{ 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 匹配。
* \*\*出问题了？\*\*在每行开头添加 `//` 将脚本注释掉，保存后刷新。
* \*\*仍然卡住？\*\*请参阅 [API 常见问题](/zh/upcart/upcart_api_frequently_asked_questions)获取更多排查步骤。