customer-chat-sdk 1.2.0 → 1.3.5

package/README.md

@@ -1,400 +1,459 @@
-# Customer SDK
-
-一个轻量级的客服系统SDK，帮助开发者快速集成客服聊天功能到现有的Web应用中。
-
-## 🚀 特性
-
-- **轻量级集成**: 一行代码快速接入
-- **悬浮图标**: 页面右下角悬浮聊天图标，支持自定义位置（x, y坐标）
-- **可拖拽图标**: 支持鼠标/触摸拖拽移动图标位置
-- **响应式设计**: PC弹窗模式 / 移动端全屏模式
-- **设备指纹**: 自动获取设备唯一标识
-- **iframe隔离**: 完全隔离的聊天界面，避免样式冲突
-- **通知系统**: 红点徽章、数字提醒功能
-- **页面截图**: 支持自动截图和上传功能，可配置截图引擎和压缩选项
-- **跨平台支持**: 支持UMD、ESM、CJS多种模块格式
-
-## 📦 安装
-
-### CDN 引入
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/customer-chat-sdk@1.0.20/dist/customer-sdk.min.js"></script>
-<script>
-  CustomerSDK.init({
-    agent: 'your_agent_id',
-    token: 'jwt_token',
-    iframeUrl: 'https://chat.example.com'
-  });
-</script>
-```
+# CustomerSDK 使用文档
 
-**或者使用 unpkg：**
-```html
-<script src="https://unpkg.com/customer-chat-sdk@1.0.20/dist/customer-sdk.min.js"></script>
-```
+## 简介
 
-### NPM 安装
+CustomerSDK 是一个轻量级的客服 SDK，提供**图标管理**和**截图功能**。适用于需要自行管理弹窗组件的项目场景。
 
-```bash
-npm install customer-chat-sdk```
+## 特性
 
-```javascript
-import CustomerSDK from 'customer-chat-sdk';
+- ✅ **悬浮图标** - 可拖动的悬浮图标，支持侧边吸附和磁性吸附
+- ✅ **截图功能** - 自动截图、压缩、上传
+- ✅ **设备识别** - 自动获取设备指纹 ID
+- ✅ **通知提醒** - 支持数字和文本通知徽章
+- ✅ **无 iframe** - 不包含 iframe 管理，由项目自行实现弹窗
 
-CustomerSDK.init({
-  agent: 'your_agent_id',
-  token: 'jwt_token',
-  iframeUrl: 'https://chat.example.com'
-});
+## 安装
+
+```bash
+npm install customer-chat-sdk
+# 或
+pnpm add customer-chat-sdk
+# 或
+yarn add customer-chat-sdk
 ```
 
-## 🔧 快速开始
+## 快速开始
 
 ### 基础用法
 
