Integrating SDK

2024-05-06

Prepare Environment

Before starting the integration of ZEGO Express SDK, please ensure the development environment meets the following requirements:

Cocos Creator v3.6.0 or above (it is recommended to download the latest version through Cocos Dashboard).

Note

Do not use Cocos Creator v3.6.2 version. For details, please refer to FAQ 6 below.

Ensure the corresponding development environment and devices for the platform to be run.
- Android: Android 5.0 or above with Android device or emulator that supports audio and video (using real device is recommended). If using a real device, please enable the Allow Debugging option.
- iOS: Xcode 15.0 or above, iOS 12.0 or above with iOS device or emulator that supports audio and video (using real device is recommended).
- macOS: macOS 10.13 or above with macOS device that supports audio and video.
- Windows: Windows 7 or above with Windows device that supports audio and video; and install Visual Studio 2019 or above.
- Browser that meets Express Web SDK compatibility (for details, please refer to Browser Compatibility and Known Issues), it is recommended to use the latest version of Google Chrome browser.
Ensure the running device is connected to the Internet.

Integrating SDK

Create New Project (Optional)

This step takes creating a new project as an example. If integrating into an existing project, this step can be ignored.

Open Cocos Dashboard, create a new project, select a template according to the actual situation, fill in the project name, specify the location to save the project, and create the project.

Import SDK

Currently, Cocos Creator supports Android, iOS, macOS, and Windows platforms.

Please refer to the Download SDK documentation to download the latest version of the SDK.
Open "Extensions > Extensions Manager", click the plus sign under the Project tab to add extension, and select the SDK package downloaded in the previous step.
After adding, confirm that "zego_express_cocos_creator_sdk" exists in the extension manager and is enabled, then check the Assets Manager. Under the assets directory, there should be a "zego_express_engine" directory, which contains the TypeScript layer source code of the SDK.

The "assets/zego_express_engine" folder in the project root directory is automatically copied when the extension manager enables the SDK extension. When the SDK is disabled, this folder will be automatically deleted. Therefore, it is recommended to add the "assets/zego_express_engine" directory to ".gitignore" and do not need to commit it to git.
```
#//////////////////////////
# ZEGO RTC
#//////////////////////////
/assets/zego_express_engine*
/extensions/zego_express_cocos_creator_sdk*
/native/plugins/zego_express_engine*
```
```
#//////////////////////////
# ZEGO RTC
#//////////////////////////
/assets/zego_express_engine*
/extensions/zego_express_cocos_creator_sdk*
/native/plugins/zego_express_engine*
```
First configure the development environment according to Cocos Creator Install and Configure Native Development Environment documentation, and then build the native platform project according to the Publish to Native Platforms documentation and actual situation.

Note

If the build fails, please open the build log file to view the error information and fix the problem according to the error prompts. If the error information is related to ZEGO SDK and difficult to solve by yourself, please contact ZEGO Technical Support.

Add the "native/engine" native project configuration file to git tracking.

It is recommended to add the "native/engine" directory of the project to git tracking to persistently track the configuration of the native project, which is very helpful in multi-person collaboration. Open the ".gitignore" file in the project root directory. You can see that the "native" directory is ignored in the default template. You can change it to:
```
native/*
!native/engine/
```
```
native/*
!native/engine/
```
So that git can collect files under the "native/engine" directory.
Some platforms require additional processing.
- Android
  1. Use Android Studio to open the native project "MyAwesomeProject/build/android/proj".
  Note
  If using macOS for development, do not open Android Studio directly. Instead, you need to open Terminal and enter open -a "Android Studio" to start Android Studio to resolve potential issues. Please refer to Issue for more information.
  1. Open the "native/engine/android/app/build.gradle" file, and add the directory where the SDK Native plugin library is located at the "android.sourceSets.main.jniLibs" node.
  srcDir "../../../plugins/zego_express_engine/android/libs"
  1. Import all jar packages of the SDK Native plugin library at the dependencies node.
  implementation fileTree(dir: "../../../plugins/zego_express_engine/android/libs", include: ['*.jar'])
  1. In the "native/engine/android/app/proguard-rules.pro" file, add the -keep class configuration for the SDK to prevent obfuscation of SDK public class names: -keep class **.zego.**{*;}.
- iOS
  1. The SDK plugin uses iOS device architecture by default. To build an iOS simulator, please open the "native/engine/ios/CMakeLists.txt" file of the project and add the following configuration above cc_ios_before_target:
