跳到主要内容

快速开始

融云控制台嵌入 SDK (@rongcloud/embed-console-sdk) 允许开发者将融云控制台的各个功能模块嵌入到自己的应用中,提供无缝的管理体验。本指南将帮助您完成融云控制台 SDK 的第一次集成。

主要特性

  • 嵌入控制台页面: 将用户管理、运营管理等功能页面直接集成到您的应用中。
  • 安全访问控制: 基于 Access Key 的安全认证机制。
  • 令牌管理: 提供访问令牌获取 API,支持开发者实现令牌刷新逻辑。
  • 响应式适配: SDK 会自动适应其容器的尺寸。为实现响应式效果,请确保您用于初始化 SDK 的 DOM 容器本身具有响应式布局(例如,宽度和高度使用百分比单位)。
  • 事件监听: 完整的事件系统,便于集成和调试。

准备工作

在开始集成之前,请确保您已经完成以下准备工作:

  1. 获取 Access Key
  2. 获取需要嵌入页面的代码 (page_code)

步骤 1: 安装 SDK

融云控制台 SDK 为开发者提供了便捷的控制台嵌入功能。您可以根据项目的技术栈选择合适的安装方式:使用 npm/yarn 包管理器安装,或通过 CDN 直接引入。

安装方式选择建议:

  • npm/yarn 安装:适用于使用现代前端框架(React、Vue、Angular 等)的项目。
  • CDN 引入:适用于传统的 HTML 页面或快速原型开发。

通过包管理器安装

bash
# 通过 npm 安装
npm install @rongcloud/embed-console-sdk

# 通过 yarn 安装
yarn add @rongcloud/embed-console-sdk

在项目中导入使用:

javascript
// ES6 模块导入
import RC from '@rongcloud/embed-console-sdk';

// CommonJS 导入
const RC = require('@rongcloud/embed-console-sdk');

// 验证导入成功
console.log('SDK 加载成功:', typeof RC);

通过 CDN 引入

html
<!-- 通过 CDN 引入 -->
<script src="https://cdn.ronghub.com/embed/console/embed-v0.0.1.js"></script>

<!-- 引入后,全局变量 RC 即可使用 -->
<script>
// 检查 SDK 是否加载成功
if (typeof RC !== 'undefined') {
console.log('融云嵌入 SDK 加载成功');
} else {
console.error('融云嵌入 SDK 加载失败');
}
</script>

步骤 2: 准备 HTML 容器

融云控制台通过 <iframe> 的方式嵌入到您的页面中,因此需要一个 HTML 容器元素来承载控制台界面。容器元素需要有明确的尺寸设置,以确保控制台能够正常显示和交互。

关键要求:

  • 容器必须有明确的宽高设置,避免显示异常。
  • 建议最小高度不少于 400px,确保界面元素完整显示。
  • 容器 ID 必须在页面中唯一,避免初始化冲突。

示例代码

html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>融云控制台集成示例</title>
<style>
/* 确保容器有明确的尺寸 */
#console-container {
width: 100%;
height: 600px;
min-height: 400px; /* 最小高度 */
border: 1px solid #e1e8ed;
border-radius: 8px;
background-color: #f8f9fa;
}
</style>
</head>
<body>
<!-- 控制台容器 -->
<div id="console-container"></div>

<!-- 引入 SDK -->
<script src="https://cdn.ronghub.com/embed/console/embed-v0.0.1.js"></script>
</body>
</html>

步骤 3: 获取访问令牌

在初始化控制台之前,需要通过融云的 API 获取访问令牌 URL。这个令牌 URL 包含了访问权限和页面配置信息,是控制台正常运行的重要凭证。

获取令牌的流程:

  1. 向融云服务器发送 POST 请求,包含 Access Key、页面代码等参数。
  2. 服务器验证 Access Key 的有效性和权限。
  3. 返回包含访问令牌的完整 URL,用于后续的控制台初始化。

重要提示: 在生产环境中,建议将此操作放在您的后端服务器执行,避免在前端暴露 Access Key。

示例代码

