💬 iframe 集成 AgentOS3 聊天页面

本文档介绍如何在您的应用中集成 AgentOS3 聊天页面，支持通过 iframe 嵌入的方式快速接入智能对话功能。

🚀 快速开始

基础集成

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AgentOS3 聊天集成</title>
    <style>
        body, html {
            margin: 0;
            padding: 0;
            height: 100%;
            width: 100%;
            overflow: hidden;
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
        }
        
        .chat-container {
            width: 100%;
            height: 100%;
            display: flex;
            justify-content: center;
            align-items: center;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        }
        
        .chat-iframe {
            width: calc(100% - 48px);
            height: calc(100% - 48px);
            border: 24px solid #ECF2FE;
            border-radius: 12px;
            box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
        }
        
        /* 响应式设计 */
        @media (max-width: 768px) {
            .chat-iframe {
                width: calc(100% - 16px);
                height: calc(100% - 16px);
                border: 8px solid #ECF2FE;
            }
        }
    </style>
</head>
<body>
    <div class="chat-container">
        <iframe 
            id="chatFrame"
            class="chat-iframe"
            src="https://console-beta1.e-tudou.com/new-agentos/chat/agent_00000000?access_key=YOUR_ACCESS_KEY"
            title="AgentOS3 智能助手"
            frameborder="0"
            allow="microphone; camera">
        </iframe>
    </div>
</body>
</html>

⚙️ 配置说明

URL 参数

聊天页面 URL 格式：{BASE_URL}/new-agentos/chat/{AGENT_ID}?access_key={ACCESS_KEY}

参数	说明	示例
`BASE_URL`	服务器地址	`https://console-beta1.e-tudou.com`
`AGENT_ID`	智能体 ID	`agent_00000000`
`ACCESS_KEY`	访问密钥	`e87b241b-10ea-42f8-b2f7-e5682fa053a4`

环境地址

javascript

// 不同环境的服务器地址
const ENVIRONMENTS = {
  // 开发环境
  development: 'http://localhost:3610',
  
  // 测试环境
  beta: 'https://console-beta1.e-tudou.com',
  
  // 生产环境
  production: 'https://console.i-tudou.com'
};

// 动态构建聊天 URL
function buildChatUrl(env, agentId, accessKey) {
  const baseUrl = ENVIRONMENTS[env];
  return `${baseUrl}/new-agentos/chat/${agentId}?access_key=${accessKey}`;
}

🎨 自定义样式

主题定制

css

/* 深色主题 */
.dark-theme {
  background: linear-gradient(135deg, #2c3e50 0%, #34495e 100%);
}

.dark-theme .chat-iframe {
  border-color: #34495e;
}

/* 简约主题 */
.minimal-theme .chat-iframe {
  border: 1px solid #e1e5e9;
  border-radius: 8px;
}

/* 全屏模式 */
.fullscreen .chat-iframe {
  width: 100%;
  height: 100%;
  border: none;
  border-radius: 0;
}

响应式布局

css

/* 移动端优化 */
@media (max-width: 480px) {
  .chat-container {
    padding: 8px;
  }
  
  .chat-iframe {
    width: 100%;
    height: 100%;
    border: none;
  }
}

/* 平板端适配 */
@media (min-width: 481px) and (max-width: 1024px) {
  .chat-iframe {
    width: calc(100% - 32px);
    height: calc(100% - 32px);
    border-width: 16px;
  }
}

🔒 安全考虑

Access Key 管理

javascript

// ✅ 推荐：从服务器获取临时访问密钥
async function getTemporaryAccessKey(userId) {
  const response = await fetch('/api/chat/access-key', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${userToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ userId })
  });
  
  const { accessKey, expiresIn } = await response.json();
  return { accessKey, expiresIn };
}

// ❌ 不推荐：在前端硬编码访问密钥
const accessKey = 'b344fdf7-2306-401e-b1f7-3e326afbb00c'; // 不安全

域名白名单

确保在 AgentOS3 后台配置允许的嵌入域名：

javascript

// 检查父页面域名
function validateParentDomain() {
  const allowedDomains = [
    'https://your-app.com',
    'https://app.your-domain.com'
  ];
  
  const parentOrigin = window.parent.location.origin;
  
  if (!allowedDomains.includes(parentOrigin)) {
    console.error('未授权的域名访问');
    return false;
  }
  
  return true;
}

🐛 常见问题

Q1: iframe 无法加载聊天页面

