Cocos Creator实时音视频SDK集成

本文分享即构科技 Cocos Creator 实时音视频SDK集成，支持在 Android / iOS / macOS / Windows 原生平台快速实现视频通话、语音通话和互动直播等功能。

准备环境

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

• Cocos Creator v3.6.0 或以上版本（建议通过 Cocos Dashboard 下载最新的版本）。

请勿使用 Cocos Creator v3.6.2 版本。

根据需要运行的平台，确保对应的开发环境和设备。

• Android：Android 5.0 或以上版本且支持音视频的 Android 设备或模拟器（推荐使用真机），如果为真机，请开启允许调试选项。
• iOS：Xcode 14.0 或以上版本，iOS 11.0 或以上版本且支持音视频的 iOS 设备或模拟器（推荐使用真机）。
• macOS：macOS 10.13 或以上版本且支持音视频的 macOS 设备。
• Windows：Windows 7 或以上版本且支持音视频的 Windows 设备；并安装 Visual Studio 2019 或以上版本。

确保运行设备已经连接到 Internet。

集成 SDK

新建项目（可选）

打开 Cocos Dashboard，新建项目，根据实际情况选择一个模版，填写项目名称并指定项目保存的位置并创建项目。

导入 SDK

目前，Cocos Creator 支持 Android、iOS、macOS、Windows 平台。

1. 请参考 下载 SDK 文档，下载最新版本的 SDK。
2. 打开 “Extensions > Extensions Manager”，在项目选项卡下，单击加号，添加扩展，选择上一步下载下来的 SDK 压缩包。

3. 添加完成后，确认扩展管理器中有 zego_express_cocos_creator_sdk 并处于启用状态，然后查看资源管理器，在 assets 目录下，应当存在一个 “zego_express_engine” 目录，里面为 SDK 的 TypeScript 层源码。 项目根目录下的 “assets/zego_express_engine” 文件夹是扩展管理器启用 SDK 扩展时自动拷贝的，当停用 SDK 时该文件夹会被自动删除。因此建议将 “assets/zego_express_engine” 目录添加到 “.gitignore” 中，不必提交到 git。

#//////////////////////////
# ZEGO RTC
#//////////////////////////
/assets/zego_express_engine*
/extensions/zego_express_cocos_creator_sdk*
/native/plugins/zego_express_engine*

先根据 Cocos Creator 安装配置原生开发环境 文档配置好开发环境，然后再根据 发布到原生平台 文档和实际情况，构建出原生平台工程。

若构建失败，请打开构建日志文件查看错误信息并根据错误提示修正问题。若错误信息与 ZEGO SDK 有关并难以自行解决，请联系 ZEGO 技术支持。

将 “native/engine” 原生工程配置文件纳入 git 跟踪。

建议把工程的 “native/engine” 目录纳入 git 跟踪，从而能持久化跟踪原生工程的配置，在多人协作中非常有帮助。打开工程根目录的 “.gitignore” 文件，可以看到默认模版中 “native” 目录被忽略了，可以改为：

