安装

npm install analytics-by-xuantong

快速开始

浏览器端

import AnalyticsHelper from 'analytics-by-xuantong';

// 初始化
AnalyticsHelper.init({
  appId: 'your_app_id',
  requestUrl: 'https://e5log1.fineboost.cn/track/h5/',
  regUrl: 'https://spatial.fineboost.cn/egs',
  fidUrl: 'https://epcfg.fineboost.cn/sapi/v5',
  pkgName: 'com.xxx.xxx',
  currentVersion: '1.0.0',
  store: 'wx',
  cors: true,
  enable: true,
});

// 可选：设置用户身份
AnalyticsHelper.setVisitor('visitor_id_20_36_chars');  // 需在 start() 前
AnalyticsHelper.login('user_id');                      // 需在 start() 前

// 启动
AnalyticsHelper.start();

// 发送事件
AnalyticsHelper.trackPageView({ page_name: 'home' });
AnalyticsHelper.trackCustomEvent('app_launch');

Node.js 服务端（Egg）

服务端需先注入 SDK：

// app.js 或插件入口
const { registerSdkClass } = require('analytics-by-xuantong');
const EasAnalyticsAPI = require('analytics-by-xuantong/vendor/easdata.yifan.min.js');

registerSdkClass(EasAnalyticsAPI);  // 仅需调用一次

// 业务代码
import AnalyticsHelper from 'analytics-by-xuantong/helper';

AnalyticsHelper.init({ /* config */ });
AnalyticsHelper.start();

AnalyticsHelper.trackCustomEvent('server_event', { key: 'value' });

引入 SDK

本包内置 vendor/easdata.yifan.min.js，开箱即用。如需手动引入：

<!-- 浏览器 -->
<script src="node_modules/analytics-by-xuantong/vendor/easdata.yifan.min.js"></script>

<!-- 或使用 CDN -->
<script src="https://your-cdn.com/easdata.yifan.min.js"></script>

API 概览

初始化

| 方法 | 说明 | |------|------| | init(config) | 创建 SDK 实例 | | start() | 启动并上报缓存事件 | | registerSdkClass(SdkClass) | 服务端注入（仅 Node.js） |

用户身份

| 方法 | 说明 | |------|------| | setVisitor(id) | 访客 ID（20-36 字符） | | login(id) | 账号 ID（>6 字符） | | setOpenid(id) | OpenID | | logout() | 退出登录 |

事件追踪

// 页面浏览
AnalyticsHelper.trackPageView({ page_name: 'goods_detail', page_url: '/product/123' });

// 点击事件
AnalyticsHelper.trackClick({ element_id: 'btn_add_cart', element_type: 'button' });

// 电商事件
AnalyticsHelper.trackAddToCart({ product_id: 'p001', quantity: 1 });
AnalyticsHelper.trackPurchase({ order_id: 'order_001', amount: 299 });

// 支付事件
AnalyticsHelper.trackPayEvent(100, 1, 'sku_001', 'CNY', 'order_001', 1, 'Buy', 'Alipay', 1);

// 自定义事件
AnalyticsHelper.trackCustomEvent('custom_name', { key: 'value' });

用户属性

AnalyticsHelper.userSet({ last_login_time: '2024-01-01' });     // 覆盖
AnalyticsHelper.userSetOnce({ first_visit: '2024-01-01' });    // 首次
AnalyticsHelper.userAdd({ total_pay: 1 });                       // 累加
AnalyticsHelper.userAppend({ tags: ['vip'] });                   // 追加
AnalyticsHelper.userUnset('temp_field');                         // 删除

超级属性

// 附加到每个事件（必须在 start() 之前）
AnalyticsHelper.setSuperProperties({
  channel: 'web',
  platform: 'pc',
});

工具方法

const fid = AnalyticsHelper.getFid();        // 设备指纹 ID
const region = AnalyticsHelper.getRegion();  // 地域信息
const ready = AnalyticsHelper.isInitialized(); // 初始化状态

模块引入

// 主入口
import AnalyticsHelper, { AnalyticsConfig } from 'analytics-by-xuantong';

// Helper（包含电商追踪方法）
import AnalyticsHelper, { EcommerceEvent } from 'analytics-by-xuantong/helper';

// 仅类型
import type { AnalyticsConfig, EventProperties } from 'analytics-by-xuantong/types';

React 使用示例

函数组件（Hooks 写法）

import { useEffect } from 'react';
import AnalyticsHelper, { EcommerceEvent } from 'analytics-by-xuantong';

