attrify-pi-types

Attrify Pixel Integration 的 TypeScript 类型定义包，提供电商事件追踪的完整类型支持。

安装

npm install attrify-pi-types
# 或
pnpm add attrify-pi-types
# 或
yarn add attrify-pi-types

使用方式

基础导入

import type {
  AttrifyEventName,
  AttrifyEventParamsMap,
  AttrifyItem,
  PurchaseParams,
  AddToCartParams,
  // ... 其他类型
} from 'attrify-pi-types';

商品数据类型

import type { AttrifyItem } from 'attrify-pi-types';

// 商品必须提供 item_id 或 item_name 之一
const product: AttrifyItem = {
  item_id: 'SKU_12345',
  item_name: 'Stan 和 Friends Tee',
  price: 29.99,
  quantity: 1,
  item_brand: '某某品牌',
  item_category: '服饰',
};

购买事件

import type { PurchaseParams } from 'attrify-pi-types';

const purchaseData: PurchaseParams = {
  transaction_id: 'T_12345',
  value: 99.99,
  currency: 'USD',
  tax: 8.00,
  shipping: 5.00,
  coupon: 'SUMMER_FUN',
  customer: {
    email: '[email protected]',
    phone: '1234567890',
    firstName: 'john',
    lastName: 'doe',
  },
  items: [
    {
      item_id: 'SKU_001',
      item_name: 'Product A',
      price: 49.99,
      quantity: 2,
    },
  ],
};

加购事件

import type { AddToCartParams } from 'attrify-pi-types';

const addToCartData: AddToCartParams = {
  value: 29.99,
  currency: 'USD',
  items: [
    {
      item_id: 'SKU_002',
      price: 29.99,
      quantity: 1,
    },
  ],
};

搜索事件

import type { SearchParams } from 'attrify-pi-types';

const searchData: SearchParams = {
  search_term: 'T 恤',
};

类型安全的事件处理

import type {
  AttrifyEventName,
  AttrifyEventParamsMap,
} from 'attrify-pi-types';

function trackEvent<T extends AttrifyEventName>(
  eventName: T,
  params: AttrifyEventParamsMap[T]
) {
  // 类型安全的事件追踪
  console.log(eventName, params);
}

// 使用示例 - TypeScript 会自动推断参数类型
trackEvent('purchase', {
  transaction_id: 'T_001',
  value: 100,
  currency: 'USD',
  items: [{ item_id: 'SKU_001', price: 100, quantity: 1 }],
});

trackEvent('search', {
  search_term: '连衣裙',
});

支持的事件类型

| 事件名称 | 参数类型 | 说明 | |---------|---------|------| | add_payment_info | AddPaymentInfoParams | 添加支付信息 | | add_shipping_info | AddShippingInfoParams | 添加配送信息 | | add_address_info | AddAddressInfoParams | 添加地址信息 | | add_contact_info | AddContactInfoParams | 添加联系信息 | | add_to_cart | AddToCartParams | 加入购物车 | | begin_checkout | BeginCheckoutParams | 开始结账 | | purchase | PurchaseParams | 完成购买 | | refund | RefundParams | 退款 | | remove_from_cart | RemoveFromCartParams | 从购物车移除 | | search | SearchParams | 搜索 | | select_item | SelectItemParams | 选择商品 | | select_promotion | SelectPromotionParams | 选择促销 | | view_cart | ViewCartParams | 查看购物车 | | view_homepage | ViewHomepageParams | 查看首页 | | view_item | ViewItemParams | 查看商品详情 | | view_item_list | ViewItemListParams | 查看商品列表 | | view_collection | ViewCollectionParams | 查看商品集合 | | view_promotion | ViewPromotionParams | 查看促销活动 | | view_search_results | ViewSearchResultsParams | 查看搜索结果 |

核心类型说明

AttrifyItem

商品数据结构，必须提供 item_id 或 item_name 之一。

必填字段（二选一）：

• item_id - 商品 ID
• item_name - 商品名称

可选字段：

• price - 单价
• quantity - 数量（默认为 1）
• item_brand - 品牌
• item_category - 类别（支持 5 级分类）
• discount - 折扣金额
• coupon - 优惠券代码
• 更多字段详见类型定义

Customer

客户信息结构，用于 purchase 事件。

interface Customer {
  email: string;           // 必填
  firstName?: string;      // 名字（小写）
  lastName?: string;       // 姓氏（小写）
  phone?: string;          // 手机号（含国家代码）
  id?: string;             // 用户唯一 ID
  gender?: string;         // 性别（f/m）
  dateOfBirth?: string;    // 生日（YYYYMMDD）
  city?: string;           // 城市
  state?: string;          // 省/州代码
  zipCode?: string;        // 邮编
  country?: string;        // 国家代码（ISO 3166-1）
}

注意事项

1. 货币与金额：设置 value 时必须同时提供 currency（ISO 4217 格式，如 USD、CNY）
2. 商品标识：每个商品必须提供 item_id 或 item_name 之一
3. 价格计算：value 应为所有商品的 (price × quantity) 之和，不包含运费和税费
4. 数据格式：
   • 邮箱、名字、姓氏使用小写
   • 手机号仅包含数字（含国家代码）
   • 日期格式为 YYYYMMDD

License

ISC