跳到主要内容

快速开始

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

主要特性​

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

准备工作​

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

  1. 获取 Access Key
  2. 获取需要嵌入页面的代码 (page_code)
  3. 确认浏览器兼容性和 Safari 设置

步骤 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 加载成功');
    // 注意：通过 CDN 引入时，需要使用 RC.default 访问 SDK API
    // 例如：RC.default.init(), RC.default.getEventNames()
} else {
    console.error('融云嵌入 SDK 加载失败');
}
</script>

重要提示：API 调用差异​

根据您的安装方式，SDK 的 API 调用方式有所不同：

安装方式初始化方法获取事件列表示例
npm/yarnRC.init()RC.getEventNames()const instance = RC.init(...)
CDN 引入RC.default.init()RC.default.getEventNames()const instance = RC.default.init(...)

原因说明：

  • 通过 npm/yarn 安装时，使用 ES6 模块导入，可以直接访问导出的对象。
  • 通过 CDN 引入时，SDK 使用 UMD 格式，需要通过 RC.default 访问默认导出。

完整示例对比：

javascript
// npm/yarn 方式
import RC from '@rongcloud/embed-console-sdk';
const instance = RC.init('container', tokenUrl, true);
const events = RC.getEventNames();

// CDN 方式
const instance = RC.default.init('container', tokenUrl, true);
const events = RC.default.getEventNames();

步骤 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.cn/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. 错误处理：确保初始化失败时能够优雅地处理。

示例代码​

根据您的安装方式，选择对应的示例代码：

方式 1：npm/yarn 安装​

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 实例（npm/yarn 方式）
        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) {
    // 获取所有可用事件（npm/yarn 方式）
    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('正在刷新访问令牌...');
    // 重新获取令牌并重新初始化
}

方式 2：CDN 引入​

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 实例（CDN 方式）
        const instance = RC.default.init(
            config.containerId,
            accessTokenUrl,
            config.showMenu
        );

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

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

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

function setupEventListeners(instance) {
    // 获取所有可用事件（CDN 方式）
    const events = RC.default.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 5px 10px 0;
        }
        button:hover { background: #0056b3; }
        button:disabled {
            background: #6c757d;
            cursor: not-allowed;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>融云控制台嵌入页面（demo）</h1>
        
        <div id="status" class="status" style="display: none;"></div>
        
        <button onclick="initConsole()">初始化控制台</button>
        <button onclick="destroyConsole()">销毁控制台</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.cn/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;
            }

            // 如果已经初始化过，提示用户
            if (consoleInstance) {
                showStatus('控制台已初始化，无需重复操作', 'info');
                return;
            }

            try {
                const tokenUrl = await getAccessToken(ACCESS_KEY, PAGE_CODE);
                
                showStatus('正在初始化控制台...');
                
                // 使用正确的 SDK API
                // 注意：通过 CDN 引入时需要使用 RC.default.init
                consoleInstance = RC.default.init(
                    'console-container',  // 容器元素 ID
                    tokenUrl,            // 访问令牌 URL
                    true                 // 是否显示菜单
                );

                // 设置事件监听（如果支持）
                // 注意：通过 CDN 引入时需要使用 RC.default.getEventNames
                if (RC.default.getEventNames && typeof RC.default.getEventNames === 'function') {
                    const events = RC.default.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);
            }
        }
        
        // 3. 销毁控制台实例
        function destroyConsole() {
            if (consoleInstance && typeof consoleInstance.destory === 'function') {
                consoleInstance.destory();
                consoleInstance = null;
                showStatus('控制台已销毁', 'info');
                console.log('控制台实例已销毁');
            } else {
                showStatus('没有需要销毁的控制台实例', 'info');
            }
        }
        
        // 页面加载完成提示
        window.addEventListener('load', () => {
            // 检查 SDK 是否加载成功
            if (typeof RC !== 'undefined') {
                showStatus('页面已就绪，点击按钮开始初始化控制台。', 'success');
                console.log('融云嵌入 SDK 加载成功');
            } else {
                showStatus('SDK 加载失败，请检查网络连接或重新刷新页面', 'error');
                console.error('融云嵌入 SDK 加载失败');
            }
        });

        // 页面关闭时自动销毁实例
        window.addEventListener('beforeunload', () => {
            if (consoleInstance && typeof consoleInstance.destory === 'function') {
                consoleInstance.destory();
                console.log('页面关闭，已自动销毁控制台实例');
            }
        });
    </script>
</body>
</html>

快速测试​

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

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

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

    bash
    python3 -m http.server 8080
    # 访问 http://localhost:8080

  4. 点击初始化控制台按钮。

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

参考与源码​