文档中心
实时音视频
快速开始
集成 SDK

集成 SDK

更新时间：2025-01-09 14:17

1 准备环境

在开始集成 ZEGO Express SDK 前，请确保开发环境满足以下要求：

Windows 或 macOS 开发电脑已经连接到 Internet。
满足 Express Web SDK 兼容性的浏览器（具体请参考浏览器兼容性和已知问题），推荐使用最新版本的 Google Chrome 浏览器。

2 集成 SDK

开发者可通过以下任意一种方式集成 SDK。

方式 1：使用包管理器自动集成（推荐）

下载并安装Node.js 。

新建项目

HTML Vue React

新建文件夹创建index.html , index.js

├── index.html
├── index.js

在命令行中执行

npm create vue@latest

选择默认选项即可

> npx
> create-vue
Vue.js - The Progressive JavaScript Framework
✔ 请输入项目名称： … zego_web_vue_demo
✔ 是否使用 TypeScript 语法？ … [否] / 是
✔ 是否启用 JSX 支持？ … [否] / 是
✔ 是否引入 Vue Router 进行单页面应用开发？ … [否] / 是
✔ 是否引入 Pinia 用于状态管理？ … [否] / 是
✔ 是否引入 Vitest 用于单元测试？ … [否] / 是
✔ 是否要引入一款端到端（End to End）测试工具？ › 不需要
✔ 是否引入 ESLint 用于代码质量检测？ › 否
正在初始化项目 /xxx/zego_web_vue_demo...
项目初始化完成，可执行以下命令：
 cd zego_web_vue_demo
 npm install
 npm run dev

在命令行中执行

npm create vite@latest zego_web_react_demo --  --template react

> npx
> create-vite zego_web_react_demo --template react
Scaffolding project in /xxx/zego_web_react_demo...
Done. Now run:
 cd zego_web_react_demo
 npm install
 npm run dev

通过包管理器安装 SDK。

在项目的根目录下执行以下命令安装依赖。
npm yarn pnpm
```
npm install zego-express-engine-webrtc
```
```
yarn add zego-express-engine-webrtc
```
```
pnpm add zego-express-engine-webrtc
```
- 安装的依赖包支持 typescript 语言。
- 如果在 macOS 或 Linux 系统中执行安装命令失败，提示 “permission denied”，请在SDK安装命令前加上 sudo 重新执行即可。

在项目中文件中引入SDK，示例代码如下：

HTML Vue React

index.html:

<!DOCTYPE html>
<html lang="en">
<head>
 <meta charset="UTF-8">
 <title>Zego Web Demo</title>
</head>
<body>
 <h1>Zego Web Demo</h1>
 <script src="index.js" type="module"></script>
</body>
</html>

index.js:

import { ZegoExpressEngine } from "zego-express-engine-webrtc"

app.vue:

<script setup>
import { ZegoExpressEngine } from 'zego-express-engine-webrtc'
</script>
<template>
 <div>
   <h1>Zego Web Vue Demo</h1>
 </div>
</template>

app.jsx:

import { ZegoExpressEngine } from "zego-express-engine-webrtc"
function App() {
 return (
   <>
     <h1>Zego Web React Demo</h1>
   </>
 )
}
export default App

完整引入和按需引入 SDK。
- 在 3.4.0 版本之前：
  开发者集成 ZEGO Web SDK 时，默认同时集成了混音、混流等功能。如果开发者的业务仅需其中的某个功能模块，无法单独集成。
- 从 3.4.0 版本开始：
  - 开发者依然可以通过主路径引入 SDK，同时集成混音、混流等功能。
  - 同时，开发者也可以按照业务需要，从混音、混流、CDN、范围语音、美颜 功能模块中进行选择，并通包管理器安装的方式单独集成。（仅支持通过包管理器安装的方式单独集成某个功能模块，其余方式不支持。）
    - 各功能模块的包大小约为：混音（56 KB）、混流（60 KB）、CDN（29 KB）、范围语音（97 KB）、美颜（69 KB）。
    - 对于未引入的功能，在构建过程中会自动移除，减少 SDK 包的体积。

完整集成 SDK 单独集成功能模块

如果您需要完整集成 ZEGO Web SDK，请参考如下代码，在 “index.js” 文件中引入完整的 SDK。

import {ZegoExpressEngine} from 'zego-express-engine-webrtc'

请注意，在创建 ZegoExpressEngine 实例时，开发者必须通过 import { ZegoExpressEngine } from "zego-express-engine-webrtc/esm" 引入某个功能模块，才能实现按需集成的效果。请根据您业务需要，选择需要使用的功能，通过 zego-express-engine-webrtc/esm 路径引入。

