一个企业级实时聊天系统 IM-Parent，SDK 集成指南

IM-Parent SDK 是一个轻量级的嵌入式聊天窗口组件，支持快速集成到任何网站。本指南详细介绍如何集成和使用 SDK,您可从https://im.aihkj.com/promo/doc获取最新sdk

1.项目部分截图

2. 初始化 SDK

javascript 复制代码

// 创建 SDK 实例
const imChat = new ImChat({
  // 必填：访客唯一标识（可选，不提供则自动生成）
  visitorId: 'visitor_123',
  
  // 必填：企业密钥（从后台获取）
  secret: 'your_company_secret_key',
  
  // 可选：产品名称（用于日志追踪）
  productName: 'my_website',
  
  // 可选：自定义访客信息
  visitorInfo: {
    name: '张三',
    phone: '13800138000',
    email: 'zhangsan@example.com'
  }
});

// 监听连接状态
imChat.on('connected', () => {
  console.log('已连接到客服系统');
});

imChat.on('disconnected', () => {
  console.log('连接已断开');
});

// 监听收到的消息
imChat.on('message', (msg) => {
  console.log('收到消息:', msg);
});

3. 打开聊天窗口

javascript 复制代码

// 方式一：直接打开
imChat.openChat();

// 方式二：通过按钮触发
document.getElementById('chat-button').addEventListener('click', () => {
  imChat.openChat();
});

// 方式三：通过全局 API（如果已在 window 上注册）
window.ImChat.openChat();

4. 发送消息

javascript 复制代码

// 发送文本消息
imChat.sendMessage({
  type: 'text',
  content: '你好，我需要帮助'
});

// 发送图片消息
imChat.sendMessage({
  type: 'image',
  content: 'https://example.com/image.jpg'
});

集成示例

HTML 中直接使用

html 复制代码

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>聊天系统集成示例</title>
  
  <!-- 引入 SDK 样式 -->
  <link rel="stylesheet" href="https://im.aihkj.com/im-sdk/dist/style.css">
  
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto;
      margin: 0;
      padding: 20px;
    }
    
    #chat-button {
      position: fixed;
      bottom: 30px;
      right: 30px;
      width: 60px;
      height: 60px;
      border-radius: 50%;
      background: #4CAF50;
      color: white;
      border: none;
      cursor: pointer;
      font-size: 24px;
      box-shadow: 0 4px 8px rgba(0,0,0,0.2);
      z-index: 100;
    }
    
    #chat-button:hover {
      background: #45a049;
      box-shadow: 0 6px 12px rgba(0,0,0,0.3);
    }
  </style>
</head>
<body>
  <h1>欢迎来到我们的网站</h1>
  <p>有问题？点击右下角按钮与客服沟通</p>
  
  <!-- 聊天按钮 -->
  <button id="chat-button">💬</button>
  
  <!-- 引入 SDK -->
  <script src="https://im.aihkj.com/im-chat.min.js"></script>
  
  <script>
    // 初始化 SDK
    const imChat = new ImChat({
      secret: 'your_secret_key',
      productName: 'my_website',
      visitorInfo: {
        name: '访客',
        source: 'website'
      }
    });
    
    // 绑定按钮事件
    document.getElementById('chat-button').addEventListener('click', () => {
      imChat.openChat();
    });
    
    // 监听消息
    imChat.on('message', (msg) => {
      if (msg.sender === 'cs') {
        // 客服回复时的处理
        console.log('客服:', msg.content);
      }
    });
    
    // 监听连接状态
    imChat.on('connected', () => {
      console.log('已连接到客服系统');
      document.getElementById('chat-button').style.background = '#4CAF50';
    });
    
    imChat.on('disconnected', () => {
      console.log('连接断开');
      document.getElementById('chat-button').style.background = '#f44336';
    });
  </script>
</body>
</html>

React 中使用

javascript 复制代码

import React, { useEffect, useState } from 'react';
import ImChat from 'im-chat-sdk';
import 'im-chat-sdk/dist/style.css';

