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

# 如何使用直达 checkout 的 UTM 链接

> 了解如何使用 UTM 参数触发购买后漏斗，包括直达 checkout 链接的设置

Aftersell 支持基于 UTM 参数触发漏斗，这是一项专为高级用例设计的可选功能。你可以将漏斗配置为在客户带着特定 UTM 查询字符串访问你的网站时激活。

此设置是可选的，通常仅在高级跟踪需求下才需要，例如直达 checkout 链接或针对特定营销活动的优惠。

<div id="how-utm-triggers-work">
  ## UTM 触发条件的工作原理
</div>

UTM 触发条件允许你根据 URL 中的 UTM 参数展示特定的购买后漏斗。这适用于：

* **针对特定营销活动的优惠** - 根据营销活动展示不同的 upsell
* **直达 checkout 链接** - 当客户跳过店面直接结账时触发漏斗
* **渠道归因** - 根据流量来源（邮件、社交媒体、广告）个性化优惠
* **A/B 测试** - 为不同的营销活动变体测试不同的优惠

<div id="quick-start-basic-utm-trigger-setup">
  ## 快速上手：基础 UTM 触发条件设置
</div>

对于标准的店面访问（非直达 checkout），你可以使用 Aftersell 应用嵌入来设置 UTM 触发条件。要了解如何快速上手 UTM 触发条件，请观看此视频：

<iframe src="https://go.screenpal.com/player/cOfD38nOD9i" title="How to set up UTM Triggers" allowFullScreen style={{ width: '100%', aspectRatio: '16/9', borderRadius: '12px' }} />

<div id="enable-the-utm-app-embed">
  ### 启用 UTM 应用嵌入
</div>

要在店面页面上跟踪 UTM 参数：

1. 在你的 Shopify 后台中，前往 **Online Store > Themes**
2. 在你的当前主题上点击 **Customize**
3. 在主题编辑器中，点击左侧栏中的 **App embeds** 图标（拼图形状）
4. 找到 **Aftersell UTM Tracker** 并将其切换为**开启**
5. 点击 **Save**

启用后，当客户通过 UTM 链接访问你的店面时，Aftersell 会自动捕获 UTM 参数。

<div id="configure-utm-triggers-in-your-funnel">
  ### 在漏斗中配置 UTM 触发条件
</div>

启用应用嵌入后：

1. 在 Aftersell 后台中前往 **Post-purchase Funnels**
2. 创建或编辑一个漏斗
3. 在 **Triggers** 部分，添加 **UTM Parameter** 触发条件
4. 配置你想匹配的 UTM 参数及其值
5. 保存漏斗

<div id="supported-utm-parameters">
  ## 支持的 UTM 参数
</div>

Aftersell 支持以下标准 UTM 参数：

* `utm_source` - 标识流量来源（例如 google、newsletter、facebook）
* `utm_medium` - 标识营销媒介（例如 email、cpc、social）
* `utm_campaign` - 标识具体营销活动（例如 spring\_sale、product\_launch）
* `utm_term` - 标识付费搜索关键词（例如 running+shoes）
* `utm_content` - 区分相似内容或链接（例如 banner\_ad、text\_link）
* `utm_id` - 标识营销活动 ID（例如 campaign\_123）

以上六个参数均会被跟踪，都可用于触发漏斗。

<div id="partial-field-matching">
  ## 字段部分匹配
</div>

配置 UTM 触发条件时，Aftersell 支持对 UTM 参数值进行**部分匹配**。这意味着：

* ✅ **触发值：**`spring` → **匹配：**`spring_sale`、`spring_2026`、`early_spring`
* ✅ **触发值：**`email` → **匹配：**`email_newsletter`、`promotional_email`
* ✅ **触发值：**`sale` → **匹配：**`spring_sale`、`flash_sale`、`sale_2026`

这种灵活性让你可以创建覆盖多个营销活动变体的更宽泛的触发条件，而无需为每个变体单独创建触发条件。

\*\*示例：\*\*如果你设置的触发条件为 `utm_campaign` 包含 `sale`，它会匹配名称中带有“sale”的任何营销活动，例如 `spring_sale`、`summer_sale` 或 `flash_sale_2026`。

<div id="direct-to-checkout-utm-links">
  ## 直达 checkout 的 UTM 链接
</div>

上面视频中展示的基础设置**不支持**将客户**直接送达 checkout** 的链接。默认情况下，Aftersell 只能在店面页面上检测 UTM 参数。这是因为它依赖于主题应用嵌入，而该嵌入只在店面页面上生效，在 checkout 或感谢页面上不起作用。

