tencent cloud

实时音视频

文档实时音视频视频会议 SDK含 UI 集成多人会议快速接入内嵌页面（iframe）

内嵌页面（iframe）

Download
聚焦模式
字号
最后更新时间： 2026-05-08 17:11:13
本文档介绍如何通过 iframe 方式快速将 TUIRoomKit 的音视频会议能力集成到您的 Web 应用中。这种方式具有良好的环境隔离性，开发者无需关注复杂的 UI 组件逻辑，仅需通过 URL 参数传递关键信息即可实现视频会议功能。
适用场景：快速跑通流程、跨技术栈集成、快速嵌入会议功能。
核心功能：支持主持人创建会议、普通用户加入会议、屏幕分享等。


前提条件

开通服务

请参考 开通服务 领取 TUIRoomKit 体验版，获取 SDKAppID 和 SDKSecretKey。
SDKAppID：应用标识，腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey：应用密钥，用于初始化配置文件的密钥信息。

环境准备

由于浏览器安全策略，访问摄像头和麦克风必须满足以下任一条件：
生产环境：父页面与 iframe 页面均必须部署在 HTTPS 协议下。
开发环境：支持 localhost 访问。
注意：
HTTP 协议（非 localhost）将导致音视频设备采集功能不可用。

iframe 接入

步骤1：构建并部署 TUIRoomKit 页面

您需要先构建一个专门用于 iframe 嵌入的 TUIRoomKit 项目。
1. 创建新的 vue3 项目。
npm
pnpm
yarn
npm create vite@latest roomkit-vue3 -- --template vue
pnpm create vite roomkit-vue3 --template vue
yarn create vite roomkit-vue3 --template vue
2. 安装 TUIRoomKit 相关依赖。
npm
pnpm
yarn
cd roomkit-vue3/

npm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api 
cd roomkit-vue3/

pnpm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
cd roomkit-vue3/

yarn add @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
3. 修改 roomkit-vue3/src/App.vue 文件。
<template>
  <UIKitProvider theme="light" language="zh-CN">
    <ConferenceMainView v-if="isPC"></ConferenceMainView>
    <ConferenceMainViewH5 v-else></ConferenceMainViewH5>
  </UIKitProvider>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
import { ConferenceMainView, ConferenceMainViewH5, conference } from '@tencentcloud/roomkit-web-vue3';
import { getPlatform } from '@tencentcloud/universal-api';
import { RoomType } from 'tuikit-atomicx-vue3/room';

const isPC = ref(getPlatform() === 'pc');

function getUrlParam(key) {
  const params = new URLSearchParams(window.location.search);
  return params.get(key) || '';
}

const sdkAppId = Number(getUrlParam('sdkAppId'));
const userId = getUrlParam('userId');
const userSig = getUrlParam('userSig');
const roomId = getUrlParam('roomId');
const action = getUrlParam('action') || 'start';

onMounted(async () => {
  try {
    await conference.login({ sdkAppId, userId, userSig });
    if (action === 'start') {
      await conference.start({ roomId, roomType: RoomType.Standard });
    } else {
      await conference.join({ roomId, roomType: RoomType.Standard });
    }
  } catch (error) {
    console.error('初始化失败：', error);
  }
});
</script>

<style>
html, body {
  padding: 0 !important;
  margin: 0 !important;
}

#app {
  width: 100% !important;
  height: 100% !important;
  padding: 0 !important;
  margin: 0 !important;
  max-width: 100% !important;
  max-height: 100% !important;
  text-align: left !important;
  overflow: hidden;
}
</style>

4. 构建与发布。
cd roomkit-vue3/
npm run build
将生成的静态资源（dist 目录）部署到您的 Web 服务器（例如 Nginx、COS 等）以获取访问链接。

步骤2：在父页面中嵌入 iframe

在您的 HTML/Vue/React 业务页面中插入 <iframe> 标签并绑定 src 属性为您部署的 TUIRoomKit 页面地址。
注意：
权限配置：iframe 必须配置 allow 属性，否则浏览器会拦截摄像头、麦克风和屏幕分享权限。
参数传递：TUIRoomKit 页面地址需携带以下关键参数以保证功能正常：
sdkAppId：数字类型，应用标识。
userId：字符串，用户 ID。
userSig：字符串，用户签名（生成方式请参考 用户鉴权）。
roomId：字符串，房间号。
action：字符串，操作类型。创建房间传 start，加入房间传 join。
<iframe
  id="tuiRoomFrame"
  src="https://your-domain.com/index.html?sdkAppId=xxxx&userId=xxxx&userSig=xxxx&roomId=xxxx&action=start"
  allow="microphone; camera; fullscreen; display-capture;"
  width="100%"
  height="100%"
  style="border: none; min-height: 600px;"
></iframe>

步骤3：处理与父页面通信

若需在父页面获取会议状态（例如会议结束），可利用 postMessage 机制向父页面发送消息。
// 在 TUIRoomKit 接入项目中发送事件
import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
const { subscribeEvent } = useRoomState();

subscribeEvent(RoomEvent.onRoomEnded, () => {
  window.parent.postMessage({ event: 'onRoomEnded', data: {} }, '*');
});

// 在您的父页面中接收事件
window.addEventListener('message', (event) => {
  if (event.data.event === 'onRoomEnded') {
    console.log('房间已解散');
  }
});

步骤4：部署验证

完成上述步骤后，您可以通过以下方式验证集成是否成功：
检查项目
验证标准
页面加载
iframe 区域正常渲染出 TUIRoomKit 会议界面。
音视频权限
尝试在会议界面内点击“取消静音”或“打开视频”，确认状态图标切换正常。
屏幕分享
点击屏幕分享，确认能够弹出系统级分享窗口。

常见问题

为什么部署后无法开启摄像头和麦克风？

检查协议：确保父页面和 iframe 地址都是 https://。
检查 allow 属性：确保 <iframe> 标签包含 allow="microphone; camera; fullscreen; display-capture;"。

TUIRoomKit 是否支持设置内网代理？

支持。请参考如下指引设置内网代理参数。更多内网代理信息请参考 应对防火墙受限。
// 请在进房前设置内网代理参数
import TUIRoomEngine from '@tencentcloud/tuiroom-engine-js';
import { useRoomEngine } from 'tuikit-atomicx-vue3/room';
const { roomEngine } = useRoomEngine();

TUIRoomEngine.once('ready', () => {
  const trtcCloud = roomEngine.instance?.getTRTCCloud();
  trtcCloud.callExperimentalAPI(JSON.stringify({
    api: 'setNetworkProxy',
    params: {
      websocketProxy: "wss://proxy.example.com/ws/",
      turnServer: [{
        url: '14.3.3.3:3478',
        username: 'turn',
        credential: 'turn',
      }],
      iceTransportPolicy: 'relay',
    },
  }));
});

联系我们

如果您在接入或使用过程有任何疑问或者建议，欢迎联系 info_rtc@tencent.com 提交反馈
上一篇: iOS下一篇: WebView

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