@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 文件中。

追踪方法

$3

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

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

$3

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

$3

`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,
});
`

$3

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

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

$3

`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

;
}

// 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 Add to Cart;
}
`

在 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

`

调试

开启 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 查看收集的数据：

`bash


安装

npm install -g @optima-chat/bi-cli

登录

bi-cli auth login

查看流量概览

bi-cli traffic overview

查看转化漏斗

bi-cli traffic funnel
``

License

MIT