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

集成 SDK

更新时间：2024-07-12 16:58

1 准备环境

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

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

2 集成 SDK

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

方式 1：使用 npm 方式集成（推荐）

下载并安装 Node.js 和 npm。
新建项目，创建一个文件夹作为基础音视频通话的项目文件夹，结构类似如下：
```
├── index.html
├── index.js
```

将以下代码拷贝到 “index.html” 文件中。

<html>

<head>
    <meta charset="UTF-8">
    <title>Zego Express Video Call</title>
    <style type="text/css">
        * {
            font-family: sans-serif;
        }

        h1,
        h4 {
            text-align: center;
        }

        #local-video, #remote-video {
            width: 400px;
            height: 300px;
            border: 1px solid #dfdfdf;
        }

        #local-video {
            position: relative;
            margin: 0 auto;
            display: block;
        }

        #remote-video {
            display: flex;
            margin: auto;
            position: relative !important;
        }
    </style>
</head>

<body>
    <h1>
        Zego RTC Video Call
    </h1>
    <h4>Local video</h4>
    <div id="local-video"></div>
    <h4>Remote video</h4>
    <div id="remote-video"></div>
    <script src="index.js"></script>
</body>

</html>

通过 npm 安装 SDK。

在终端中，cd 到 ”index.js“ 文件所在的文件夹，执行 npm i zego-express-engine-webrtc 命令安装依赖。
- npm 下载包支持 typescript 语言（推荐）。
- 如果在 macOS 或 Linux 系统中执行 npm 命令失败，提示 “permission denied”，请在 npm 命令前加上 sudo 重新执行即可。
在 “index.js” 文件中引入 SDK。
- 在 3.4.0 版本之前，开发者集成 ZEGO Web SDK 时，默认同时集成了混音、混流等功能。如果开发者的业务仅需其中的某个功能模块，无法单独集成。
- 从 3.4.0 版本开始：
  - 开发者依然可以通过主路径引入 SDK，同时集成混音、混流等功能。
  - 同时，开发者也可以按照业务需要，从 混音、混流、CDN、范围语音、美颜 功能模块中进行选择，并通过 npm 方式单独集成。（仅支持通过 npm 方式单独集成某个功能模块，其余方式不支持。）
    - 各功能模块的包大小约为：混音（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'

或

var ZegoExpressEngine = require('zego-express-engine-webrtc').ZegoExpressEngine

请注意，在创建 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 接口如下：

混音功能：
- startMixingAudio：开始混音。
- stopMixingAudio：停止混音。
- setMixingAudioVolume：设置混音音量。
- enableLiveAudioEffect：开启或关闭音效增强的功能。
- setAudioChangerParam：对传入的歌曲进行变调处理。
混流功能：
- startMixerTask：开始混流任务。
- stopMixerTask：停止服务端混流。
- setMixerTaskConfig：混流高级配置。
CDN 功能：
- addPublishCdnUrl：通知即构服务器将流转推到 CDN。
- removePublishCdnUrl：通知即构服务器停止将流转推到 CDN。
范围语音：
- 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：添加或更新自定义发声源位置信息。
美颜功能：
- setEffectsBeauty：开启或关闭美颜。
- setLowlightEnhancement：设置低照度增强。

在本地 Web 服务器上运行和测试项目。

本地服务器（localhost 或 127.0.0.1）运行 Web 应用仅作为测试，生产环境必须使用 HTTPS 协议。
1. 在命令行中执行 npm i live-server -g 命令，安装 live-server。
2. 进入项目所在的根目录。
3. 执行 live-server . 命令运行该项目，浏览器会自动打开 “index.html” 页面。

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

从官网下载 SDK，手动集成

下载最新版本的 SDK 并解压。
解压 SDK 压缩包，我们可以在 “dist_js/” 下找到 “ZegoExpressWebRTC-x.x.x.js” 文件。
推荐下载 VSCode，在 VSCode 中找到项目文件目录并打开。
安装 VSCode 扩展插件 Live Server。
新建 “index.html” 文件，并放置于和 “ZegoExpressWebRTC-x.x.x.js” 相同的目录下。

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

“index.html” 代码示例如下：

<html>

<head>
    <meta charset="UTF-8">
    <title>Zego Express Video Call</title>
    <style type="text/css">
        * {
            font-family: sans-serif;
        }

        h1,
        h4 {
            text-align: center;
        }

        #local-video, #remote-video {
            width: 400px;
            height: 300px;
            border: 1px solid #dfdfdf;
        }

        #local-video {
            position: relative;
            margin: 0 auto;
            display: block;
        }

        #remote-video {
            display: flex;
            margin: auto;
            position: relative !important;
        }
    </style>

    <script src="./ZegoExpressWebRTC-x.x.x.js"></script>
</head>

<body>
    <h1>
        Zego RTC Video Call
    </h1>
    <h4>Local video</h4>
    <div id="local-video"></div>
    <h4>Remote video</h4>
    <div id="remote-video"></div>
    <script> // 教程中的 js 代码可粘贴至此标签内

    // const zg = new ZegoExpressEngine(appID, server);
    </script>
</body>

</html>

在 “index.html” 文件的编辑面板，单击鼠标右键，弹出菜单，选择 “Open with Live Server”，即可看到基本界面，此时表示 SDK 已集成。