Trustoo Loyalty Tracker

一个用于追踪用户忠诚度事件的 JavaScript 库，支持在用户未登录时暂存事件数据，登录后自动上报。

功能特性

• 🎯 事件追踪：支持注册和登录事件追踪
• 💾 本地存储：未登录时自动暂存事件数据到 localStorage
• ⏰ 数据有效期：24 小时内的事件数据有效
• 🔄 自动上报：用户登录后自动上报暂存的事件数据
• 🛡️ 错误处理：完善的错误处理和日志记录
• 📦 单例模式：确保全局只有一个追踪器实例

安装

npm install @hashcoop/trustoo-loyalty-tracker

使用方法

基础用法

import {
  trustooLoyaltyTracker,
  trackSourcesNamesMap,
  trackSourcesTypesMap
} from '@hashcoop/trustoo-loyalty-tracker';

// 获取追踪器实例
const tracker = trustooLoyaltyTracker.getCustomerEventTrackerInstance();

// 初始化追踪器（通常在应用启动时调用）
tracker.init('https://your-api.com/track');

// 追踪注册事件
tracker.trackSignupEvent(
  trackSourcesNamesMap.loyalty_popup,
  trackSourcesTypesMap.from_banner,
  123 // 可选的 source_id
);

// 追踪登录事件
tracker.trackLoginEvent(
  trackSourcesNamesMap.loyalty_widget,
  trackSourcesTypesMap.from_widget_home,
  456 // 可选的 source_id
);

简化使用方式

如果你想要更简洁的使用方式，可以创建一个工具函数：

import {
  trustooLoyaltyTracker,
  trackSourcesNamesMap,
  trackSourcesTypesMap
} from '@hashcoop/trustoo-loyalty-tracker';

// 创建便捷的追踪器实例
const tracker = trustooLoyaltyTracker.getCustomerEventTrackerInstance();

// 初始化
tracker.init('https://your-api.com/track');

// 使用追踪器
tracker.trackSignupEvent(trackSourcesNamesMap.loyalty_popup, trackSourcesTypesMap.from_banner， 100);
tracker.trackLoginEvent(trackSourcesNamesMap.loyalty_widget, trackSourcesTypesMap.from_widget_home， 111);

在 React 应用中使用

import React, { useEffect } from 'react';
import {
  trustooLoyaltyTracker,
  trackSourcesNamesMap,
  trackSourcesTypesMap
} from '@hashcoop/trustoo-loyalty-tracker';

function App() {
  const tracker = trustooLoyaltyTracker.getCustomerEventTrackerInstance();
  useEffect(() => {
    // 获取追踪器实例并初始化
    tracker.init('https://your-api.com/track');
  }, []);

  const handleRegisterClick = () => {
    tracker.trackSignupEvent(
      trackSourcesNamesMap.loyalty_popup,
      trackSourcesTypesMap.from_banner,
      123 // 可选的 source_id
    );
  };

  const handleLoginClick = () => {
    tracker.trackLoginEvent(
      trackSourcesNamesMap.loyalty_widget,
      trackSourcesTypesMap.from_widget_home,
      456 // 可选的 source_id
    );
  };

  return (
    <div>
      <button onClick={handleRegisterClick}>注册</button>
      <button onClick={handleLoginClick}>登录</button>
    </div>
  );
}

事件源类型

事件名称 (trackEventsNamesMap)

import { trackEventsNamesMap } from '@hashcoop/trustoo-loyalty-tracker';

// 可用的事件名称
trackEventsNamesMap.login; // 登录事件
trackEventsNamesMap.register; // 注册事件

事件源名称 (trackSourcesNamesMap)

import { trackSourcesNamesMap } from '@hashcoop/trustoo-loyalty-tracker';

// 可用的事件源名称
trackSourcesNamesMap.loyalty_popup; // 忠诚度弹窗
trackSourcesNamesMap.loyalty_widget; // 忠诚度组件
trackSourcesNamesMap.loyalty_page; // 忠诚度页面
trackSourcesNamesMap.checkout_extension; // 结账扩展

事件源类型 (trackSourcesTypesMap)

import { trackSourcesTypesMap } from '@hashcoop/trustoo-loyalty-tracker';

