@mai-co/pixel

v1.0.5

Published

25 days ago

MAI Pixel SDK - Event tracking and UTM attribution for Shopify Headless stores

Downloads

185

0High
0Medium
0Low

zilong.wang

pengleimai

shopify headless analytics pixel tracking utm attribution

MAI Pixel - Headless Store Integration Guide

将 MAI Pixel 添加到 Headless 店铺或自定义网站。

为什么需要手动安装？

MAI Pixel 的自动安装仅适用于 Shopify Liquid 主题。如果你的店铺使用 Headless 架构（Hydrogen、Next.js、Gatsby、Vue/Nuxt 等自定义前端），前端代码托管在 Shopify 之外，MAI 无法自动注入追踪代码，需要手动集成。

Step 1: 安装 SDK

根据你的技术栈，选择下面两种接入方式之一。

方式 A：Script 标签接入（任意网站）

适用于任意网站 — Shopify Liquid、静态站点、GTM 等。在每个页面的 <head> 标签内添加：

<script>
  window.MAI_CONFIG = {
    storeDomain: "your-store.myshopify.com",
  };
  window.MaiPixel =
    window.MaiPixel ||
    function () {
      (window.MaiPixel.q = window.MaiPixel.q || []).push(arguments);
    };
</script>
<script src="https://cdn.jsdelivr.net/npm/@mai-co/pixel@1/dist/mai-pixel.min.js" async></script>

将 your-store.myshopify.com 替换为你的 Shopify 店铺域名。

SDK 通过 jsDelivr CDN 分发。URL 里的 @1 锁定主版本号 1，自动拿到向后兼容的小版本更新。

方式 B：npm + ESM 接入（Hydrogen / Next.js / Vite 等现代框架）

推荐用于现代框架。先安装：

npm install @mai-co/pixel
# 或
pnpm add @mai-co/pixel
# 或
yarn add @mai-co/pixel

在应用入口处初始化一次（例如 app 根组件）：

import { initMaiPixel, MaiPixel } from "@mai-co/pixel";

initMaiPixel({
  storeDomain: "your-store.myshopify.com",
  // debug: true,  // 可选，开启调试日志
});

// 初始化后即可调用 MaiPixel 上报事件
MaiPixel("product_viewed", {
  product_id: "gid://shopify/Product/1234567",
  product_variant_id: "gid://shopify/ProductVariant/654321",
});

npm 包自带 TypeScript 类型定义，所有事件都有完整的自动补全和类型校验。初始化后 MaiPixel 也会挂到 window.MaiPixel，你可以选择用 import 导入的函数或全局的 window.MaiPixel，两者等价。

验证安装

打开浏览器开发者工具 Console，输入：

MaiPixel._initialized;

如果返回 true，说明安装成功。

事件集成一览表

以下是 SDK 支持的所有事件，按重要性排序：

| 事件 | 优先级 | 是否需要手动集成 | 说明 | |------|--------|---------------|------| | setCustomer | ⭐⭐⭐ 必须 | 是 — 登录后立即调用 | 归因依赖 | | page_viewed | ⭐⭐⭐ 必须 | SPA 需要（非 SPA 自动） | SDK 初始化时自动发一次；SPA 路由切换时需手动调用 | | product_viewed | ⭐⭐ 推荐 | 是 | 商品详情页浏览 | | product_added_to_cart | ⭐⭐ 推荐 | 是 | 加入购物车 | | product_removed_from_cart | ⭐ 可选 | 按需 | 移出购物车 | | cart_viewed | ⭐ 可选 | 按需 | 查看购物车 | | search_submitted | ⭐ 可选 | 按需 | 搜索提交 | | collection_viewed | ⭐ 可选 | 按需 | 集合/分类页浏览 | | checkout_started | 🔸 特殊 | 自定义 checkout 才需要 | Shopify 托管 checkout 由 Web Pixel 自动追踪 | | checkout_completed | 🔸 特殊 | 自定义 checkout 才需要 | Shopify 托管 checkout 由 Web Pixel 自动追踪 | | consent | 🔹 合规 | 有 cookie banner 时需要 | 隐私授权控制 |

Step 2: 识别访问者（必须）

当用户登录或提交表单时，调用 setCustomer 将联系信息关联到当前访问者：

