npm package: @optima-chat/analytics-sdk
Description: Optima Analytics SDK - Browser-based user behavior tracking
Author: Optima Team
Latest version: 0.1.1

# @optima-chat/analytics-sdk

Optima Analytics SDK - 用于电商网站的用户行为追踪。

## 安装

```bash
npm install @optima-chat/analytics-sdk
```

## 快速开始

```typescript
import { Analytics } from '@optima-chat/analytics-sdk';

const analytics = new Analytics({
  environment: 'production', // 'production' | 'stage'
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  merchantId: 'your-merchant-id',
});

analytics.init();

// 追踪页面浏览
analytics.page();

// 追踪商品浏览
analytics.productViewed('product-123', { name: 'iPhone 15', price: 999 });

// 追踪加入购物车
analytics.productAddedToCart('product-123', 1);
```

## 配置选项

```typescript
interface AnalyticsConfig {
  // 必填
  clientId: string; // OAuth Client ID
  clientSecret: string; // OAuth Client Secret
  merchantId: string; // 商户 ID

  // 可选
  environment?: 'production' | 'stage' | 'development'; // 默认 'production'
  productId?: string; // 数据来源标识，如 'optima-store'
  autoTrack?: boolean; // 自动追踪页面浏览，默认 true
  debug?: boolean; // 开启调试日志，默认 false
  batchSize?: number; // 批量发送阈值，默认 10
  flushInterval?: number; // 自动发送间隔(ms)，默认 5000
  sessionTimeout?: number; // 会话超时(ms)，默认 30 分钟
}
```

## 环境配置

SDK 根据 `environment` 自动选择正确的服务端点：

| 环境        | Auth URL                      | Collect Endpoint                        |
| ----------- | ----------------------------- | --------------------------------------- |
| production  | https://auth.optima.onl       | https://bi-api.optima.onl/collect       |
| stage       | https://auth.stage.optima.onl | https://bi-api.stage.optima.onl/collect |
| development | https://auth.optima.chat      | https://bi-api.optima.chat/collect      |

## OAuth 凭据获取

联系管理员获取 `clientId` 和 `clientSecret`，凭据存储在 `.env.analytics` 文件中。

## 追踪方法

### 页面浏览

```typescript
// 基础页面浏览（自动获取页面信息）
analytics.page();

// 带自定义属性
analytics.page({ category: 'products', section: 'electronics' });
```

### 商品相关

```typescript
// 商品浏览
analytics.productViewed('product-id', {
  name: 'Product Name',
  price: 99.99,
  category: 'Electronics',
});

// 商品列表浏览
analytics.productListViewed('category-page', [
  { product_id: 'prod-1', name: 'Product 1' },
  { product_id: 'prod-2', name: 'Product 2' },
]);

// 加入购物车
analytics.productAddedToCart('product-id', 2, { variant: 'blue' });

// 从购物车移除
analytics.productRemovedFromCart('product-id', 1);

// 加入心愿单
analytics.productAddedToWishlist('product-id');
```

### 购物流程

```typescript
// 查看购物车
analytics.cartViewed(
  [
    { product_id: 'prod-1', quantity: 2 },
    { product_id: 'prod-2', quantity: 1 },
  ],
  299.99 // 购物车总价
);

// 开始结账
analytics.checkoutStarted({ step: 1, payment_method: 'credit_card' });

// 完成订单
analytics.orderCompleted('order-123', 299.99, {
  currency: 'USD',
  products_count: 3,
});
```

### 搜索

```typescript
// 执行搜索
analytics.searchPerformed('iphone', 15); // 关键词, 结果数

// 点击搜索结果
analytics.searchResultClicked('iphone', 'product-123', 3); // 关键词, 商品ID, 位置
```

### 自定义事件

```typescript
analytics.track('custom_event', {
  custom_property: 'value',
  another_property: 123,
});
```

## 用户识别

```typescript
// 用户登录后调用
analytics.identify('user-123');
```