native/*
!native/engine/

从而让 git 收集 “native/engine” 目录下的文件。

部分平台需要做一些额外处理。

• Android
  1. 使用 Android Studio 打开原生工程 “MyAwesomeProject/build/android/proj”。 若使用 macOS 开发，请勿直接打开 Android Studio，而是需要打开终端，并输入 open -a "Android Studio" 来启动 Android Studio 以解决潜在问题，请参考 Issue 以获得更多信息。
  2. 打开 “native/engine/android/app/build.gradle” 文件，在 “android.sourceSets.main.jniLibs” 节点添加 SDK Native 插件库所在目录。 srcDir "../../../plugins/zego_express_engine/android/libs"
  3. 在 dependencies 节点导入 SDK Native 插件库的所有 jar 包。 implementation fileTree(dir: "../../../plugins/zego_express_engine/android/libs", include: ['*.jar'])
  4. 在 “native/engine/android/app/proguard-rules.pro” 文件中，为 SDK 添加 -keep 类的配置，防止混淆 SDK 公共类名称：-keep class **.zego.**{*;}。
• iOS
  • SDK 插件默认使用 iOS 真机架构，若要构建 iOS 模拟器，请打开工程的 “native/engine/ios/CMakeLists.txt” 文件，在 cc_ios_before_target 上面添加如下配置：

set(IOS_VARIANT "SIMULATOR") # DEVICE / SIMULATOR / MACCATALYST

• 在“构建发布”面板中，重新生成 iOS 工程。当需要构建 iOS 真机架构时，将上面的值改为 “DEVICE” 即可，或者删除该行配置。
  1. （可选）对于 Cocos Creator iOS 原生工程，推荐直接使用导出的 Xcode 原生工程进行编译、运行、调试，不建议使用“构建发布”面板中的“生成”与“运行”按钮进行编译与运行 iOS 应用。
  2. （可选）若一定要使用“构建发布”面板中的按钮来直接生成与运行，注意“构建发布配置”中的“目标平台”仅能勾选其中一种，不能同时勾选真机与模拟器，否则必定生成失败。并且当勾选 “iOS Simulator 模拟器”时，需要按照上述指引修改 iOS 原生工程的 CMake 配置。

设置权限

根据实际需要，设置 SDK 所需的摄像头和麦克风权限。

Android

根据实际应用需要，设置应用所需权限。

打开 “native/engine/android/app/AndroidManifest.xml” 文件，添加权限声明。

<!-- 必要权限 -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>

<!-- 非必要权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

由于 Android 6.0+ 在一些比较重要的权限上要求必须申请动态权限，不能只通过 “AndroidMainfest.xml” 文件申请静态权限，因此还需要参考执行如下代码，其中 requestPermissions 是 Activity 的方法。

以下简单示例在 App 启动时申请权限，也可以根据实际情况在合适的时机申请（在调用 SDK 的 createEngine 前申请即可）。

// native/engine/android/app/src/com/cocos/game/AppActivity.java

import android.content.pm.PackageManager;
import android.os.Build;
import androidx.core.content.ContextCompat;

// ......

public class AppActivity extends CocosActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // DO OTHER INITIALIZATION BELOW
        SDKWrapper.shared().init(this);

        String[] permissionNeeded = {
                "android.permission.CAMERA",
                "android.permission.RECORD_AUDIO"};

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            if (ContextCompat.checkSelfPermission(this, "android.permission.CAMERA") != PackageManager.PERMISSION_GRANTED ||
                    ContextCompat.checkSelfPermission(this, "android.permission.RECORD_AUDIO") != PackageManager.PERMISSION_GRANTED) {
                requestPermissions(permissionNeeded, 101);
            }
        }

    }

// ......

}

iOS

使用 Xcode 打开原生工程 “MyAwesomeProject/build/ios/proj/MyAwesomeProject.xcodeproj”。

1. 在 Xcode 中，选择 “TARGETS > Info > Custom iOS Target Properties” 菜单。
2. 单击 “+” 添加按钮，根据实际应用需要，添加摄像头和麦克风权限。
   • Privacy - Camera Usage Description
   • Privacy - Microphone Usage Description
3. （可选）如果没有在 Cocos Creator 构建面板中勾选 “跳过 Xcode 工程更新”，下次构建 iOS 时，上面添加的内容会被覆盖掉。建议修改 “native/engine/ios/Info.plist” 文件，并确保 “native/engine/ios” 目录有被 git 跟踪，从而添加的权限声明能持久化。

<key>NSCameraUsageDescription</key>
<string>We need camera</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need microphone</string>

macOS

按照实际需要添加摄像头和麦克风权限声明，详情请参考 iOS。

建议修改 “native/engine/mac/Info.plist” 文件，并确保 “native/engine/mac” 目录有被 git 跟踪，从而添加的权限声明能持久化。

<key>NSCameraUsageDescription</key>
<string>We need camera</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need microphone</string>

注意：集成过程有问题可访问 https://doc-zh.zego.im/article/16919，或者留言给我们。