可能原因：

Access Key 无效或过期
域名未在白名单中
网络连接问题

解决方案：

javascript

// 添加错误处理
const iframe = document.getElementById('chatFrame');

iframe.addEventListener('load', () => {
  console.log('聊天页面加载成功');
});

iframe.addEventListener('error', (e) => {
  console.error('聊天页面加载失败:', e);
  // 显示错误提示或重试机制
});

// 超时检测
setTimeout(() => {
  if (!iframe.contentDocument) {
    console.warn('聊天页面加载超时');
    // 执行重试逻辑
  }
}, 10000);

Q2: 移动端显示异常

解决方案：

css

/* 移动端适配 */
@media (max-width: 768px) {
  .chat-iframe {
    width: 100vw;
    height: 100vh;
    border: none;
    position: fixed;
    top: 0;
    left: 0;
    z-index: 1000;
  }
}

Q3: 跨域通信问题

解决方案：

javascript

// 监听来自聊天页面的消息
window.addEventListener('message', (event) => {
  // 验证消息来源
  if (event.origin !== 'https://console-beta1.e-tudou.com') {
    return;
  }
  
  const { type, data } = event.data;
  
  switch (type) {
    case 'chat_ready':
      console.log('聊天页面已准备就绪');
      break;
    case 'chat_error':
      console.error('聊天错误:', data);
      break;
  }
});

📊 性能优化

懒加载

javascript

// 延迟加载聊天页面
function lazyLoadChat() {
  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const iframe = entry.target;
        iframe.src = iframe.dataset.src;
        observer.unobserve(iframe);
      }
    });
  });

  const iframe = document.querySelector('.chat-iframe');
  iframe.dataset.src = iframe.src;
  iframe.src = '';
  observer.observe(iframe);
}

预加载

javascript

// 预加载聊天资源
function preloadChatResources() {
  const link = document.createElement('link');
  link.rel = 'prefetch';
  link.href = 'https://console-beta1.e-tudou.com/new-agentos/chat/';
  document.head.appendChild(link);
}

🔐 Token 过期处理

当内嵌的聊天应用遇到 token 过期情况时，会自动向父窗口发送消息以触发登录流程：

javascript

// 在内嵌应用中处理 token 过期事件
window.parent.postMessage(
  {
    type: 'TOKEN_EXPIRED',
    url: window.location.href,
  },
  '*'
);

父页面可以通过监听此消息来执行相应的登录跳转或其他操作：

javascript

// 在父页面中监听 token 过期消息
window.addEventListener('message', (event) => {
  // 注意：在生产环境中应该验证消息来源
  if (event.data.type === 'TOKEN_EXPIRED') {
    console.log('Token 已过期，跳转到登录页面...');
    // 实现跳转到登录页的逻辑
    window.location.href = '/login';
  }
});

📖 相关文档

🎯 总结

通过本文档，您可以：

快速集成: 使用 iframe 方式快速嵌入聊天功能
灵活定制: 支持主题、样式和响应式布局定制
多端适配: 支持 Web、React Native、Flutter 等平台
安全可靠: 提供访问控制和安全最佳实践
性能优化: 包含懒加载、预加载等优化方案

开始使用 AgentOS3 聊天页面，为您的应用添加强大的 AI 对话能力！

💬 iframe 集成 AgentOS3 聊天页面 ​

🚀 快速开始 ​

基础集成 ​

⚙️ 配置说明 ​

URL 参数 ​

环境地址 ​

🎨 自定义样式 ​

主题定制 ​

响应式布局 ​

🔒 安全考虑 ​

Access Key 管理 ​

域名白名单 ​

🐛 常见问题 ​

Q1: iframe 无法加载聊天页面 ​

Q2: 移动端显示异常 ​

Q3: 跨域通信问题 ​

📊 性能优化 ​

懒加载 ​

预加载 ​

🔐 Token 过期处理 ​

📖 相关文档 ​

🎯 总结 ​

💬 iframe 集成 AgentOS3 聊天页面

🚀 快速开始

基础集成

⚙️ 配置说明

URL 参数

环境地址

🎨 自定义样式

主题定制

响应式布局

🔒 安全考虑

Access Key 管理

域名白名单

🐛 常见问题

Q1: iframe 无法加载聊天页面

Q2: 移动端显示异常

Q3: 跨域通信问题

📊 性能优化

懒加载

预加载

🔐 Token 过期处理

📖 相关文档

🎯 总结