javascript
/**
* 获取访问令牌
* @param {string} accessKey - 融云 Access Key
* @param {string} pageCode - 页面代码
* @param {number} usefulLife - 令牌有效期,单位:秒(取值范围: 1-31536000,建议: 3600-86400)
* @param {string} apiUrl - API 地址(可选,默认根据环境自动选择)
* @returns {Promise<string>} 访问令牌 URL
*/
async function getAccessToken(accessKey, pageCode, usefulLife = 36000, apiUrl) {
try {
// 使用默认 API 地址
const tokenApiUrl = apiUrl || 'https://embed-console.rongcloud.net/embed/access/token';

const response = await fetch(tokenApiUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
access_key: accessKey,
page_code: pageCode,
useful_life: usefulLife
})
});

if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const result = await response.json();

if (result.code === 10000 && result.data) {
return result.data; // 返回完整的访问令牌 URL
} else {
throw new Error(result.message || '获取访问令牌失败');
}
} catch (error) {
console.error('获取访问令牌失败:', error);
throw error;
}
}

步骤 4: 初始化控制台

完成前面的准备工作后,最后一步是使用获取到的访问令牌 URL 来初始化融云控制台。这个过程包括调用 RC SDK 的 init() 方法、配置参数、以及设置事件监听器来处理各种状态变化。

初始化过程主要包含以下几个关键步骤:

  1. 准备配置参数:包括 Access Key、页面代码、容器 ID 等。
  2. 获取访问令牌:调用之前定义的 getAccessToken() 函数。
  3. 调用 RC.init():使用令牌 URL 初始化控制台实例。
  4. 设置事件监听:监听令牌过期、初始化错误等重要事件。
  5. 错误处理:确保初始化失败时能够优雅地处理。

示例代码

javascript
async function initConsole() {
try {
// 配置参数
const config = {
accessKey: 'YOUR_ACCESS_KEY', // 替换为您的 Access Key
pageCode: 'user_manage', // 替换为所需的页面代码
containerId: 'console-container', // 容器元素 ID
showMenu: true, // 是否显示菜单
usefulLife: 36000 // 令牌有效期(10小时)
};

// 获取访问令牌
const accessTokenUrl = await getAccessToken(
config.accessKey,
config.pageCode,
config.usefulLife
);

// 初始化 RC 实例
const instance = RC.init(
config.containerId,
accessTokenUrl,
config.showMenu
);

// 注册事件监听器
setupEventListeners(instance);

console.log('融云控制台初始化成功');
return instance;

} catch (error) {
console.error('初始化失败:', error);
throw error;
}
}

function setupEventListeners(instance) {
// 获取所有可用事件
const events = RC.getEventNames();

events.forEach(eventName => {
instance.on(eventName, (event) => {
console.log(`事件触发 [${eventName}]:`, event);

// 处理特定事件
switch (eventName) {
case 'expired':
console.warn('访问令牌已过期,需要刷新');
handleTokenExpired();
break;
case 'initError':
console.error('初始化错误:', event);
break;
default:
// 处理其他事件
break;
}
});
});
}

async function handleTokenExpired() {
// 令牌过期处理逻辑
console.log('正在刷新访问令牌...');
// 重新获取令牌并重新初始化
}

完整示例

将以上步骤整合为一个完整的示例:

