Integrate the SDK

Prepare the environment

Before integrating the ZEGO Express SDK, ensure that the development environment meets the following requirements:

Xcode 15.0 or later.
iOS 12.0 or later with iOS devices or simulators that support audio (real devices are recommended).
iOS devices are connected to the Internet.

Integrate the SDK

(Optional) Create a new project

This step uses creating a new project as an example. If integrating into an existing project, ignore this step.

Launch Xcode, click "Create a new Xcode project" in the "Welcome to Xcode" window, or select the "File > New > Project" menu. In the displayed form, select the iOS platform, and choose "App" under "Application".
Fill out the form and select various options to configure the project. After completion, click "Next".

You must provide "Product Name" and "Organization Identifier" to create the unique identifier "Bundle Identifier" for the App.
Select the project storage path and click "Create" to create the project.

Import the SDK

Developers can integrate the SDK through any of the following methods.

Method 1: Use Swift Package Manager for automatic integration (recommended)

Open Xcode and click the menu bar "File > Add Packages...". In the "Search or Enter Package URL" input box of the "Apple Swift Packages" dialog, enter the following URL and press Enter to confirm:
```
https://github.com/zegolibrary/express-audio-ios
```
```
https://github.com/zegolibrary/express-audio-ios
```
In "Dependency Rule", specify the SDK version you want to integrate (it is recommended to use the default "Up to Next Major Version"), then click "Add Package" to import the SDK. You can also refer to the Apple official documentation for settings.

Method 2: Use CocoaPods for automatic integration

Use CocoaPods for automatic integration

Install CocoaPods. For common installation issues, please refer to CocoaPods FAQ - Installing CocoaPods.
Open Terminal, navigate to the project root directory, and run the pod init command to create a Podfile file.
Open the Podfile file and add pod 'ZegoExpressAudio' under "target". You need to replace "MyProject" with your Target name.

Warning

Since the SDK is an XCFramework, CocoaPods v1.10.0 or later is required to integrate this SDK.
Starting from version v3.2.0, the Pod name for Express Video Call Video SDK has changed from ZegoExpressEngine/Video to ZegoExpressEngine; the Pod name for Express Voice Call Audio SDK has changed from ZegoExpressEngine/Audio to ZegoExpressAudio.

target 'MyProject' do
    use_frameworks!
    # Please enter the specific SDK version number
    # Please check the SDK latest version from the release notes and modify x.y.z to the specific version number
    pod 'ZegoExpressAudio', '~> x.y.z'
end

target 'MyProject' do
    use_frameworks!
    # Please enter the specific SDK version number
    # Please check the SDK latest version from the release notes and modify x.y.z to the specific version number
    pod 'ZegoExpressAudio', '~> x.y.z'
end

Run the pod repo update command to update the local index to ensure the latest version of the SDK can be installed. For the latest version number, please refer to the release history in Download SDK Package.
Run the pod install command to install the SDK.

Note

If the "CDN: trunk URL couldn't be downloaded" issue occurs, please refer to CocoaPods FAQ - Connection to trunk CDN issue.
If the "Unable to find a specification for 'ZegoExpressEngine'" issue occurs, please refer to CocoaPods FAQ - Unable to find project issue.
If the "CocoaPods could not find compatible versions for pod "ZegoExpressEngine"" issue occurs, please refer to CocoaPods FAQ - Unable to find project issue.

Method 3: Manually integrate by copying SDK files

Manually integrate by copying SDK files

Please refer to Download SDK Package to download the latest version of the SDK and extract it.
Manually copy the SDK dynamic library file "ZegoExpressEngine.xcframework" to your project directory.

XCFramework file description

XCFramework is a new packaging form that includes multiple platform architectures such as real devices and simulators at the same time. Please integrate it as a whole into the project. It is not recommended to split it for use. However, if you indeed only need to integrate the real device architecture separately, or integrate the simulator architecture separately, you can also extract the .framework inside the XCFramework for separate use.

ios-arm64: Suitable for iOS real devices.
ios-arm64_x86_64-maccatalyst: Suitable for Mac Catalyst package on macOS. Mac Catalyst is a new framework launched by Apple in 2019, namely UIKit for Mac, designed to let iPad Apps run on macOS. For details, please refer to Apple Developer - Mac Catalyst
ios-arm64_x86_64-simulator: Suitable for iOS simulators.

Open Xcode, select the "File > Add Files to "xxx" (xxx is the project name)" menu, and add the SDK library file to the project.
Select "TARGETS > General > Frameworks,Libraries,and Embedded Content" menu, add "ZegoExpressEngine.xcframework", and set "Embed" to "Embed & Sign".

Set permissions

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

In Xcode, select the "TARGETS > Info > Custom iOS Target Properties" menu.
Click the "+" button to add microphone permissions.
- Privacy - Microphone Usage Description

FAQ

When running the App, it prompts Building for iOS Simulator, but the linked and embedded framework'ZegoExpressEngine.framework' was built for iOS + iOS Simulator.

After Xcode 12.3, the framework with iOS + iOS (Simulator) dual-platform architecture is prohibited by default. It is recommended to replace it with XCFramework recommended by Apple. Or you can select "TARGETS > Build Settings > Validate Workspace" through Xcode and set the value of this parameter to YES to continue using the traditional framework.