本章节主要指导您完成
TUILiveKit UI 组件库接入的环境配置。集成方案说明:
本文档提供的是 UI 组件库接入方案,包含视频直播、语聊房的完整 UI 界面与全套业务逻辑。如果您有极高的 UI 定制需求,需要采用 无 UI(Core SDK) 集成方式,请直接参考 Core SDK 快速开始。
功能预览
TUILiveKit UI 组件为您提供的是功能闭环、交互丰富的直播全链路逻辑,集成后可快速实现一套交互完整、业务丰富的直播系统。
视频直播
Web
主播开播前预览 | 主播开播 |
![]() | ![]() |
观众观看 | 主播和观众连麦 |
![]() | ![]() |
H5
主播开播前预览 | 主播开播 | 观众观看 | 主播和观众连麦 |
![]() | ![]() | ![]() | ![]() |
前提条件
开通服务
SDKAppID:应用标识,腾讯云基于
SDKAppID 完成计费统计。SDKSecretKey:应用密钥,仅用于本地调试时生成 UserSig,不可写入生产代码。
环境准备
Node.js:≥ 18.19.1 (推荐使用官方 LTS 版本)。
浏览器:推荐使用最新版 Chrome,或其他支持 WebRTC API 的浏览器。
媒体设备:建议配备摄像头、麦克风和扬声器。缺少相应设备时仍可入会,但对应音视频能力不可用。
代码集成
步骤1:安装依赖
# 在已有 React 项目根目录执行;# 若需新建项目,可先运行 npm create vite@latest livekit-demo-react -- --template react-tsnpm install @tencentcloud/livekit-web-react tuikit-atomicx-react @tencentcloud/uikit-base-component-react --save
# 在已有 React 项目根目录执行;# 若需新建项目,可先运行 npm create vite@latest livekit-demo-react -- --template react-tspnpm install @tencentcloud/livekit-web-react tuikit-atomicx-react @tencentcloud/uikit-base-component-react --save
# 在已有 React 项目根目录执行;# 若需新建项目,可先运行 npm create vite@latest livekit-demo-react -- --template react-tsyarn add @tencentcloud/livekit-web-react tuikit-atomicx-react @tencentcloud/uikit-base-component-react --save
步骤2:完成登录
完成登录是使用 TUILiveKit 的基础,只有在登录成功后才能正常使用 TUILiveKit 的各项功能,故请您耐心检查相关参数是否配置正确:
说明:
在示例代码中,直接进行了登录接口的调用。但在实际项目场景下,强烈推荐您在完成自己的用户身份验证等相关登录操作后,再调用 TUILiveKit 的登录服务。这样可以避免因过早调用登录服务,导致业务逻辑混乱或数据不一致的问题,同时也能更好地适配您项目中现有的用户管理和权限控制体系。
// 以 App.tsx 为例import { useEffect, useState } from 'react';import { useLoginState, LoginStatus } from 'tuikit-atomicx-react';const css = '*,*::before,*::after{box-sizing:border-box}.guide{position:fixed;inset:0;overflow-y:auto;text-align:left;min-height:100vh;padding:64px 32px 40px;background:radial-gradient(1100px 560px at 12% -12%,rgba(99,102,241,.3),transparent 62%),radial-gradient(900px 480px at 100% 0%,rgba(45,212,191,.18),transparent 58%),#0b1020;color:#e8edff;font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif}.guide__pending{display:flex;align-items:center;gap:12px;margin-top:44px;padding:22px;border-radius:16px;background:rgba(255,255,255,.04);border:1px solid rgba(255,255,255,.08);color:#b7c2de}.guide__spinner{flex:none;width:18px;height:18px;border:2px solid rgba(94,234,212,.25);border-top-color:#5eead4;border-radius:50%;animation:guide-spin .8s linear infinite}@keyframes guide-spin{to{transform:rotate(360deg)}}.guide__error{margin-top:36px;padding:26px;border-radius:18px;background:rgba(248,113,113,.06);border:1px solid rgba(248,113,113,.24)}.guide__error-msg{margin:0 0 16px;color:#fca5a5;font-size:14px;word-break:break-word}.guide__checks{display:grid;gap:10px;margin:0;padding:0;list-style:none}.guide__checks li{position:relative;padding-left:22px;color:#b7c2de;font-size:14px}.guide__checks li::before{content:"•";position:absolute;left:4px;color:#f87171}.guide__inner{position:relative;max-width:1080px;margin:0 auto}.guide__brand{display:inline-block;font-size:13px;font-weight:700;letter-spacing:.16em;text-transform:uppercase;color:#8b9ac9}.guide__title{margin:26px 0 12px;font-size:clamp(30px,4vw,46px);line-height:1.2;font-weight:700;letter-spacing:-.02em;color:#f7f9ff}.guide__subtitle{margin:0;color:#9aa7c7;font-size:16px}.guide__steps{display:flex;align-items:center;gap:12px;flex-wrap:wrap;list-style:none;padding:0;margin:36px 0 26px}.guide__steps li{display:flex;align-items:center;gap:10px;padding:9px 15px;border-radius:10px;background:rgba(255,255,255,.04);border:1px solid rgba(255,255,255,.07);color:#b7c2de;font-size:14px}.guide__steps b{color:#5eead4;font:700 12px/1 ui-monospace,Consolas,monospace}.guide__steps li:not(:last-child)::after{content:"→";margin-left:2px;color:#5f6b8f}.guide__grid{display:grid;grid-template-columns:repeat(3,1fr);gap:20px}.card{display:flex;flex-direction:column;padding:28px;border-radius:20px;border:1px solid rgba(255,255,255,.1);background:linear-gradient(160deg,rgba(255,255,255,.07),rgba(255,255,255,.025));box-shadow:0 18px 40px rgba(0,0,0,.28);color:inherit;text-decoration:none;transition:transform .25s ease,border-color .25s ease,box-shadow .25s ease}.card:hover{transform:translateY(-6px);border-color:rgba(94,234,212,.55);box-shadow:0 24px 50px rgba(0,0,0,.4),0 0 0 1px rgba(94,234,212,.12)}.card:focus-visible{outline:2px solid #5eead4;outline-offset:3px}.card__top{display:flex;align-items:center;justify-content:space-between}.card__num{font:700 13px/1 ui-monospace,Consolas,monospace;letter-spacing:.12em;color:#5eead4}.card__tag{padding:6px 10px;border-radius:999px;background:rgba(129,140,248,.14);border:1px solid rgba(129,140,248,.25);color:#a5b4fc;font-size:12px;font-weight:600}.card__title{margin:22px 0 10px;font-size:22px;font-weight:600;letter-spacing:.02em;color:#f5f7ff}.card__desc{margin:0 0 24px;min-height:48px;color:#9aa7c7;font-size:14.5px}.card__cta{display:inline-flex;align-items:center;gap:8px;margin-top:auto;color:#5eead4;font-size:14px;font-weight:600}.card__arrow{display:inline-block;transition:transform .25s ease}.card:hover .card__arrow{transform:translateX(5px)}.guide__foot{margin-top:32px;color:#6f7ea6;font-size:13px;text-align:center}.uikit-uikit-modal-mask,.uikit-modal-mask{display:none!important}@media(max-width:900px){.guide{padding:40px 20px}.guide__grid{grid-template-columns:1fr}.guide__steps{gap:10px}.guide__steps li:not(:last-child)::after{display:none}.guide__title{font-size:30px}.card__desc{min-height:0}}';function App() {const { login, loginStatus } = useLoginState();const [loginError, setLoginError] = useState('');useEffect(() => {login({sdkAppId: 0, // SDKAppID - 开通服务时获取的 SDKAppIDuserId: '', // UserID - 用户 IDuserSig: '', // userSig - 用户签名,详细获取方式请参照下文参数说明}).catch((error: unknown) => {setLoginError(error instanceof Error ? error.message : String(error));console.error('登录失败:', error);});}, []);return (<><style>{css}</style><main className="guide"><div className="guide__inner"><header><span className="guide__brand">TUILiveKit · Web (React)</span><h1 className="guide__title">{loginError ? '登录失败,请先检查配置' : loginStatus === LoginStatus.LOGINED ? '登录成功,接下来做什么?' : '正在初始化登录'}</h1><p className="guide__subtitle">{loginError ? '请确认下列参数后刷新页面重新登录' : loginStatus === LoginStatus.LOGINED ? '按业务场景选择接入方式,点击卡片查看对应的接入文档' : '登录完成后将展示可选的接入场景'}</p></header>{loginError ? (<section className="guide__error"><p className="guide__error-msg">{loginError}</p><ul className="guide__checks"><li>确认 SDKAppID 与当前应用一致</li><li>确认 UserID 与 UserSig 中的用户匹配</li><li>确认 UserSig 未过期,且由该 SDKAppID 对应的密钥生成</li></ul></section>) : loginStatus === LoginStatus.LOGINED ? (<><ol className="guide__steps"><li><b>01</b>选择场景</li><li><b>02</b>参照文档接入组件</li><li><b>03</b>运行并验证效果</li></ol><section className="guide__grid"><a className="card" href="https://cloud.tencent.com/document/product/647/140796" target="_blank" rel="noopener noreferrer"><div className="card__top"><span className="card__num">01</span><span className="card__tag">LivePusher</span></div><h2 className="card__title">主播开播</h2><p className="card__desc">创建直播间并推流,配置摄像头、美颜、连麦与观众互动</p><span className="card__cta">查看接入文档 <span className="card__arrow">→</span></span></a><a className="card" href="https://cloud.tencent.com/document/product/647/123471" target="_blank" rel="noopener noreferrer"><div className="card__top"><span className="card__num">02</span><span className="card__tag">LivePlayer</span></div><h2 className="card__title">观众观看</h2><p className="card__desc">通过 liveId 进入直播间,观看视频、发弹幕、送礼与连麦</p><span className="card__cta">查看接入文档 <span className="card__arrow">→</span></span></a><a className="card" href="https://cloud.tencent.com/document/product/647/127824" target="_blank" rel="noopener noreferrer"><div className="card__top"><span className="card__num">03</span><span className="card__tag">LiveList</span></div><h2 className="card__title">直播列表</h2><p className="card__desc">展示进行中的直播,点击进入观看或发起开播</p><span className="card__cta">查看接入文档 <span className="card__arrow">→</span></span></a></section></>) : (<div className="guide__pending"><span className="guide__spinner"></span>正在登录,请稍候…</div>)}<footer className="guide__foot">文档将在新窗口打开 · 接入前请确认 SDKAppID / UserID / UserSig 已正确配置</footer></div></main></>);}export default App;
注意:
安全提醒: 出于安全考虑,强烈建议将
userSig 的计算逻辑放在您的服务端进行,避免将 SecretKey 暴露在前端代码中。您可以使用 控制台辅助工具 生成临时 userSig 进行调试。 更多信息参见 如何计算及使用 UserSig。GitHub 中的示例代码使用了 genTestUserSig 函数在本地计算 userSig 是为了更快地让您跑通当前的接入流程,但该方案会将您的 SecretKey 暴露在代码当中,这并不利于您后续升级和保护您的 SecretKey。参数说明如下表所示:参数 | 类型 | 说明 |
SDKAppID | int | |
UserID | String | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1、123 等简单 ID。 |
userSig | String | 用于腾讯云鉴权的票据。请注意: 开发环境:您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者 通过 UserSig 辅助工具 生成临时的 UserSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 UserSig 的方式。详细信息请参考 服务端生成 UserSig。 |
下一步
恭喜您,现在您已经成功集成了直播组件并完成了登录。接下来,您可以根据您的业务场景实现主播开播、观众观看、直播列表等功能。
常见问题
每次进房都需要调用登录吗?
不需要。通常您只需要调用一次
useLoginState() 返回的 login 函数,我们强烈推荐您将 useLoginState() 返回的 login() 和 logout() 响应式函数, 与您自己的登录业务关联。为什么接入 TUILiveKit 后,必须使用 HTTPS 协议部署?
如果您需要部署项目打包的 dist 文件,生产环境下必须使用 HTTPS 域名。TUILiveKit 底层依赖 WebRTC 功能,也可能访问用户的摄像头、麦克风、扬声器等物理设备,浏览器厂商为了保护用户数据安全和隐私安全,要求必须使用 HTTPS 协议。
注意:
URL 域名协议限制
由于浏览器安全策略的限制,使用 WebRTC 能力对页面的访问协议有严格的要求,请参照以下表格进行开发和部署应用。
应用场景 | 协议 | 接收(播放) | 发送(上麦) | 屏幕分享 | 备注 |
生产环境 | HTTPS 协议 | 支持 | 支持 | 支持 | 推荐 |
生产环境 | HTTP 协议 | 支持 | 不支持 | 不支持 | - |
本地开发环境 | http://localhost | 支持 | 支持 | 支持 | 推荐 |
本地开发环境 | http://127.0.0.1 | 支持 | 支持 | 支持 | - |
本地开发环境 | http://[本机 IP] | 支持 | 不支持 | 不支持 | - |
本地开发环境 | file:/// | 支持 | 支持 | 支持 | - |