export default function ChatWidget() {
  const [imChat, setImChat] = useState(null);
  const [status, setStatus] = useState('disconnected');

  useEffect(() => {
    // 初始化 SDK
    const instance = new ImChat({
      secret: 'your_secret_key',
      productName: 'react_app',
      visitorInfo: {
        name: '访客',
        source: 'react_app'
      }
    });

    // 监听状态变化
    instance.on('statusChange', (newStatus) => {
      setStatus(newStatus);
    });

    // 监听消息
    instance.on('message', (msg) => {
      if (msg.sender === 'cs') {
        console.log('客服消息:', msg.content);
      }
    });

    setImChat(instance);

    // 清理
    return () => {
      instance.destroy();
    };
  }, []);

  const handleOpenChat = () => {
    imChat?.openChat();
  };

  return (
    <div>
      <button 
        onClick={handleOpenChat}
        style={{
          position: 'fixed',
          bottom: '30px',
          right: '30px',
          width: '60px',
          height: '60px',
          borderRadius: '50%',
          background: status === 'connected' ? '#4CAF50' : '#f44336',
          color: 'white',
          border: 'none',
          cursor: 'pointer',
          fontSize: '24px'
        }}
      >
        💬
      </button>
    </div>
  );
}

Vue 3 中使用

javascript 复制代码

<template>
  <div>
    <button 
      @click="openChat"
      class="chat-button"
      :class="{ connected: status === 'connected' }"
    >
      💬
    </button>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import ImChat from 'im-chat-sdk';
import 'im-chat-sdk/dist/style.css';

const imChat = ref(null);
const status = ref('disconnected');

onMounted(() => {
  // 初始化 SDK
  imChat.value = new ImChat({
    secret: 'your_secret_key',
    productName: 'vue_app',
    visitorInfo: {
      name: '访客',
      source: 'vue_app'
    }
  });

  // 监听状态
  imChat.value.on('statusChange', (newStatus) => {
    status.value = newStatus;
  });

  // 监听消息
  imChat.value.on('message', (msg) => {
    if (msg.sender === 'cs') {
      console.log('客服消息:', msg.content);
    }
  });
});

onUnmounted(() => {
  imChat.value?.destroy();
});

const openChat = () => {
  imChat.value?.openChat();
};
</script>

<style scoped>
.chat-button {
  position: fixed;
  bottom: 30px;
  right: 30px;
  width: 60px;
  height: 60px;
  border-radius: 50%;
  background: #f44336;
  color: white;
  border: none;
  cursor: pointer;
  font-size: 24px;
  transition: all 0.3s ease;
  z-index: 100;
}

.chat-button:hover {
  box-shadow: 0 6px 12px rgba(0, 0, 0, 0.3);
}

.chat-button.connected {
  background: #4CAF50;
}
</style>

高级用法

自定义访客信息

javascript 复制代码

const imChat = new ImChat({
  secret: 'your_secret_key',
  visitorInfo: {
    // 基本信息
    name: '客户名称',
    phone: '联系电话',
    email: '邮箱地址',
    
    // 自定义字段
    customField1: '自定义值1',
    customField2: '自定义值2',
    
    // 访问来源
    source: 'website',
    
    // 用户标签
    tags: ['vip', 'new_user'],
    
    // 额外信息
    metadata: {
      orderId: '123456',
      productName: '某产品'
    }
  }
});

监听所有事件

javascript 复制代码

imChat.on('connected', () => console.log('✓ 连接成功'));
imChat.on('disconnected', () => console.log('✗ 连接断开'));
imChat.on('message', (msg) => console.log('📨 消息:', msg));
imChat.on('statusChange', (newStatus) => console.log('状态:', newStatus));
imChat.on('error', (error) => console.error('错误:', error));

// 监听多个相同事件处理器
imChat.on('message', (msg) => {
  if (msg.type === 'text') {
    // 处理文本消息
  }
});