// 页面浏览
function ProductListPage() {
  useEffect(() => {
    AnalyticsHelper.track(EcommerceEvent.PAGE_VIEW, { page_name: 'product_list' });
  }, []);

  return <div>商品列表</div>;
}

// 商品曝光
function ProductCard({ productId, price }: { productId: string; price: number }) {
  useEffect(() => {
    AnalyticsHelper.track(EcommerceEvent.PRODUCT_EXPOSE, {
      product_id: productId,
      price,
      position: '0',
    });
  }, [productId]);

  const handleAddToCart = () => {
    AnalyticsHelper.track(EcommerceEvent.ADD_TO_CART, {
      product_id: productId,
      quantity: 1,
      price,
    });
  };

  return <button onClick={handleAddToCart}>加购</button>;
}

Context 方式

// 封装 Provider
import { createContext, useContext } from 'react';
import AnalyticsHelper from 'analytics-by-xuantong';

const AnalyticsContext = createContext({ track: AnalyticsHelper.track });

function AnalyticsProvider({ children, config, userId }) {
  useEffect(() => {
    AnalyticsHelper.init(config);
    if (userId) AnalyticsHelper.login(userId);
    AnalyticsHelper.start();
  }, []);

  return (
    <AnalyticsContext.Provider value={{ track: AnalyticsHelper.track }}>
      {children}
    </AnalyticsContext.Provider>
  );
}

// 函数组件中使用
function ProductCard({ productId }) {
  const { track } = useContext(AnalyticsContext);

  return (
    <button onClick={() => track(EcommerceEvent.PRODUCT_CLICK, { product_id: productId })}>
      点击
    </button>
  );
}

// 类组件中使用（直接引用已实例化的单例）
import { analyticsHelper } from './03-with-context';

class ProductCardClass extends Component {
  componentDidMount() {
    analyticsHelper.track(EcommerceEvent.PRODUCT_EXPOSE, {
      product_id: this.props.productId,
    });
  }

  handleClick = () => {
    analyticsHelper.track(EcommerceEvent.PRODUCT_CLICK, {
      product_id: this.props.productId,
    });
  };
}

更多示例见 examples/react/

初始化顺序

init() → setVisitor() / login() → setSuperProperties() → start()

注意：start() 之前调用 track() 的事件会被缓存，待 start() 时一起上报。

附录：电商追踪扩展

import { AnalyticsHelper, EcommerceEvent } from 'analytics-by-xuantong/helper';

此模块基于《标准埋点方案-电商》整理，适用于有相同业务场景的项目。

事件枚举

| 常量 | 事件 | 说明 | |------|------|------| | EcommerceEvent.LAUNCH | launch | 启动 | | EcommerceEvent.USER_REGISTER | user_register | 注册 | | EcommerceEvent.USER_LOGIN | userlogin | 登录 | | EcommerceEvent.PAGE_VIEW | page_view | 页面浏览 | | EcommerceEvent.PRODUCT_CLICK | product_click | 商品点击 | | EcommerceEvent.ADD_TO_CART | add_to_cart | 加购 | | EcommerceEvent.CREATE_ORDER | create_order | 创建订单 | | EcommerceEvent.PAYMENT_SUCCESS | payment_success | 支付成功 | | EcommerceEvent.PAYMENT_FAILURE | payment_failure | 支付失败 |

完整事件列表请查看 src/helper.ts。

使用示例

// 基础事件
AnalyticsHelper.trackLaunch();
AnalyticsHelper.trackUserRegister({ register_channel: 'wx' });
AnalyticsHelper.trackUserLogin({ login_type: 'phone' });

// 商品流程
AnalyticsHelper.trackProductExpose({ product_id: 'p001', price: 299, position: '0' });
AnalyticsHelper.trackProductClick({ product_id: 'p001', source: 'recommend' });
AnalyticsHelper.trackProductDetailView({ product_id: 'p001', stock_status: 'in_stock' });
AnalyticsHelper.trackAddToCart({ product_id: 'p001', quantity: 1 });
AnalyticsHelper.trackCreateOrder({ order_id: 'order_001', order_amount: 299 });
AnalyticsHelper.trackPaymentSuccess({ order_id: 'order_001', payment_amount: 299 });

枚举参考

类型定义中保留了枚举常量作为参考：PageName、ElementType、ShareTarget、StockStatus 等。参数类型已放开为 string，可直接传入新值。

官方 SDK 文档：https://yifants.feishu.cn/wiki/F0vdwTfdqiOXUzkP4uTcc8gbn9b