

Voice Call v4.0.0 Beta





Start a Voice Call

Last updated 2022/09/29 06:24:09

Real-time voice chatting immerses people in the sights and sounds of human connections, keeping them engaged in your app longer.

This page shows the minimum code you need to integrate high-quality, low-latency Voice Call function into your app using the SDK.

Understand the tech

The following figure shows the workflow you need to integrate into your app in order to achieve Voice Call functionality.

To start voice call, implement the following steps in your app:

1. Set the role

Set both app clients as the host.

2. Join a channel

Call joinChannel to create and join a channel. When using the same App ID, users who pass in the same channel name enter the same channel.

3 and 4. Publish and subscribe to audio in the channel

After joining a channel, both hosts can publish audio stream to the channel and subscribe to each other.

Prerequisites

Xcode 12.0 or later.
Two macOS devices running macOS 10.10 or later.
A computer that can access the Internet. Ensure that no firewall is deployed in your network environment, otherwise the project fails.
A valid Agora account and an Agora project. Please refer to Start using the Agora platform and get the following information from Agora Console:
- The App ID: A randomly generated string provided by Agora for identifying your app.
- A temporary token: A token is the credential that authenticates a user when your app client joins a channel. A temporary token is valid for 24 hours.
- The channel name: A string that identifies the channel.
Apple developer account.

Project setup

In order to create the environment necessary to integrate Voice Call into your app, do the following in Xcode:

Create a new project for a macOS app using the App template. Make sure you select Storyboard as Interface, and Swift as Language.

If you have not added any team information, you can see an Add account... button. Click it, input your Apple ID, and click Next to add your team.
Enable automatic signing for your project.
Set the target devices to deploy your macOS app.
Add project permissions for microphone and camera usage.

Open the info.plist file in the project navigation panel, and edit the property list to add the following properties:

key type value

Privacy-Microphone Usage Description String The purpose for accessing the microphone, such as for a call or live interactive streaming.

Navigate to TARGETS > Project Name > Signing & Capabilities, and add the following permissions in App Sandbox and Hardened Runtime:
Capability Category Permission
App Sandbox

Network
Incoming Connections (Server)
Outgoing Connections (Client)
App Sandbox

Hardware
Audio Input
Hardened Runtime

Resource Access
Audio Input
- If you need to add a third-party plug-in or library (such as a third-party camera), and the signing of the third-party plug-in or library is different from your project, you need to navigate to Hardened Runtime > Runtime Exceptions, and check the Disable Library Validation option.
- See more considerations in Preparing Your App for Distribution.
Integrate the SDK into your project.

Ensure that you have installed CocoaPods before the following steps. If it is not installed, you can refer to Getting Started with CocoaPods to install Cocoapods to this machine.
1. Enter the project root directory in Terminal and run the pod init command, after which you can find the Podfile under the project directory.
2. Open the Podfile and modify it by referring to the code below. Remember to changeYour App to the target name of your project.
```
platform :macos, '10.11'
target 'Your App' do
    // For version, fill in a specific SDK version number. For example, '4.0.0.4` or `4.0.1`.
    // See release notes for the latest version of SDK.
    pod 'AgoraRtcEngine_macOS', 'version'
end
```
1. Run the pod install command in the Terminal to install the Agora SDK. Once you successfully install the SDK, it shows Pod installation complete!
2. A new file with a suffix of .xcworkspace is generated under the project folder. Use Xcode to open it for subsequent operations.
For more integration methods, see Other approaches to integrating the SDK.

key	type	value
Privacy-Microphone Usage Description	String	The purpose for accessing the microphone, such as for a call or live interactive streaming.

Capability	Category	Permission
App Sandbox	Network	Incoming Connections (Server) Outgoing Connections (Client)
App Sandbox	Hardware	Audio Input
Hardened Runtime	Resource Access	Audio Input

Implement a client for Voice Call

This section shows how to use the Agora SDK to implement Voice Call into your app step by step.

Create the UI

When creating the user interface for basic Voice Call, Agora recommends adding the video view of the host on both the local and remote clients. Refer to the following code samples to create a basic UI from scratch:

import Cocoa
class ViewController: BaseViewController{
    ...
    // Defines agoraKit
    var agoraKit: AgoraRtcEngineKit!
}

Implement the Voice Call logic

The following figure and steps show the API call sequence of implementing Voice Call.

To implement this logic, take the following steps:

Import the Agora kit.

In ViewController.swift, add the following line after import Cocoa:
```
import AgoraRtcKit
```

Initialize the Agora engine.

Call sharedEngineWithConfig to create and initialize the AgoraRtcEngineKit object. In ViewController.swift, add the following lines after the initView function:

func initializeAgoraEngine(){
    let config = AgoraRtcEngineConfig()
    // Pass in your App ID here.
    config.appId = <#Your app Id#>
    // Use AgoraRtcEngineDelegate for the following delegate parameter.
    agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
}

Join the channel with a temp token, channel name, and uid of your project. Configure channel profile and client role type at the same time.

In ViewController.swift, add the following lines after the initializeAgoraEngine function:

func joinChannel(){
    let option = AgoraRtcChannelMediaOptions()
    // For a voice call scenario, set the channel profile as liveBroadcasting.
    option.channelProfile = .of((Int32)(AgoraChannelProfile.liveBroadcasting.rawValue))
    // Set the client role as broadcaster or audience.
    option.clientRoleType = .of((Int32)(AgoraClientRole.broadcaster.rawValue))
    // Shut down the camera.
    option.publishCameraTrack = .of(false)

    // Join the channel with a temp token. Pass in your token and channel name here
   agoraKit.joinChannel(byToken: <#Your token#>, channelId: <#Your channel name#>, uid: 0, mediaOptions: option)
}

Start and stop your app

Now you have created the Voice Call functionality. In this implementation, a voice call starts when the user opens your app. The voice call ends when the user closes your app.

Join the channel after the view is loaded.

In ViewController.swift, add the viewDidLoad function inside the BaseViewController function:

override func viewDidLoad() {
    super.viewDidLoad()
    // The following functions are used when calling Agora APIs
    initializeAgoraEngine()
    joinChannel()
}

Leave the channel in order to clean up all resources related to the session.

In ViewController.swift, add the following codes.

If you want to release all resources used by the Agora SDK, call destroy to clean up all the resources you created in initializeAgoraEngine.
```
    agoraKit.leaveChannel(nil)
```

Test your app

Please follow the test procedure as shown in the example.

Connect the macOS devices to the computer.
In Xcode 12.2 or later, to avoid compliation errors, you need to navigate to TARGETS > Project Name > Build Settings > Architectures, and set the Architectures property to x86_64 before the compilation.
Click the Build button to run your project, and wait a few seconds till the installation completes.
Grant microphone access to your app.
When the app launches, ask a friend to use a second device to join the channel with the same App ID, token, and channel name. After your friend joins the channel, you can hear each other.

Next steps

In a test or production environment, use a token server to generate token is recommended to ensure communication security, see Authenticate Your Users with Tokens for details.