-```javascript
-// 初始化SDK
-await CustomerSDK.init({
-  agent: 'agent_123',
-  token: 'jwt_token_here',
-  iframeUrl: 'https://chat.example.com',
-  debug: true
-}, {
-  // 自定义图标位置（可选）
-  iconPosition: {
-    x: 20,        // 距离左边的距离（像素）
-    y: 80         // 距离顶部的距离（像素）
-  },
-  // 或者使用CSS值
-  // iconPosition: {
-  //   x: '20px',
-  //   y: '10%'
-  // }
-});
-
-// 关闭悬浮图标
-CustomerSDK.hideIcon();
-
-// 打开悬浮图标
-CustomerSDK.showIcon();
-
-// 动态设置图标位置
-CustomerSDK.setIconCoordinates({ x: 50, y: 100 });
-
-// 打开聊天窗口
-CustomerSDK.openChat();
-
-// 检查聊天窗口是否打开
-const isOpen = CustomerSDK.isChatOpen();
-
-// 显示通知
-CustomerSDK.showNotification(5); // 数字徽章
-CustomerSDK.showNotification('NEW'); // 文本徽章
-CustomerSDK.clearNotification(); // 清除通知
-```
+```typescript
+import { CustomerSDK } from 'customer-chat-sdk'
 
-### 高级配置
+// 创建 SDK 实例
+const sdk = new CustomerSDK()
 
-```javascript
-// 高级配置
-await CustomerSDK.init({
-  agent: 'your_agent_id',
-  token: 'your_jwt_token',
-  iframeUrl: 'https://chat.example.com',
-  debug: true,
-  // 截图配置（可选）
-  screenshot: {
-    interval: 5000,           // 截图间隔（毫秒），默认5000
-    quality: 0.4,            // 图片质量（0-1），默认0.4
-    maxWidth: 1600,           // 最大宽度，默认1600
-    maxHeight: 900,           // 最大高度，默认900
-    outputFormat: 'webp',      // 输出格式：'webp' | 'jpeg' | 'png'，默认webp
-    engine: 'html2canvas',    // 截图引擎（仅支持html2canvas）
-    compress: false,          // 是否启用前端压缩，默认false
-    enableCORS: true,         // 是否启用CORS处理，默认true
-    corsMode: 'canvas-proxy', // CORS处理模式，默认canvas-proxy
-    silentMode: false         // 静默模式，减少控制台输出，默认false
-  }
-}, {
-  // iframe选项（可选）
-  width: 400,
-  height: 600,
-  mode: 'auto', // 'auto' | 'fullscreen' | 'popup'
-  draggable: false,
-  resizable: false,
-  allowClose: true,
-  // 图标位置配置（可选）
-  iconPosition: {
-    x: 20,      // 距离左边的距离（像素或CSS值，如'20px'、'10%'）
-    y: 80       // 距离顶部的距离（像素或CSS值，如'80px'、'10%'）
-  }
-});
-
-// 设置自定义截图目标元素
-CustomerSDK.setScreenshotTarget(document.getElementById('my-container'));
+// 初始化（返回初始化结果，包含设备ID等）
+const initResult = await sdk.init({
+  debug: true, // 开发环境开启
+  iconPosition: { x: 20, y: 80 },
+  target: '#app'
+})
 
-// 手动触发截图
-await CustomerSDK.captureScreenshot();
+console.log('Device ID:', initResult.deviceId)
 
-// 获取截图状态
-const state = CustomerSDK.getScreenshotState();
-console.log('截图状态:', state);
+// 设置图标点击回调
+sdk.onIconClick(() => {
+  // 打开您的弹窗组件
+  openChatPopup()
+})
 ```
 
-## 📖 API 文档
-
-### 初始化方法
-
-#### `CustomerSDK.init(config, options?)`
-
-初始化Customer SDK，自动获取设备指纹ID并创建隐藏iframe。
-
-**参数：**
-
-- `config` (SDKConfig): SDK配置选项
-- `options` (ChatWindowOptions?, 可选): iframe窗口选项
-
-**SDKConfig:**
-```typescript
-interface SDKConfig {
-  agent: string;           // 代理商ID
-  token: string;           // 认证令牌
-  iframeUrl: string;       // iframe聊天页面URL (必需)
-  debug?: boolean;         // 调试模式
-  screenshot?: ScreenshotOptions;  // 截图配置（可选）
-}
+### 完整示例（Vue 3）
+
+```vue
+<template>
+  <div id="app">
+    <ChatPopup
+      ref="chatPopupRef"
+      v-model:visible="chatVisible"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+import { CustomerSDK } from 'customer-chat-sdk'
+
+const chatVisible = ref(false)
+const chatPopupRef = ref()
+let sdk: CustomerSDK | null = null
+
+onMounted(async () => {
+  sdk = new CustomerSDK()
+  
+  const initResult = await sdk.init({
+    debug: true,
+    screenshot: {
+      engine: 'modern-screenshot',
+      quality: 0.15,
+      compress: true,
+      interval: 5000
+    },
+    iconPosition: { x: 20, y: 80 },
+    target: '#app',
+    sideAttach: true,
+    magnetic: true
+  }, {
+    sendData: (data) => {
+      // 处理截图数据
+      chatPopupRef.value?.handleScreenshotData(data)
+    }
+  })
+
+  // 获取设备ID等信息
+  console.log('Device ID:', initResult.deviceId)
+  console.log('Referrer:', initResult.referrer)
+
+  // 图标点击打开弹窗
+  sdk.onIconClick(async () => {
+    chatVisible.value = true
+    
+    // 启用截图
+    const config = await fetchScreenshotConfig()
+    if (config) {
+      sdk?.triggerScreenshotConfig(JSON.stringify(config))
+    }
+  })
+})
+
+onUnmounted(() => {
+  sdk?.destroy()
+})
+</script>
+```
 