## 手动控制

```typescript
// 立即发送队列中的事件
await analytics.flushAsync();

// 重置 SDK 状态（如用户登出）
analytics.reset();

// 获取 SDK 指标
const metrics = analytics.getMetrics();
console.log(metrics);
// {
//   eventsTracked: 50,
//   eventsSent: 48,
//   eventsFailed: 2,
//   eventsPending: 0,
//   sendSuccessRate: 0.96,
//   retries: 3,
//   storageUsed: 1024,
// }
```

## SPA 支持

SDK 自动监听 `history.pushState`、`history.replaceState` 和 `popstate` 事件，在 SPA 路由变化时自动追踪页面浏览。

如需关闭自动追踪：

```typescript
const analytics = new Analytics({
  // ...
  autoTrack: false,
});

// 手动追踪
router.afterEach((to) => {
  analytics.page({ path: to.path });
});
```

## 离线支持

SDK 使用 `localStorage` 持久化未发送的事件，在网络恢复后自动重试发送。

## 在 React 中使用

```tsx
// analytics.ts
import { Analytics } from '@optima-chat/analytics-sdk';

export const analytics = new Analytics({
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'stage',
  clientId: process.env.REACT_APP_ANALYTICS_CLIENT_ID!,
  clientSecret: process.env.REACT_APP_ANALYTICS_CLIENT_SECRET!,
  merchantId: process.env.REACT_APP_MERCHANT_ID!,
});

// App.tsx
import { useEffect } from 'react';
import { analytics } from './analytics';

function App() {
  useEffect(() => {
    analytics.init();
  }, []);

  return <div>...</div>;
}

// ProductPage.tsx
import { analytics } from './analytics';

function ProductPage({ product }) {
  useEffect(() => {
    analytics.productViewed(product.id, {
      name: product.name,
      price: product.price,
    });
  }, [product.id]);

  const handleAddToCart = () => {
    analytics.productAddedToCart(product.id, 1);
    // ... add to cart logic
  };

  return <button onClick={handleAddToCart}>Add to Cart</button>;
}
```

## 在 Vue 中使用

```typescript
// plugins/analytics.ts
import { Analytics } from '@optima-chat/analytics-sdk';

export const analytics = new Analytics({
  environment: import.meta.env.PROD ? 'production' : 'stage',
  clientId: import.meta.env.VITE_ANALYTICS_CLIENT_ID,
  clientSecret: import.meta.env.VITE_ANALYTICS_CLIENT_SECRET,
  merchantId: import.meta.env.VITE_MERCHANT_ID,
});

// main.ts
import { analytics } from './plugins/analytics';
analytics.init();

// composables/useAnalytics.ts
import { analytics } from '../plugins/analytics';

export function useAnalytics() {
  return analytics;
}

// ProductView.vue
<script setup>
import { onMounted } from 'vue';
import { useAnalytics } from '@/composables/useAnalytics';

const props = defineProps(['product']);
const analytics = useAnalytics();

onMounted(() => {
  analytics.productViewed(props.product.id, {
    name: props.product.name,
    price: props.product.price,
  });
});
</script>
```

## 调试

开启 debug 模式查看详细日志：

```typescript
const analytics = new Analytics({
  // ...
  debug: true,
});
```

控制台输出示例：

```
[Analytics] Analytics initialized { clientId: '...', merchantId: '...', endpoint: '...' }
[Analytics] Event tracked { eventName: 'page_viewed', queueSize: 1 }
[Analytics] Access token obtained { expiresIn: 3600 }
[Analytics] Flushing events { count: 5 }
[Analytics] Events sent successfully { count: 5 }
```

## 数据查看

使用 [bi-cli](../bi-cli) 查看收集的数据：

```bash
# 安装
npm install -g @optima-chat/bi-cli

# 登录
bi-cli auth login

# 查看流量概览
bi-cli traffic overview

# 查看转化漏斗
bi-cli traffic funnel
```

## License

MIT