// 可用的事件源类型
trackSourcesTypesMap.from_banner; // 来自横幅
trackSourcesTypesMap.from_coupon; // 来自优惠券
trackSourcesTypesMap.from_vip_perk; // 来自VIP特权
trackSourcesTypesMap.from_vip; // 来自VIP
trackSourcesTypesMap.from_widget_home; // 来自组件首页
trackSourcesTypesMap.from_widget_ways_to_earn; // 来自组件赚取方式
trackSourcesTypesMap.from_widget_ways_to_redeem; // 来自组件兑换方式
trackSourcesTypesMap.from_checkout_redeem; // 来自结账兑换
trackSourcesTypesMap.from_checkout_points; // 来自结账积分
trackSourcesTypesMap.from_popup_signup; // 来自弹窗注册
trackSourcesTypesMap.write_an_review; // 写评论
trackSourcesTypesMap.write_an_review_with_photos; // 带照片写评论
trackSourcesTypesMap.place_an_order; // 下单
trackSourcesTypesMap.visit_website; // 访问网站
trackSourcesTypesMap.sign_up; // 注册
trackSourcesTypesMap.celebrate_a_birthday; // 庆祝生日
trackSourcesTypesMap.subscribe_to_newsletter; // 订阅新闻通讯
trackSourcesTypesMap.share_on_facebook; // 在Facebook分享
trackSourcesTypesMap.share_on_x; // 在X分享
trackSourcesTypesMap.follow_on_instagram; // 在Instagram关注
trackSourcesTypesMap.follow_on_tiktok; // 在TikTok关注
trackSourcesTypesMap.subscribe_youtube; // 订阅YouTube
trackSourcesTypesMap.visit_url; // 访问URL
trackSourcesTypesMap.custom_action; // 自定义操作

方法参数说明

trackSignupEvent(sourceName, sourceType, sourceId?)

• sourceName: 事件源名称，使用 trackSourcesNamesMap 对象
• sourceType: 事件源类型，使用 trackSourcesTypesMap 对象
• sourceId: 可选的源 ID，用于标识特定的源实例

trackLoginEvent(sourceName, sourceType, sourceId?)

• sourceName: 事件源名称，使用 trackSourcesNamesMap 对象
• sourceType: 事件源类型，使用 trackSourcesTypesMap 对象
• sourceId: 可选的源 ID，用于标识特定的源实例

工作流程

1. 获取实例：通过 trustooLoyaltyTracker.getCustomerEventTrackerInstance() 获取追踪器实例
2. 初始化：调用 tracker.init(apiUrl) 初始化追踪器，自动上报
3. 事件追踪：调用 tracker.trackSignupEvent() 或 tracker.trackLoginEvent() 记录事件
4. 数据暂存：如果用户未登录，事件数据会暂存到 localStorage
5. 自动上报：用户登录后，追踪器会自动检查并上报暂存的事件数据
6. 数据清理：上报成功后自动清除本地暂存数据

数据格式

追踪器会发送以下格式的数据到后端：

{
  "timestamp": "2024-01-01T00:00:00.000Z",
  "sources": [
    {
      "source_name": "loyalty_popup",
      "source_type": "from_banner",
      "event_name": "register",
      "trigger_at": "2024-01-01T00:00:00.000Z",
      "source_id": 123
    }
  ]
}

字段说明：

• timestamp: 数据创建时间戳
• sources: 事件源数组
  • source_name: 事件源名称
  • source_type: 事件源类型
  • event_name: 事件名称（login 或 register）
  • trigger_at: 事件触发时间
  • source_id: 可选的源 ID

开发

安装依赖

pnpm install

构建库

pnpm build

开发模式

pnpm dev

运行测试

pnpm test

注意事项

• 追踪器使用单例模式，确保全局只有一个实例
• 需要通过 trustooLoyaltyTracker.getCustomerEventTrackerInstance() 获取追踪器实例
• 事件数据在 localStorage 中保存 24 小时
• 需要确保后端 API 能够接收 POST 请求
• 追踪器会自动检测用户登录状态（通过 window.__st.cid）
• 使用 trackSignupEvent() 方法追踪注册事件，而不是 trackRegisterEvent()
• 使用 const assertions 替代枚举，减少打包体积