imChat.on('message', (msg) => {
  if (msg.type === 'image') {
    // 处理图片消息
  }
});

动态更新访客信息

javascript 复制代码

// 用户登录后更新信息
function onUserLogin(user) {
  imChat.setVisitorInfo({
    name: user.name,
    phone: user.phone,
    email: user.email,
    userId: user.id  // 关联到系统用户 ID
  });
}

// 用户结账时添加订单信息
function onCheckout(order) {
  imChat.setVisitorInfo({
    metadata: {
      orderId: order.id,
      totalPrice: order.total,
      items: order.items
    }
  });
}

常见问题

Q1: 如何获取企业密钥 (secret)?

A: 登录客服后台系统，在"系统设置" > "企业配置" 中可获取密钥。

Q2: 访客 ID 可以不提供吗?

A: 可以。不提供时 SDK 会自动生成唯一 ID，并存储在浏览器本地。如果需要关联用户系统，请明确提供。

Q3: 如何在页面加载时自动打开聊天窗口?

javascript 复制代码

imChat.on('connected', () => {
  // 连接成功后自动打开
  imChat.openChat();
});

Q4: SDK 支持离线消息吗?

A: 支持。访客离线时发送的消息会自动保存，重新连接后会推送给访客。

Q5: 如何在多个页面间保持聊天记录?

A : 使用相同的 visitorId 初始化 SDK，聊天记录会自动恢复。

Q6: 支持自定义样式吗?

A: 支持。SDK 提供 CSS 类名，可通过覆盖样式表来自定义外观。

css 复制代码

/* 自定义聊天窗口背景色 */
.im-chat-container {
  --primary-color: #4CAF50;
  --bg-color: #ffffff;
}

Q7: 如何处理消息发送失败?

javascript 复制代码

imChat.on('error', (error) => {
  if (error.code === 'SEND_FAILED') {
    console.log('消息发送失败，请稍后重试');
    // 重试逻辑
  }
});

Q8: SDK 对浏览器有什么要求?

A: 支持所有现代浏览器（Chrome, Firefox, Safari, Edge）。IE 11 需要 polyfills。

性能优化

1. 延迟初始化

javascript 复制代码

// 只在用户点击时初始化
let imChat = null;

document.getElementById('chat-button').addEventListener('click', () => {
  if (!imChat) {
    imChat = new ImChat({
      secret: 'your_secret_key'
    });
  }
  imChat.openChat();
});

2. 资源清理

javascript 复制代码

// 在页面卸载时销毁实例
window.addEventListener('beforeunload', () => {
  imChat?.destroy();
});

3. 事件去抖动

javascript 复制代码

// 避免频繁处理消息事件
let messageTimeout = null;

imChat.on('message', (msg) => {
  clearTimeout(messageTimeout);
  messageTimeout = setTimeout(() => {
    // 处理消息
  }, 200);
});

部署注意事项

域名配置

SDK 使用固定域名访问后端：

WebSocket: wss://im.aihkj.com/im/ws
API: https://im.aihkj.com

重要: 确保你的网站所在域名能访问上述服务。如需使用自定义域名，请在初始化时配置：

javascript 复制代码

const imChat = new ImChat({
  secret: 'your_secret_key',
  serverUrl: 'wss://your-domain.com',  // 自定义 WebSocket 地址
  apiUrl: 'https://your-domain.com'    // 自定义 API 地址
});

HTTPS/SSL

SDK 要求在 HTTPS 环境下运行。如果页面是 HTTP，WebSocket 将无法连接。

Nginx 配置示例:

nginx 复制代码

server {
    listen 443 ssl;
    server_name im.aihkj.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://backend:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
    
    location /im/ws {
        proxy_pass http://backend:8088;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_read_timeout 3600s;
    }
}

CSP (Content Security Policy)

如果你的网站使用 CSP，确保允许加载 SDK：

html 复制代码

<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self' https://im.aihkj.com; 
               connect-src 'self' https://im.aihkj.com wss://im.aihkj.com;">