npm package: @hashcoop/trustoo-loyalty-tracker
Description: Trustoo Loyalty Tracker
Latest version: 0.1.1

# Trustoo Loyalty Tracker

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

## 功能特性

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

## 安装

```bash
npm install @hashcoop/trustoo-loyalty-tracker
```

## 使用方法

### 基础用法

```javascript
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
);
```

### 简化使用方式

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

```javascript
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 应用中使用

```jsx
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)

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

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

#### 事件源名称 (trackSourcesNamesMap)

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

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

#### 事件源类型 (trackSourcesTypesMap)

```typescript
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. **数据清理**：上报成功后自动清除本地暂存数据

### 数据格式

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

```json
{
  "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

## 开发

### 安装依赖

```bash
pnpm install
```

### 构建库

```bash
pnpm build
```

### 开发模式

```bash
pnpm dev
```

### 运行测试

```bash
pnpm test
```

## 注意事项

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