import { ZegoExpressEngine } from "zego-express-engine-webrtc/esm"
// 引入 CDN 模块
import { StreamCDN } from "zego-express-engine-webrtc/esm/stream-cdn"
// 引入 混音 模块
import { AudioMix } from "zego-express-engine-webrtc/esm/audio-mix"
// 引入 混流 模块
import { MixStream }  from "zego-express-engine-webrtc/esm/mix-stream"
// 引入 范围语音 模块
import { RangeAudio } from 'zego-express-engine-webrtc/esm/range-audio';
// 引入 美颜 模块
import { BeautyEffect } from 'zego-express-engine-webrtc/esm/beauty-effect';
ZegoExpressEngine.use(StreamCDN);
ZegoExpressEngine.use(AudioMix);
ZegoExpressEngine.use(MixStream);
ZegoExpressEngine.use(RangeAudio);
ZegoExpressEngine.use(BeautyEffect);

如果您未集成某个功能模块、但调用了模块相关的 API 接口，SDK 将返回错误码 1101003 及相关提示。功能模块及对应的 API 接口如下：

CDN 功能(StreamCDN)：
- addPublishCdnUrl：通知即构服务器将流转推到 CDN。
- removePublishCdnUrl：通知即构服务器停止将流转推到 CDN。
混音功能(AudioMix)：
- startMixingAudio：开始混音。
- stopMixingAudio：停止混音。
- setMixingAudioVolume：设置混音音量。
- enableLiveAudioEffect：开启或关闭音效增强的功能。
- setAudioChangerParam：对传入的歌曲进行变调处理。
混流功能(MixStream)：
- startMixerTask：开始混流任务。
- stopMixerTask：停止服务端混流。
- setMixerTaskConfig：混流高级配置。
范围语音(RangeAudio)：
- createRangeAudioInstance：创建范围语音实例对象。
- setVoiceChangerParam：范围语音对媒体流进行自定义参数设置变声处理。
- setVoiceChangerPreset：范围语音对媒体流进行变声处理。
- enableAudioSourceUpdateChecker：是否检查范围内用户的变更。
- on：注册回调事件。
- off：注销回调事件。
- setAudioReceiveRange：设置音频接收距离的最大范围。
- updateSelfPosition：更新听者的位置和朝向。
- updateAudioSource：添加或更新音源位置信息。
- enableSpatializer：开关 3D 音效。
- enableMicrophone：开关麦克风。
- selectMicrophone：指定麦克风设备。
- selectSpeaker：指定扬声器设备。
- enableSpeaker：开关扬声器。
- setRangeAudioCustomMode：设置范围语音的高阶自定义模式。
- setRangeAudioMode：设置范围语音模式。
- setTeamID：设置队伍 ID。
- setPositionUpdateFrequency：设置 SDK 内部实时更新位置的频率。
- setRangeAudioVolume：设置范围语音本地播放音量。
- enableAiDenoise：范围语音开启或关闭 AI 降噪。
- isAudioContextRunning：判断 AudioContext 对象是否已启用。
- resumeAudioContext：重新启用内部的 AudioContext 对象。
- setStreamVocalRange：设置拉流音频发送范围。
- updateStreamPosition：更新拉流的位置。
- setCustomSourceVocalRange：设置自定义发声源发送范围。
- updateCustomSourcePosition：添加或更新自定义发声源位置信息。
美颜功能(BeautyEffect)：
- setEffectsBeauty：开启或关闭美颜。
- setLowlightEnhancement：设置低照度增强。

方式 2：从官网下载 SDK，手动集成

从官网下载 SDK，手动集成

下载最新版本的 SDK 并解压到项目文件夹，我们可以在 “dist_js/” 下找到 “ZegoExpressWebRTC-x.x.x.js” 文件。
在 VSCode中打开项目文件夹并新建 “index.html” 文件。

在 “index.html” 文件中编写界面代码，并在文件的 head 标签内使用 script 标签引入 “ZegoExpressWebRTC-x.x.x.js”。其中，“x.x.x” 为 SDK 的版本号，请参考第 1 步压缩包解压后的文件名修改。

index.html 代码示例如下：

<html>
 <head>
   <meta charset="UTF-8">
   <title>Zego RTC Web Demo</title>
   <script src="./dist_js/ZegoExpressWebRTC-x.x.x.js"></script>
 </head>
 <body>
   <h1>
     Zego RTC Web Demo
   </h1>
 </body>
 <script>
   (async () => {
     // 此处添加后续的代码...
   })();
 </script>
</html>