<div id="enable-utm-tracking-on-checkout-pages">
  ### 在 checkout 页面上启用 UTM 跟踪
</div>

要在 checkout 页面上跟踪 UTM 参数（针对直达 checkout 链接），你需要向商店**添加一个 Shopify Pixel**。

⚠️ **重要限制：**

* 此设置要求访客通过 UTM 链接到达 checkout 时拥有**购物车令牌（cart token）**。没有购物车令牌，UTM 数据将不会被捕获。
* **不支持快捷结账方式（Shop Pay、Apple Pay、Google Pay）**，因为它们会绕过购物车，不会生成购物车令牌。使用快捷结账的客户不会触发基于 UTM 的漏斗。

<div id="setting-up-the-shopify-pixel">
  ### 设置 Shopify pixel
</div>

请按照以下分步说明设置直达 checkout 的 UTM 跟踪：

1. 在你的 Shopify 后台中，前往 **Settings > Customer Events**。
2. 点击 **Add Custom Pixel**，任意命名即可。
3. 在 **Permission** 下拉菜单中，选择 **Analytics**。这是唯一需要的权限。
4. 对于 **Data Sale** 下拉菜单，你可以选择 **Data collected does not qualify as data sale**。Aftersell 会对所有收集的数据严格保密，绝不会与你以外的任何人共享。
5. 在出现的代码编辑器中，粘贴下面提供的代码。
6. 点击 **Save**，然后点击 **Connect**。

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
/**  
 * IMPORTANT: This pixel can only fire on sessions where the  
 * customer has a cart object, otherwise it will be skipped.  
 * For example, clicking "Buy Now" on a product page skips the cart,  
 * going directly to checkout.  
**/  
function processData({event, cartToken}) {  
  // TODO: Edit MYSHOPIFY_DOMAIN to your domain. E.g.  
  // const MYSHOPIFY_DOMAIN = 'example-store.myshopify.com';  
  const MYSHOPIFY_DOMAIN = '';  
  
  const enableDebug = false;  
  
  // DO NOT EDIT PAST HERE  
  const SESSION_STORAGE_KEY = 'as-customer-trigger-data';  
  const HOST = 'https://start.aftersell.app';  
  
  if (!MYSHOPIFY_DOMAIN) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing Shopify domain");  
    }  
    return;  
  }  
  if (!cartToken) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing cart token");  
    }  
  }  
    
  let existingCustomerData = null;  
  try {  
      existingCustomerData = JSON.parse(  
          sessionStorage.getItem(SESSION_STORAGE_KEY) || 'null'  
      );  
  } catch (ignore) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because malformed user data json");  
    }  
  }  
    
  const allowedUrlParams = [  
        'utm_source',  
        'utm_medium',  
        'utm_campaign',  
        'utm_term',  
        'utm_id',  
        'utm_content',  
    ];  
    
  const searchParams = new URLSearchParams(event.context.window.location.search);  
  let hasCustomerData = false;  
  const customerData = {};  
  for (const param of allowedUrlParams) {  
    const paramValue = searchParams.get(param) || existingCustomerData?.[param];  
    if (paramValue) {  
        hasCustomerData = true;  
        customerData[param] = paramValue;  
    }  
  }  
  
  if (hasCustomerData) {  
    sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(customerData));  
  
    const postBody = {  
      shop: MYSHOPIFY_DOMAIN,  
      cartToken,  
      checkoutToken: event.data.checkout.token ?? undefined,  
      customerTriggerData: customerData,  
    };  
  
    if (enableDebug) {  
      console.log("UTM pixel fired with the following data:", postBody);  
    }  
      
    fetch(`\${HOST}/api/v1/storefrontSessions`, {  
        method: 'POST',  
        headers: {  
            'Content-Type': 'application/json',  
        },  
        body: JSON.stringify(postBody),  
    });  
  } else {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because there was no data to send");  
    }  
  }  
}  
  
analytics.subscribe('checkout_started', (event) => {  
   // minimum realistic time between adding item to cart and clicking checkout  
    const COOKIE_POLLING_INTERVAL_MS = 500;  
  
    let currentCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
    processData({event, cartToken: currentCookieValue});  
  
    setInterval(() => {  
        const newCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
        if (newCookieValue !== currentCookieValue) {  
            currentCookieValue = newCookieValue;  
            processData({event, cartToken: newCookieValue});  
        }  
    }, COOKIE_POLLING_INTERVAL_MS);  
});  
  