html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>融云控制台嵌入页面(demo)</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
margin: 20px;
background: #f5f5f5;
}
.container {
max-width: 1200px;
margin: 0 auto;
background: white;
padding: 20px;
border-radius: 8px;
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
#console-container {
width: 100%;
height: 600px;
border: 1px solid #e1e8ed;
border-radius: 8px;
background-color: #f8f9fa;
margin-top: 20px;
}
.status {
padding: 10px;
margin: 10px 0;
border-radius: 4px;
}
.status.success { background: #d4edda; color: #155724; }
.status.error { background: #f8d7da; color: #721c24; }
.status.info { background: #cce5ff; color: #004085; }
button {
background: #007bff;
color: white;
border: none;
padding: 10px 20px;
border-radius: 4px;
cursor: pointer;
margin: 10px 0;
}
button:hover { background: #0056b3; }
</style>
</head>
<body>
<div class="container">
<h1>融云控制台嵌入页面(demo)</h1>

<div id="status" class="status" style="display: none;"></div>

<button onclick="initConsole()">初始化控制台</button>

<div id="console-container"></div>
</div>

<script src="https://cdn.ronghub.com/embed/console/embed-v0.0.1.js"></script>
<script>
// --- 配置区域 ---
const ACCESS_KEY = "YOUR_ACCESS_KEY"; // 替换为您的 Access Key
const PAGE_CODE = "user_manage"; // 您希望嵌入的页面代码
// --- 配置区域结束 ---

let consoleInstance;

// 显示状态信息
function showStatus(message, type = 'info') {
const statusEl = document.getElementById('status');
statusEl.textContent = message;
statusEl.className = `status ${type}`;
statusEl.style.display = 'block';
}

// 1. 从您的服务端获取访问令牌 URL
async function getAccessToken(accessKey, pageCode, usefulLife = 36000) {
// 注意:在生产环境中,此操作应在您的后端服务器上完成,以避免暴露 Access Key。
// 本示例为方便前端直接测试,在浏览器中发起请求。
const apiUrl = 'https://embed-console.rongcloud.net/embed/access/token';

showStatus('正在获取访问令牌...');
const response = await fetch(apiUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
access_key: accessKey,
page_code: pageCode,
useful_life: usefulLife
})
});

if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const result = await response.json();

if (result.code === 10000 && result.data) {
showStatus('成功获取访问令牌!', 'success');
return result.data;
} else {
throw new Error(result.message || '获取访问令牌失败');
}
}

// 2. 初始化控制台
async function initConsole() {
// 检查 SDK 是否加载
if (typeof RC === 'undefined') {
showStatus('SDK 未加载,请刷新页面重试', 'error');
return;
}

if (ACCESS_KEY === "YOUR_ACCESS_KEY") {
showStatus('请先在脚本中替换 YOUR_ACCESS_KEY', 'error');
return;
}

try {
const tokenUrl = await getAccessToken(ACCESS_KEY, PAGE_CODE);

showStatus('正在初始化控制台...');

// 如果已存在实例,先销毁
if (consoleInstance && typeof RC.destroy === 'function') {
RC.destroy();
consoleInstance = null;
}

// 使用正确的 SDK API
consoleInstance = RC.init(
'console-container', // 容器元素 ID
tokenUrl, // 访问令牌 URL
true // 是否显示菜单
);

// 设置事件监听(如果支持)
if (RC.getEventNames && typeof RC.getEventNames === 'function') {
const events = RC.getEventNames();
events.forEach(eventName => {
if (consoleInstance && typeof consoleInstance.on === 'function') {
consoleInstance.on(eventName, (event) => {
console.log(`RC 事件 [${eventName}]:`, event);

if (eventName === 'expired') {
showStatus('访问令牌已过期,需要刷新', 'error');
} else if (eventName === 'initError') {
showStatus(`初始化错误: ${event.error || '未知错误'}`, 'error');
}
});
}
});
}

showStatus('控制台初始化成功!', 'success');

} catch (error) {
showStatus(`初始化失败: ${error.message}`, 'error');
console.error('初始化失败:', error);
}
}

// 页面加载完成提示
window.addEventListener('load', () => {
// 检查 SDK 是否加载成功
if (typeof RC !== 'undefined') {
showStatus('页面已就绪,点击按钮开始初始化控制台。', 'success');
console.log('融云嵌入 SDK 加载成功');
} else {
showStatus('SDK 加载失败,请检查网络连接或重新刷新页面', 'error');
console.error('融云嵌入 SDK 加载失败');
}
});
</script>
</body>
</html>

快速测试

  1. 复制上面的完整示例*到一个 HTML 文件。

  2. 替换 YOUR_ACCESS_KEY 为您的实际 Access Key。

  3. 为避免 CORS 问题,建议使用本地服务器打开:

    bash
    python3 -m http.server 8080
    # 访问 http://localhost:8080
  4. 点击初始化控制台按钮。

  5. 查看嵌入的控制台,检查是否正常加载。

参考与源码