Integrate the SDK

---

Set up the development environment

Before integrating the ZEGO Express SDK, make sure 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).

  Do not use Cocos Creator v3.6.2, please refer to FAQ-6 for details.

• Ensure the corresponding development environment and equipment according to the platform that needs to run.

  • Android: An Android device or emulator with Android 5.0 or above that supports audio and video (recommended to use a real device). If it is a real device, please enable the Allow Debugging option.
  • iOS: Xcode 14.0 or above, iOS 11.0 or above and an iOS device or simulator that supports audio and video (a real device is recommended).
  • macOS: Xcode 14.0 or above, macOS devices with macOS 10.13 or above that support audio and video.
  • Windows: A Windows device with Windows 7 or above that supports audio and video; and Visual Studio 2019 or above installed.

• Make sure the running device is connected to the Internet.

Create a new project

Skip this step if a project already exists.

Create a new project

Open CocosDashboard, create a new project, select a template according to the actual situation, fill in the project name and specify the location where the project is saved, and create the project.

Import the SDK

Currently, Cocos Creator SDK supports different platforms such as Android, iOS, macOS, and Windows.

1. Download the latest SDK and extract files from the downloaded SDK package. For more details, see SDK downloads.

2. Open Extensions > Extension Manager, under the project tab, click the + button to add an extension, and select the SDK zip package downloaded in the previous step.

3. After the import is complete, confirm that zego_express_cocos_creator_sdk exists in the extension manager and is enabled, and then check the Assets tab. 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, and will be automatically deleted when the SDK is disabled. Therefore, it is recommended to add the assets/zego_express_engine directory to .gitignore without committing to git.

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

4. According to Cocos Creator Publishing to Native Platforms document and actual situation, build a native platform project.

   If the build fails, please open the build log file to view the error message and correct the problem according to the error prompt. If the error message is related to ZEGO SDK and you can't solve it by yourself, please contact ZEGO technical support.

5. Add native/engine native project configuration files to git tracking.

   It is recommended to add the native/engine directory of the project to git tracking, so that the configuration of the native project can be tracked persistently, which is very helpful in multi-person collaboration. Open the .gitignore file in the root directory of the project, you can see that the native directory in the default template is ignored, you can change it to:

   native/*
   !native/engine/

   

   This lets git collect the files in the native/engine directory.

6. Some platforms need to do some extra processing.

   • Android

     1. Use Android Studio to open the native project MyAwesomeProject/build/android/proj

        If you use macOS to develop, do not open Android Studio directly, but open the terminal, and enter open -a "Android Studio" to start Android Studio to solve potential issues, please refer to this Issue for more information.

     2. Open native/engine/android/app/build.gradle file and add the directory where the SDK Native plugin library is located in the android.sourceSets.main.jniLibs node.

        srcDir "../../../plugins/zego_express_engine/android/libs"

        

     3. Import all jar packages of the SDK native plugin library in the dependencies node.

        implementation fileTree(dir: "../../../plugins/zego_express_engine/android/libs", include: ['*.jar'])

        

     4. In the native/engine/android/app/proguard-rules.pro file, add the -keep configuration for the SDK to prevent confusing the SDK public class name: -keep class **.zego.**{*;} .

   • iOS

     1. The SDK plugin uses the iOS device architecture by default. To build for iOS Simulator, please open the native/engine/ios/CMakeLists.txt file of your project, and add the following configuration above cc_ios_before_target:

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

        

     2. In the Build panel, click Build button to regenerate the iOS Xcode project. When you need to build for iOS device, just change the above cmake value to DEVICE, or delete this line of configuration.

     3. (Optional) For the Cocos Creator iOS native project, it is recommended to directly use the exported Xcode project to compile, run, and debug. It is not recommended to use the "Make" and "Run" buttons in the Build panel to compile and run iOS app.

     4. (Optional) If you must use the "Make" and "Run" button in the Build panel to directly compile and run the app, note that OS Target in the Build panel can only check one of them, and you cannot check the iPhone OS at the same time with the iOS Simulator, otherwise the build will fail. And when iOS Simulator is checked, you need to modify the CMake configuration of the iOS native project according to the above guidelines.

        

Add camera and microphone permissions

Follow these procedures to set the camera and microphone permissions for different platforms.

Android

According to your needs, set the permissions required by the application.

Open native/engine/android/app/AndroidManifest.xml file, add permissions.

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

The following simple code applies for permission when the app starts, or it can be applied at an appropriate time according to the actual situation (apply before calling createEngine of the SDK).

// 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

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

1. In Xcode, select the TARGETS > Info > Custom iOS Target Properties menu.

   

2. Click the + button to add camera and microphone permissions according to actual application needs.

   • Privacy - Camera Usage Description

   • Privacy - Microphone Usage Description

     

3. (Optional) If you do not check Skip Xcode project update in the Cocos Creator Build panel, the content added above will be overwritten the next time you build iOS. 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 statement can be persisted.

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

macOS

Please refer to iOS above to add camera and microphone permission statements according to actual needs.

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 statement can be persisted.

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

FAQ

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

1. Please check the build/android/proj/build/cmake/debug/arm64-v8a/build_output.txt build output file, search for ZEGO, if you can't find the relevant content, it means that the SDK has not been loaded successfully.

2. If there is an output of NodeJS is not found in $PATH, it means that the cmake executed in Android Studio cannot find node and the SDK cannot be loaded, please refer to this Issue.

3. Please refer to the tips above about the extra processing for Android project: enter open -a "Android Studio" through the terminal to start Android Studio.

4. After starting Android Studio, first in the menu bar, click Build > Clean Project to clear the build cache, then click File > Invalidate Caches... to clear the IDE cache and restart Android Studio.

5. In the menu bar, click File > Sync Project With Gradle Files, check whether there is a src folder containing ZEGO related C++ source code under the MyAwesomeProject > cpp folder in the project directory, if not, please clean the cache again and restart Android Studio.

6. (Optional) If you still cannot solve the problem after repeated cleaning and restarting, please contact ZEGO technical support.

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

The SDK is not fully integrated, please refer to the tips above about the extra processing for Android project.

3. The following error is reported when building the Android project, how to deal with it?

* 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 of your local 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 your machine has been specified to use JDK 11 (environment variable JAVA_HOME points to JDK 11), but still reports this error, it may be that macOS did not read the JAVA_HOME environment variable defined in .zshrc, please enter open -a CocosDashboard through the terminal to start CocosDashboard.

4. How to solve the blurred screen and fonts when running Windows?

The display effect of Cocos Creator app on Windows is not good, the optimization method is as follows:

1. In the menu bar, click Project > Project Settings > Macro Configurations, and check ENABLE_WEBGL_ANTIALIAS and ENABLE_ANTIALIAS_FXAA.

2. To solve the problem of blurred Label text display, the Font Size can be enlarged by 2 times, and the Scale of Node can be set to 0.5 times of the original.

5. How to deal with the error message Undefined symbol: _zego_express_xxxxxxxxxx when build for iOS simulator?

Please refer to the tips above about the extra processing for iOS project.

6. How to deal with Assertion failed crash when debugging?

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

7. How to deal with the error when build for iOS or macOS?

The error is shown as follows：

[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 later, CMake 3.23.3 or later is required, please refer to this Issue for details. 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. Why the SDK does not respond to the API calling when previewing in the editor of Cocos Creator?

The current version of the SDK does not support the web platform, please use Build panel run your game on native platform.