```
set(IOS_VARIANT "SIMULATOR") # DEVICE / SIMULATOR / MACCATALYST
```
```
set(IOS_VARIANT "SIMULATOR") # DEVICE / SIMULATOR / MACCATALYST
```
  1. In the "Build & Publish" panel, regenerate the iOS project. When you need to build an iOS device architecture, you can change the above value to "DEVICE" or delete this configuration.
  2. (Optional) For Cocos Creator iOS native projects, it is recommended to directly use the exported Xcode native project for compilation, running, and debugging. It is not recommended to use the "Make" and "Run" buttons in the "Build & Publish" panel to compile and run iOS applications.
  3. (Optional) If you must use the buttons in the "Build & Publish" panel to directly generate and run, note that in the "Build Configuration", the "Target Platform" can only check one of them. You cannot check both device and simulator at the same time, otherwise the build will definitely fail. And when checking "iOS Simulator", you need to modify the CMake configuration of the iOS native project according to the above guidelines.

Set Permissions

Set the camera and microphone permissions required by the SDK according to actual needs.

Android

Set the permissions required by the application according to actual application needs.

Open the "native/engine/android/app/AndroidManifest.xml" file and add permission declarations.

<!-- Required permissions -->
<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"/>

<!-- Optional permissions -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<!-- Required permissions -->
<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"/>

<!-- Optional permissions -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Warning

Since Android 6.0+ requires dynamic permission requests for some important permissions, you cannot only apply for static permissions through the "AndroidMainfest.xml" file. Therefore, you also need to refer to the following code, where requestPermissions is a method of Activity.

The following simple example applies for permissions when the App starts. You can also apply for permissions at the appropriate time according to the actual situation (you can apply before calling the SDK's 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);
            }
        }

    }

// ......

}

// 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);
            }
        }

    }

// ......

}

The specific permission descriptions are as follows:

Necessity	Permission	Permission Description	Reason for Application
Required Permissions	INTERNET	Network access permission.	The basic functions of the SDK need to be used when connected to the Internet.
	ACCESS_WIFI_STATE	Get current WiFi status permission.	The SDK will perform different operations according to the change of network status. For example, when the network is reconnected, the SDK will internally restore the state when the network was disconnected, and users do not need to perform additional operations.
	ACCESS_NETWORK_STATE	Get current network status permission.
	CAMERA	Camera access permission.	This permission is required when previewing and sending video.
	RECORD_AUDIO	Audio recording permission.	This permission is required when sending audio.
	BLUETOOTH	Bluetooth device connection permission.	This permission is required when connecting to Bluetooth devices.
	MODIFY_AUDIO_SETTINGS	Modify audio configuration permission.	This permission is required when modifying audio device configuration.
Optional Permissions	READ_PHONE_STATE	Allow read-only access to phone status, including current call status.	The SDK will start/stop the audio device according to the current call status. For example, if it is detected that the current status is a call, the SDK will automatically stop using the audio device until the call ends.
Optional Permissions	WRITE_EXTERNAL_STORAGE	Built-in SDK write permission.	If you need to use the media player or sound effect player to load media resource files in Android external storage, you need to apply for this permission, otherwise the SDK cannot load resources.

Note

Among them, the optional permission "android.permission.READ_PHONE_STATE" is only used to implement the interrupt event handling of the SDK, so it only needs to be declared in the AndroidMainfest.xml file and does not need to apply dynamically (if the business side has requirements, handle it separately).

iOS

Use Xcode to open the native project "MyAwesomeProject/build/ios/proj/MyAwesomeProject.xcodeproj".

In Xcode, select "TARGETS > Info > Custom iOS Target Properties" menu.
Click the "+" add button to add camera and microphone permissions according to actual application needs.
- Privacy - Camera Usage Description
- Privacy - Microphone Usage Description
(Optional) If you did not check "Skip Xcode Project Update" in the Cocos Creator build panel, the content added above will be overwritten when building iOS next time. It is recommended to modify the "native/engine/ios/Info.plist" file and ensure that the "native/engine/ios" directory is tracked by git, so that the added permission declarations can be persisted.

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

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

macOS

Add camera and microphone permission declarations according to actual needs. For details, please refer to iOS.

It is recommended to modify the "native/engine/mac/Info.plist" file and ensure that the "native/engine/mac" directory is tracked by git, so that the added permission declarations can be persisted.

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

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

FAQ