MaiPixel("setCustomer", {
  email: "[email protected]", // email 或 phone 至少提供一个
  phone: "+1-555-123-4567", // email 或 phone 至少提供一个
  firstName: "John", // 可选
  lastName: "Doe", // 可选
});

设置后，后续所有事件都会自动携带客户信息。这对 checkout 归因至关重要——后端通过 email 将浏览阶段的 UTM 和 checkout 阶段的订单关联起来。

Step 3: 追踪用户行为

页面浏览（必须）

SDK 初始化时会自动触发一次 page_viewed。对于 SPA（单页应用），你需要在路由切换时手动调用：

MaiPixel("page_viewed");

各框架的路由监听方式不同，核心是在路由变化的回调里加上这一行即可。

商品浏览（推荐）

当用户进入商品详情页时：

MaiPixel("product_viewed", {
  product_id: "gid://shopify/Product/1234567", // Product ID (Required)
  product_variant_id: "gid://shopify/ProductVariant/654321", // Variant ID (Required)
  product_title: "Premium Widget", // Product name (Optional)
  product_variant_title: "Blue / Large", // Variant name (Optional)
  price: "29.99", // Variant price (Optional)
  currency: "USD", // Currency code, ISO 4217 (Optional)
  sku: "W-BLUE-L", // SKU (Optional)
});

加入购物车（推荐）

MaiPixel("product_added_to_cart", {
  product_id: "gid://shopify/Product/1234567", // Product ID (Required)
  product_variant_id: "gid://shopify/ProductVariant/654321", // Variant ID (Required)
  quantity: 1, // Quantity added (Required)
  product_title: "Premium Widget", // Product name (Optional)
  product_variant_title: "Blue / Large", // Variant name (Optional)
  price: "29.99", // Variant price (Optional)
  currency: "USD", // Currency code, ISO 4217 (Optional)
  total_cost: "29.99", // Total line cost (Optional)
  sku: "W-BLUE-L", // SKU (Optional)
});

Step 4: 追踪其他用户行为

移出购物车（可选）

MaiPixel("product_removed_from_cart", {
  product_id: "gid://shopify/Product/1234567", // Product ID (Required)
  product_variant_id: "gid://shopify/ProductVariant/654321", // Variant ID (Required)
  quantity: 1, // Quantity removed (Optional)
  product_title: "Premium Widget", // Product name (Optional)
  price: "29.99", // Variant price (Optional)
  currency: "USD", // Currency code, ISO 4217 (Optional)
});

查看购物车（可选）

MaiPixel("cart_viewed", {
  cart_id: "gid://shopify/Cart/xxx", // Cart ID (Optional)
  amount: "59.98", // Cart total amount (Optional)
  currency: "USD", // Currency code, ISO 4217 (Optional)
  total_quantity: 2, // Total items in cart (Optional)
  items: [
    // Line items (Optional)
    {
      item_id: "1234567", // Product ID
      item_name: "Widget", // Product name
      item_variant: "Blue", // Variant name
      price: "29.99", // Variant price
      quantity: 2, // Quantity
      cost: "59.98", // Line total cost
      sku: "W-BLUE", // SKU
    },
  ],
});

搜索（可选）

MaiPixel("search_submitted", {
  query: "snowboard", // Search query (Optional)
  items: [
    // Search result items (Optional)
    {
      item_id: "1234567", // Product ID
      item_name: "Snowboard Pro", // Product name
      item_variant: "Default", // Variant name
      price: "499.99", // Price
      sku: "SB-PRO", // SKU
    },
  ],
});

集合页浏览（可选）

MaiPixel("collection_viewed", {
  items: [
    // Collection items (Optional)
    {
      item_id: "1234567", // Product ID
      item_name: "Widget", // Product name
      price: "29.99", // Price
    },
    {
      item_id: "2345678", // Product ID
      item_name: "Gadget", // Product name
      price: "49.99", // Price
    },
  ],
});

Step 5: 自定义 Checkout 事件

注意： 如果你的 checkout 由 Shopify 托管（大部分情况），checkout 事件由 MAI Web Pixel 自动追踪，无需手动调用。仅在自定义 checkout（商户完全自己实现支付页面）时才需要使用以下事件。

开始结账