-interface ScreenshotOptions {
-  interval?: number;       // 截图间隔（毫秒），默认5000
-  quality?: number;        // 图片质量（0-1），默认0.4
-  scale?: number;          // 缩放比例，默认1
-  maxHistory?: number;     // 最大历史记录数，默认10
-  compress?: boolean;      // 是否压缩图片，默认false
-  maxWidth?: number;       // 最大宽度，默认1600
-  maxHeight?: number;      // 最大高度，默认900
-  outputFormat?: 'webp' | 'jpeg' | 'png';  // 输出格式，默认webp
-  enableCORS?: boolean;     // 是否启用CORS处理，默认true
-  proxyUrl?: string;       // 代理服务器URL，用于处理CORS问题
-  engine?: 'html2canvas';  // 截图引擎（仅支持html2canvas，此选项已废弃，保留仅为兼容性）
-  corsMode?: 'simple' | 'smart' | 'proxy' | 'blob' | 'canvas-proxy' | 'ignore' | 'test-first';  // CORS处理模式，默认canvas-proxy
-  silentMode?: boolean;     // 静默模式，减少控制台输出，默认false
-  maxRetries?: number;      // 最大重试次数，默认2
+### React 示例
+
+```tsx
+import { useEffect, useRef, useState } from 'react'
+import { CustomerSDK } from 'customer-chat-sdk'
+
+function App() {
+  const [chatVisible, setChatVisible] = useState(false)
+  const sdkRef = useRef<CustomerSDK | null>(null)
+
+  useEffect(() => {
+    const sdk = new CustomerSDK()
+    sdkRef.current = sdk
+
+    sdk.init({
+      debug: true,
+      screenshot: {
+        engine: 'modern-screenshot',
+        quality: 0.15,
+        compress: true
+      },
+      iconPosition: { x: 20, y: 80 },
+      target: '#app'
+    }, {
+      sendData: (data) => {
+        // 发送截图数据到后端
+        fetch('/api/upload-screenshot', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/octet-stream' },
+          body: data.data
+        })
+      }
+    }).then((initResult) => {
+      // 获取设备ID等信息
+      console.log('Device ID:', initResult.deviceId)
+      
+      sdk.onIconClick(async () => {
+        setChatVisible(true)
+        const config = await fetchScreenshotConfig()
+        if (config) {
+          sdk.triggerScreenshotConfig(JSON.stringify(config))
+        }
+      })
+    })
+
+    return () => {
+      sdk.destroy()
+    }
+  }, [])
+
+  return <div id="app">...</div>
 }
 ```
 
-**ChatWindowOptions:**
-```typescript
-interface ChatWindowOptions {
-  width?: number;                          // iframe宽度
-  height?: number;                          // iframe高度
-  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-  draggable?: boolean;                     // 是否可拖拽
-  resizable?: boolean;                      // 是否可调整大小
-  minimizable?: boolean;                    // 是否可最小化
-  iconPosition?: IconPosition;              // 图标位置配置
-}
+## API 文档
 
-interface IconPosition {
-  x?: number | string;     // x坐标（像素值或CSS值，如'20px'、'10%'）
-  y?: number | string;     // y坐标（像素值或CSS值，如'80px'、'10%'）
-}
-```
+### CustomerSDK 类
 
-### 核心方法
+#### 构造函数
 
-#### `CustomerSDK.openChat()` / `CustomerSDK.closeChat()`
+```typescript
+const sdk = new CustomerSDK()
+```
 
-打开或关闭iframe聊天窗口。
+#### init(config, screenshotCallback?)
 
-#### `CustomerSDK.showIcon()` / `CustomerSDK.hideIcon()`
+初始化 SDK
 
-显示或隐藏悬浮图标。
+```typescript
+const initResult = await sdk.init(config, screenshotCallback?)
+```
 
-#### `CustomerSDK.setIconPosition(position)`
+**返回值：**
 
-设置图标到预设位置（兼容旧API）。
+返回 `InitResult` 对象，包含：
+- `deviceId: string` - 设备ID（md5后的）
+- `referrer: string` - 页面来源
+- `agent?: string` - 代理商ID（如果配置了）
+- `timestamp: number` - 初始化时间戳
 
 **参数：**
-- `position` ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right'): 预设位置
 
-#### `CustomerSDK.setIconCoordinates(position)`
+- `config: SDKConfig` - SDK 配置
+- `screenshotCallback?: ScreenshotMessageCallback` - 截图回调（可选）
 
-设置图标到自定义坐标位置。
+**配置选项：**
 
-**参数：**
-- `position` (IconPosition): 位置配置对象
-  ```typescript
-  {
-    x?: number | string;  // x坐标（像素值或CSS值）
-    y?: number | string;  // y坐标（像素值或CSS值）
+```typescript
+interface SDKConfig {
+  debug?: boolean                    // 调试模式
+  screenshot?: ScreenshotOptions    // 截图配置
+  iconPosition?: {                  // 图标位置
+    x?: number | string
+    y?: number | string
   }
-  ```
+  target?: HTMLElement | string     // 图标挂载目标
+  sideAttach?: boolean              // 侧边吸附（默认 true）
+  sideHideRatio?: number            // 侧边隐藏比例（默认 0.5）
+  magnetic?: boolean                // 磁性吸附（默认 true）
+  magneticDirection?: 'x' | 'y' | 'both' // 磁性方向（默认 'x'）
+  margin?: number                   // 边距（默认 10px）
+  autoAttachDelay?: number          // 自动吸附延迟（默认 3000ms）
+  referrer?: string                 // 页面来源
+  agent?: string                    // 代理商ID
+  token?: string                    // 认证令牌
+}
+```
 
-**示例：**
-```javascript
-// 使用像素值
-CustomerSDK.setIconCoordinates({ x: 50, y: 100 });
+**截图配置：**
 
-// 使用CSS值
-CustomerSDK.setIconCoordinates({ x: '20px', y: '10%' });
+```typescript
+interface ScreenshotOptions {
+  engine?: 'modern-screenshot' | 'snapdom' | 'html2canvas'
+  quality?: number                  // 0-1，默认 0.15
+  compress?: boolean                // 是否压缩
+  interval?: number                 // 默认间隔（毫秒）
+  maxWidth?: number                 // 最大宽度
+  maxHeight?: number                // 最大高度
+  outputFormat?: 'webp' | 'jpeg' | 'png'
+  enableCORS?: boolean              // 启用 CORS
+  proxyUrl?: string                 // 代理 URL
+  corsMode?: 'simple' | 'smart' | 'proxy' | 'blob' | 'canvas-proxy'
+  debug?: boolean                   // 截图调试
+}
 ```
 
-#### `CustomerSDK.setScreenshotTarget(element)`
+**截图回调：**
 
-设置截图目标元素。默认截图目标为 `document.body`。
+```typescript
+interface ScreenshotMessageCallback {
+  sendData?: (data: {
+    type: 'screenshotBinary'
+    data: ArrayBuffer
+  }) => void
+  onConfig?: (config: string) => void
+}
+```
 
-**参数：**
-- `element` (HTMLElement): 要截图的DOM元素
+#### onIconClick(callback)
 
-#### `CustomerSDK.captureScreenshot()`
+设置图标点击回调
 
-手动触发一次截图。
+```typescript
+sdk.onIconClick(() => {
+  openChatPopup()
+})
+```
 
-**返回：** `Promise<boolean>` - 是否截图成功
+#### showNotification(badgeCount, options?)
 
-#### `CustomerSDK.getScreenshotState()`
+显示通知
 
-获取截图功能的状态信息。
+```typescript
+sdk.showNotification(5, { pulse: true, autoHide: 5000 })
+sdk.showNotification('新', { pulse: true })
+```
 
-**返回：** 状态对象，包含：
-- `isRunning`: 是否正在运行
-- `screenshotCount`: 截图次数
-- `lastScreenshotTime`: 最后截图时间
-- `error`: 错误信息
-- `isEnabled`: 是否启用
-- `isUploading`: 是否正在上传
-- `uploadError`: 上传错误
-- `uploadProgress`: 上传进度
-- `currentUploadConfig`: 当前上传配置
+#### clearNotification()
 
-#### `CustomerSDK.isChatOpen()`
+清除通知
 
-检查聊天窗口是否打开。
+```typescript
+sdk.clearNotification()
+```
 
-**返回：** boolean
+#### triggerScreenshotConfig(configJson)
 
-#### `CustomerSDK.sendToIframe(data)`
+启用/停止截图
 
-向iframe发送数据消息。
+```typescript
+// 启用截图
+const config = {
+  agent: 'your-agent-id',
+  sign: 'your-sign',
+  type: 1,
+  topic: 'screenshot',
+  routingKey: 'route-key',
+  ttl: Date.now() + 3600000, // 1小时后过期
+  duration: 5000 // 5秒间隔
+}
+sdk.triggerScreenshotConfig(JSON.stringify(config))
 
-**参数：**
-- `data` (any): 要发送的数据
+// 停止截图
+sdk.triggerScreenshotConfig(JSON.stringify({
+  ...config,
+  ttl: 0 // 禁用
+}))
+```
 
-#### `CustomerSDK.showNotification(badgeCount, options?)`
+#### showIcon() / hideIcon()
 
-显示通知徽章。
+显示/隐藏图标
 
-**参数：**
-- `badgeCount` (number | string): 徽章内容（数字或文本）
-- `options` (object?, 可选): { pulse?: boolean, autoHide?: number }
+```typescript
+sdk.showIcon()
+sdk.hideIcon()
+```
 
-#### `CustomerSDK.clearNotification()`
+#### getDeviceId()
 
-清除通知徽章。
+获取设备ID（md5后的）
 
-## 🌐 URL 参数
+```typescript
+const deviceId = sdk.getDeviceId()
+console.log('Device ID:', deviceId)
+```
 
-SDK会向iframe URL自动添加以下参数：
+#### getInitResult()
 
-- `Agent`: 代理商ID
-- `Authorization`: 认证令牌
-- `DeviceSign`: 设备指纹ID（通过FingerprintJS自动获取）
-- `Referrer`: 页面来源URL（通过`document.referrer`自动获取）
+获取初始化结果（包含设备ID等信息）
 
-**最终URL示例：**
-```
-https://chat.example.com?Agent=demo_app&Authorization=test_token_1703123456789&DeviceSign=abc123xyz&Referrer=https://example.com/page
+```typescript
+const initResult = sdk.getInitResult()
+if (initResult) {
+  console.log('Device ID:', initResult.deviceId)
+  console.log('Referrer:', initResult.referrer)
+  console.log('Timestamp:', initResult.timestamp)
+}
 ```
 
-## 🔧 响应式设计
+#### getScreenshotManager() / getIconManager()
 
-SDK自动检测设备类型并应用相应样式：
+获取管理器实例（用于高级操作）
 
-**PC模式：**
-- 悬浮图标：默认右下角，可自定义位置（x, y坐标），支持拖拽移动
-- 聊天窗口：居中弹窗，可通过iframe发送`close`消息关闭
+```typescript
+const screenshotManager = sdk.getScreenshotManager()
+const iconManager = sdk.getIconManager()
+```
 
-**移动端模式：**  
-- 悬浮图标：默认右下角，可自定义位置（x, y坐标），支持触摸拖拽移动
-- 聊天窗口：全屏显示，可通过iframe发送`close`消息关闭
+#### destroy()
 
-## 🛠️ 开发
+销毁 SDK
 
-### 环境要求
+```typescript
+sdk.destroy()
+```
 
-- Node.js >= 18
-- pnpm >= 8 (推荐) 或 npm >= 9
+## 完整工作流程
 
-### 安装依赖
+### 1. 初始化
 
-```bash
-# 使用pnpm (推荐)
-pnpm install
+```typescript
+const sdk = new CustomerSDK()
+const initResult = await sdk.init({
+  debug: true,
+  screenshot: { /* ... */ },
+  iconPosition: { x: 20, y: 80 },
+  target: '#app'
+}, {
+  sendData: (data) => {
+    // 处理截图数据
+  }
+})
 
-# 或者使用传统npm
-npm install
+// 获取设备ID等信息
+console.log('Device ID:', initResult.deviceId)
+console.log('Referrer:', initResult.referrer)
 ```
 
-### 开发命令
-
-```bash
-# 启动开发服务器
-pnpm dev
+### 2. 弹窗打开时启用截图
 
-# 启动Demo页面
-pnpm demo
+```typescript
+sdk.onIconClick(async () => {
+  openChatPopup()
+  const config = await fetchScreenshotConfig()
+  sdk.triggerScreenshotConfig(JSON.stringify(config))
+})
+```
 
-# 构建生产版本
-pnpm build
+### 3. 弹窗关闭时停止截图
 
-# 代码检查
-pnpm lint
+```typescript
+function closeChatPopup() {
+  closePopup()
+  sdk.triggerScreenshotConfig(JSON.stringify({
+    ...config,
+    ttl: 0
+  }))
+}
+```
 
-# 格式化代码
-pnpm format
+### 4. 清理
 
-# 检查依赖更新
-pnpm package-check
+```typescript
+onUnmounted(() => {
+  sdk?.destroy()
+})
 ```
 
-### 项目结构
+## 常见场景
 
-```
-src/
-├── core/           # 核心SDK功能
-│   ├── CustomerSDK.ts      # SDK主类
-│   ├── IconManager.ts      # 悬浮图标管理
-│   └── IframeManager.ts    # iframe管理
-├── types/              # TypeScript类型定义
-└── index.ts            # 主入口文件
-```
+### 只使用图标功能
 
-## 🔗 iframe 通信
+```typescript
+const sdk = new CustomerSDK()
+await sdk.init({
+  debug: true,
+  iconPosition: { x: 20, y: 80 },
+  target: '#app'
+})
 
-SDK通过postMessage与iframe进行通信：
+sdk.onIconClick(() => {
+  openChatPopup()
+})
+```
 
-```javascript
-// 向iframe发送数据
-CustomerSDK.sendToIframe({
-  type: 'userInfo',
-  data: {
-    profile: { name: 'John', avatar: '...' }
-  }
-});
+### 图标 + 截图
 
-// iframe接收示例
-window.addEventListener('message', (event) => {
-  if (event.data.type === 'userInfo') {
-    console.log('收到用户信息:', event.data.data);
+```typescript
+const sdk = new CustomerSDK()
+await sdk.init({
+  screenshot: {
+    engine: 'modern-screenshot',
+    quality: 0.15,
+    compress: true
   }
-});
+}, {
+  sendData: (data) => {
+    sendToBackend(data)
+  }
+})
 ```
 
-## 📄 许可证
+## 注意事项
+
+1. **调试模式**：生产环境请关闭 `debug: true`
+2. **截图性能**：合理设置截图间隔，避免过于频繁
+3. **内存管理**：及时调用 `destroy()` 清理资源
+4. **错误处理**：所有异步操作都应添加错误处理
+5. **CORS 问题**：如果遇到跨域问题，配置 `proxyUrl` 或调整 `corsMode`
 
-MIT License
+## 类型定义
+
+```typescript
+import type {
+  CustomerSDK,
+  ScreenshotMessageCallback,
+  SDKConfig,
+  ScreenshotOptions
+} from 'customer-chat-sdk'
+```
 
-## 🤝 贡献
+## 许可证
 
-欢迎提交 Issue 和 Pull Request！
+MIT