function getCookieValue({ cookie, cookieName }) {  
    const cartCookieRegex = new RegExp(`^\${cookieName}=`);  
    const cartCookie = cookie  
        .split(';')  
        .map((val) => val.trim())  
        .find((val) => cartCookieRegex.test(val));  
    if (!cartCookie) return null;  
    const cartCookieValue = cartCookie.replace(`\${cookieName}=`, '');  
    return cartCookieValue;  
}
```

**重要配置说明：**

* \*\*编辑 `MYSHOPIFY_DOMAIN`：\*\*你必须将空字符串替换为你商店的 myshopify.com 域名（例如 `'example-store.myshopify.com'`）
* \*\*启用调试模式（可选）：\*\*将 `enableDebug = true` 以在排查问题时查看控制台日志
* \*\*支持的参数：\*\*该 pixel 跟踪 `allowedUrlParams` 数组中列出的全部六个标准 UTM 参数

<div id="testing-your-utm-trigger-setup">
  ## 测试你的 UTM 触发条件设置
</div>

设置好 UTM 触发条件后，请使用以下清单验证一切是否正常运行：

<div id="for-storefront-utm-tracking-app-embed">
  ### 店面 UTM 跟踪（应用嵌入）
</div>

* ✅ \*\*应用嵌入已启用：\*\*确认 Aftersell UTM Tracker 应用嵌入在你的主题设置中已开启
* ✅ \*\*测试 URL：\*\*带 UTM 参数访问你的商店（例如 `yourstore.com?utm_campaign=test`）
* ✅ \*\*完成购买：\*\*将商品加入购物车并完成结账
* ✅ \*\*检查漏斗：\*\*确认感谢页面上显示了正确的漏斗
* ✅ \*\*订单浏览器：\*\*在 Aftersell 订单浏览器中确认 UTM 触发条件已被检测到

<div id="for-direct-to-checkout-utm-tracking-shopify-pixel">
  ### 直达 checkout 的 UTM 跟踪（Shopify pixel）
</div>

* ✅ \*\*pixel 已安装：\*\*确认自定义 pixel 已在 Settings > Customer Events 中保存并连接
* ✅ \*\*域名已配置：\*\*确认 pixel 代码中的 `MYSHOPIFY_DOMAIN` 已正确设置
* ✅ \*\*存在购物车令牌：\*\*确保客户在进入 checkout 之前购物车中有商品（跟踪所必需）
* ✅ \*\*测试 URL：\*\*使用带 UTM 参数的直达 checkout 链接（例如 `yourstore.com/checkout?utm_campaign=test`）
* ✅ \*\*完成购买：\*\*完成结账流程
* ✅ \*\*检查漏斗：\*\*确认感谢页面上显示了正确的漏斗
* ✅ \*\*订单浏览器：\*\*在 Aftersell 订单浏览器中确认 UTM 触发条件已被检测到
* ⚠️ \*\*快捷结账：\*\*请记住，Shop Pay、Apple Pay 和 Google Pay 无法与 UTM 触发条件配合使用

<div id="troubleshooting-tips">
  ### 排查建议
</div>

如果 UTM 触发条件不起作用：

1. \*\*启用调试模式：\*\*在 pixel 代码中设置 `enableDebug = true`，并在浏览器控制台中查看错误信息
2. \*\*验证购物车令牌：\*\*确保客户在到达 checkout 之前购物车中有商品（pixel 需要购物车令牌）
3. \*\*检查触发条件配置：\*\*确认漏斗触发条件中的 UTM 参数和值与 URL 参数匹配
4. \*\*测试部分匹配：\*\*请记住触发条件使用部分匹配——`sale` 会匹配 `spring_sale`、`flash_sale` 等
5. \*\*检查漏斗优先级：\*\*如果多个漏斗匹配，只有优先级最高的漏斗会显示
6. \*\*查看订单浏览器：\*\*使用 Aftersell 订单浏览器查看每笔订单触发了哪些条件

<div id="best-practices-for-utm-triggers">
  ## UTM 触发条件最佳实践
</div>

* \*\*使用一致的命名：\*\*为你的 UTM 参数建立命名规范（例如 `utm_campaign=email_spring_2026`）
* \*\*善用部分匹配：\*\*使用更宽泛的触发值来匹配多个营销活动变体
* \*\*上线前测试：\*\*在向客户发送之前，务必测试你的 UTM 链接和触发条件
* \*\*记录你的营销活动：\*\*记录每个营销活动使用的 UTM 参数
* \*\*与其他触发条件组合：\*\*将 UTM 触发条件与商品或订单金额触发条件结合使用，实现更精准的定向
* \*\*监控表现：\*\*定期查看订单浏览器，了解哪些 UTM 营销活动带来了最多的 upsell