1. How to handle the JS error ReferenceError: ZegoExpressBridge is not defined when running on Android?

Please check the "build/android/proj/build/cmake/debug/arm64-v8a/build_output.txt" build output file and search for "ZEGO". If no relevant content is found, it means the SDK was not loaded successfully.
If you find the output "NodeJS is not found in $PATH", it means that cmake executed inside Android Studio cannot find node, causing the SDK to fail to load. Please refer to Issue.
Please refer to the hints for Android projects in "Step 6" of Import SDK: start Android Studio by entering open -a "Android Studio" in Terminal.
After starting Android Studio, first select "Build > Clean Project" in the menu bar to clean the build cache, then select "File > Invalidate Caches..." in the menu bar to clear the IDE cache and restart Android Studio.

In the menu bar, select "File > Sync Project With Gradle Files" to check whether there is a "src" folder containing ZEGO related C++ source code under the "MyAwesomeProject > cpp" folder in the project directory. If it does not exist, please clean the cache and restart Android Studio again.
(Optional) If the problem still cannot be solved after repeatedly cleaning and restarting multiple times, please contact ZEGO Technical Support.

2. How to handle the error java.lang.UnsatisfiedLinkError: dlopen failed: library "libZegoExpressEngine.so" not found when building an Android project?

The SDK is not integrated completely. Please refer to the additional processing steps for Android projects in "Step 6" of Import SDK.

3. How to handle the following error when building an Android project?

* What went wrong:
Execution failed for task ':libcocos:compileReleaseJavaWithJavac'.
> java.lang.IllegalAccessError: class org.gradle.internal.compiler.java.ClassNameCollector (in unnamed module @0x7e7b1ec8) cannot access class com.sun.tools.javac.code.Symbol$TypeSymbol (in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.code to unnamed module @0x7e7b1ec8

* What went wrong:
Execution failed for task ':libcocos:compileReleaseJavaWithJavac'.
> java.lang.IllegalAccessError: class org.gradle.internal.compiler.java.ClassNameCollector (in unnamed module @0x7e7b1ec8) cannot access class com.sun.tools.javac.code.Symbol$TypeSymbol (in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.code to unnamed module @0x7e7b1ec8

Generally, the JDK version on the machine is too high, which is not compatible with the Android Gradle Plugin version of the Cocos native project template. It is recommended to install and use JDK 11.

If the machine has already specified to use JDK 11 (the environment variable JAVA_HOME points to JDK 11), but this error is still reported, it may be because when macOS directly opens the "CocosDashborad" application, it does not read the JAVA_HOME environment variable defined in .zshrc. Please start "CocosDashborad" by entering open -a CocosDashboard in Terminal.

4. How to solve the problem of blurred screens and fonts when running on Windows?

Cocos Creator has poor display performance on Windows, which is a known issue. The optimization methods are as follows:

In the menu bar, select "Project > Project Settings > Macro Config", and check "ENABLE_WEBGL_ANTIALIAS" and "ENABLE_ANTIALIAS_FXAA".

For the problem of blurred Label text display, you can expand the font size Font Size by 2 times, and set the Node's Scale to 0.5 times the original.

5. How to handle the error Undefined symbol: _zego_express_xxxxxxxxxx when building an iOS simulator?

Please refer to the additional processing steps for iOS projects in "Step 6" of Import SDK.

6. How to handle the inevitable crash Assertion failed when running the Debug package?

There is a bug in Cocos Creator version 3.6.2. It is recommended to use Cocos Creator 3.6.1 / 3.6.3 or higher versions, or you can also fix it yourself according to the Pull Request of the Cocos engine.

7. How to handle the following error when building an iOS or macOS project?

[cmake] -- The CXX compiler identification is unknown
[cmake-err] CMake Error at CMakeLists.txt:6 (project):
    No CMAKE_CXX_COMPILER could be found.

[cmake] -- The CXX compiler identification is unknown
[cmake-err] CMake Error at CMakeLists.txt:6 (project):
    No CMAKE_CXX_COMPILER could be found.

When using Xcode 14 or higher, CMake 3.23.3 or higher is required. For details, please refer to Issue. If you have installed a new version of CMake but still encounter this problem, please select "CocosCreator > Preferences > External Programs" in the menu bar and specify CMake as the path you installed yourself.

8. When previewing in the CocosCreator editor, there is no response when calling the SDK interface?

The current version of the SDK does not support the Web platform temporarily. Please use "Build & Publish" to run to the native platform.