MaiPixel("checkout_started", {
  token: "abc123", // Checkout token (Optional)
  email: "[email protected]", // Customer email (Optional, recommended for attribution)
  phone: "+1-555-123-4567", // Customer phone (Optional)
  first_name: "John", // Shipping first name (Optional)
  last_name: "Doe", // Shipping last name (Optional)
  address1: "123 Main St", // Shipping address line 1 (Optional)
  address2: "Apt 4", // Shipping address line 2 (Optional)
  city: "New York", // Shipping city (Optional)
  country: "United States", // Shipping country (Optional)
  country_code: "US", // Shipping country code, ISO 3166 (Optional)
  province: "New York", // Shipping province/state (Optional)
  province_code: "NY", // Shipping province code (Optional)
  zip: "10001", // Shipping zip code (Optional)
  order_id: "ORDER-1001", // Order ID (Optional)
  currency: "USD", // Currency code, ISO 4217 (Optional)
  subtotal: "59.98", // Subtotal before shipping/tax (Optional)
  shipping: "5.00", // Shipping cost (Optional)
  tax: "3.50", // Tax amount (Optional)
  value: "68.48", // Total order value (Optional)
  sms_marketing_phone: "+1-555-123-4567", // SMS marketing phone (Optional)
  items: [
    // Line items (Optional)
    {
      item_id: "1234567", // Product ID
      item_name: "Widget", // Product name
      item_variant: "Blue", // Variant name
      price: "59.98", // Line total price
      unit_price: "29.99", // Unit price per item
      quantity: 2, // Quantity
      sku: "W-BLUE", // SKU
    },
  ],
});

完成购买

MaiPixel("checkout_completed", {
  order_id: "ORDER-1001", // Order ID (Required)
  token: "abc123", // Checkout token (Optional)
  email: "[email protected]", // Customer email (Optional, recommended for attribution)
  phone: "+1-555-123-4567", // Customer phone (Optional)
  first_name: "John", // Shipping first name (Optional)
  last_name: "Doe", // Shipping last name (Optional)
  address1: "123 Main St", // Shipping address line 1 (Optional)
  address2: "Apt 4", // Shipping address line 2 (Optional)
  city: "New York", // Shipping city (Optional)
  country: "United States", // Shipping country (Optional)
  country_code: "US", // Shipping country code, ISO 3166 (Optional)
  province: "New York", // Shipping province/state (Optional)
  province_code: "NY", // Shipping province code (Optional)
  zip: "10001", // Shipping zip code (Optional)
  currency: "USD", // Currency code, ISO 4217 (Optional)
  subtotal: "59.98", // Subtotal before shipping/tax (Optional)
  shipping: "5.00", // Shipping cost (Optional)
  tax: "3.50", // Tax amount (Optional)
  value: "68.48", // Total order value (Optional)
  sms_marketing_phone: "+1-555-123-4567", // SMS marketing phone (Optional)
  items: [
    // Line items (Optional)
    {
      item_id: "1234567", // Product ID
      item_name: "Widget", // Product name
      item_variant: "Blue", // Variant name
      price: "59.98", // Line total price
      unit_price: "29.99", // Unit price per item
      quantity: 2, // Quantity
      sku: "W-BLUE", // SKU
    },
  ],
});

Step 6: SPA 框架集成

SDK 初始化时会自动触发首次 page_viewed。但 SPA 中路由切换不会重新加载页面，需要在路由变化时手动调用：

// 监听路由变化后调用
window.MaiPixel?.("page_viewed");

各框架的路由监听方式不同，核心是在路由变化的回调里加上这一行即可。

Managing Tracking Consent

禁用追踪

当用户通过 cookie banner 拒绝追踪时：

MaiPixel("consent", false);

SDK 将停止发送所有后续事件。

启用追踪

当用户同意追踪时：

MaiPixel("consent", true);

SDK 恢复发送事件。

细粒度控制

如果你的 consent 管理需要区分不同类型的追踪授权（与 Shopify CustomerPrivacy API 对齐）：

MaiPixel("consent", {
  analytics_processing_allowed: true, // 分析追踪
  marketing_allowed: true, // 营销追踪
  preferences_processing_allowed: true, // 偏好追踪
  sale_of_data_allowed: false, // 数据销售
});

当 analytics_processing_allowed 为 false 时，SDK 停止发送事件。

默认行为

如果不调用 consent()，SDK 默认允许追踪。