Start a Video Call

The Agora Video SDK for iOS makes it easy to embed real-time Video Call into iOS apps. It enables you to develop rapidly and easily to enhance your social, work, education and IoT apps with face-to-face interaction.

This page shows the minimum code you need to add video call into your app by using the Agora Video SDK for iOS.

Understand the tech

The following figure shows the workflow to integrate into your app in order to add Video Call functionality.

As shown in the figure, the workflow for adding Video Call in your project is as follows:

1. Retrieve a token
   A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.

2. Join a channel
   Call joinChannel to create and join a channel. App clients that pass the same channel name join the same channel.

3. Publish and subscribe to audio and video in the channel
   After joining a channel, the app client automatically publishes and subscribes to audio and video in the channel.

For an app client to join a channel, you need the following information:

• The App ID: A randomly generated string provided by Agora for identifying your app. You can get the App ID from Agora Console.
• The user ID: The unique identifier of a user. You need to specify the user ID yourself, and ensure that it is unique in the channel.
• A token: In a test or production environment, your app client retrieves tokens from a server in your security infrastructure. For this page, you use a temporary token with a validity period of 24 hours that you retrieve from Agora Console.
• The channel name: A string that identifies the channel for the video call.

Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

• Xcode 9.0 or later.
• An iOS device running iOS 9.0 or later.
• A valid Agora account.
• A valid Agora project with an App ID and a temporary token. For details, see Get Started with Agora.
• A computer with access to the internet. If your network has a firewall, follow the instructions in Firewall Requirements.

Project setup

In Xcode, follow the steps to create the environment necessary to add Video Call into your app.

1. Create a new iOS app and configure the following settings:
   • Product Name: Any name you like.
   • Team: If you have added a team, choose it from the pop-up menu. If not, you can see the Add account button. Click it, input your Apple ID, and click Next to add your team.
   • Organization Identifier: The identifier of your organization. If you do not belong to an organization, use any identifier you like.
   • Interface: Choose Storyboard.
   • Language: Choose Swift.

2. Integrate the Video SDK into your project:

   Go to File > Swift Packages > Add Package Dependencies..., and paste the following URL:

     https://github.com/AgoraIO/AgoraRtcEngine_iOS

   In Choose Package Options, specify the Video SDK version you want to use. You need to fill in x.y.z for version x.y.z and x.y.z-r.a for version x.y.z.a. For example, fill in 3.5.0 for version 3.5.0 and 3.5.0-r.2 for version 3.5.0.2.

3. Enable automatic signing for your project.
4. Set the deployment target for your app:
   1. In the project editor, choose your target and click General.
   2. In the Deployment Info settings, choose the operating system version for your iOS app from the dropdown menu.

5. Add permissions for microphone and camera usage.
   In the Project navigator, open the info.plist file of your project and add the following properties:
   • Privacy - Microphone Usage Description
   • Privacy - Camera Usage Description

Implement a client for Video Call

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

Create the UI

In the interface, you should have one frame for local video and another for remote video. In ViewController.swift, replace any existing content with the following:

import UIKit
class ViewController: UIViewController {
    var localView: UIView!
    var remoteView: UIView!

    override func viewDidLoad() {
        super.viewDidLoad()
        initView()
     }

    override func viewDidLayoutSubviews() {
        super.viewDidLayoutSubviews()
        remoteView.frame = self.view.bounds
        localView.frame = CGRect(x: self.view.bounds.width - 90, y: 0, width: 90, height: 160)
    }

    func initView() {
        remoteView = UIView()
        self.view.addSubview(remoteView)
        localView = UIView()
        self.view.addSubview(localView)
    }
}

Implement the Video Call logic

When your app opens, you create an RtcEngine instance, enable the video, join a channel, and publish the local video to the lower frame layout in the UI. When another user joins the channel, your app catches the join event and adds the remote video to the top frame layout in the UI.

The following figure shows the API call sequence of implementing Video Call.

To implement this logic, take the following steps:

1. Import the Agora kit and add the agoraKit variable.

   Modify your ViewController.swift as follows:

   import UIKit
   // Add this line to import the Agora kit
   import AgoraRtcKit
   class ViewController: UIViewController {
       var localView: UIView!
       var remoteView: UIView!
       // Add this linke to add the agoraKit variable
       var agoraKit: AgoraRtcEngineKit?
   
       override func viewDidLoad() {
           super.viewDidLoad()
           initView()
        }

2. Initialize the app and join the channel.

   Call the core methods to initialize the app and join a channel. In this example app, this functionality is encapsulated in the initializeAndJoinChannel function.

   In ViewController.swift, add the following lines after the initView function, and fill in your App ID, temporary token, and channel name:

    func initializeAndJoinChannel() {
      // Pass in your App ID here
      agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: "Your App ID", delegate: self)
      // Video is disabled by default. You need to call enableVideo to start a video stream.
      agoraKit?.enableVideo()
           // Create a videoCanvas to render the local video
           let videoCanvas = AgoraRtcVideoCanvas()
           videoCanvas.uid = 0
           videoCanvas.renderMode = .hidden
           videoCanvas.view = localView
           agoraKit?.setupLocalVideo(videoCanvas)
   
      // Join the channel with a token. Pass in your token and channel name here
      agoraKit?.joinChannel(byToken: "Your token", channelId: "Channel name", info: nil, uid: 0, joinSuccess: { (channel, uid, elapsed) in
           })
       }

3. Add the remote interface when a remote user joins the channel.

   In ViewController.swift, add the following lines after the ViewController class:

    extension ViewController: AgoraRtcEngineDelegate {
        // This callback is triggered when a remote user joins the channel
        func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
            let videoCanvas = AgoraRtcVideoCanvas()
            videoCanvas.uid = uid
            videoCanvas.renderMode = .hidden
            videoCanvas.view = remoteView
            agoraKit?.setupRemoteVideo(videoCanvas)
        }
    }

Start and stop your app

Now you have created the Video Call functionality, add the functionality of starting and stopping the app. In this implementation, a video call starts when the user opens your app. The call ends when the user closes your app.

To implement the functionality of starting and stopping the app:

1. When the view is loaded, call initializeAndJoinChannel to join a video call channel.

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

   override func viewDidLoad() {
           super.viewDidLoad()
           initView()
           // Add this line
           initializeAndJoinChannel()
        }

2. When the user closes this app, clean up all the resources used by your app.

   In ViewController.swift, add viewDidDisappear after the initializeAndJoinChannel function.

   override func viewDidDisappear(_ animated: Bool) {
          super.viewDidDisappear(animated)
          agoraKit?.leaveChannel(nil)
          AgoraRtcEngineKit.destroy()
    }        

Test your app

To test your app on a physical device, do the following:

1. Check whether you fill in your App ID, temporary token, and channel name in ViewController.swift.

2. Connect an iOS device to your computer.

3. In Xcode, choose the device from the scheme menu in the toolbar, and click the Run button.

4. On your device, launch the app and grant microphone and camera access.

   You can see yourself on the local view.

5. Ask a friend to join the video call with you on the demo app. Your friend needs to enter the same App ID and channel name.

   When your friend joins the channel, you can see and hear each other.

Next steps

Generating a token by hand is not helpful in a production context. Authenticate Your Users with Tokens shows you how to start Video Call with a token that you retrieve from your server.

See also

This section provides additional information for your reference:

Sample project

Agora provides an open-source sample project Basic Video Call on GitHub that implements one-to-one video call and group video call for your reference.

Other approaches to integrate the latest SDK

In addition to integrating the Agora Video SDK for iOS through Swift Package, you can also import the SDK into your project through CocoaPods or by manually copying the SDK files.

Automatically integrate the SDK with CocoaPods

1. Install CocoaPods if you have not. See Getting Started with CocoaPods.

2. In Terminal, navigate to the root of your project folder, and run the pod init command to create a Podfile in the project folder.

3. Open the Podfile, and replace all contents with the following code. Remember to replace Your App with the target name of your project.

   # platform :ios, '9.0'
   target 'Your App' do
      pod 'AgoraRtcEngine_iOS'
   end

4. In Terminal, run the pod install command to install the SDK. When the SDK is installed successfully, you can see Pod installation complete! in Terminal and an xcworkspace file in the project folder.
5. Open the xcworkspace file for any further steps.

Manually copy the SDK files

1. Go to SDK Downloads, download the latest version of the Agora Video SDK, and extract the files from the downloaded SDK package.

2. From the libs folder of the downloaded SDK package, copy the files or subfolders you need to the root of your project folder.

3. In Xcode, link your target to the frameworks or libraries you have copied. Be sure to choose Embed & Sign from the pop-up menu in the Embed column.

   • Apple does not allow an app extension to contain any dynamic library. If you are integrating the Agora SDK to an app extension, choose Do Not Embed in the Embed column.
   • The Agora SDK uses libc++ (LLVM) by default. Contact support@agora.io if you want to use libstdc++ (GNU). The SDK provides FAT image libraries with multi-architecture support for both 32/64-bit audio emulators and 32/64-bit audio/video real devices.

Integrate earlier versions of the SDK

Choose one of the following methods to integrate a version of the Agora iOS SDK earlier than v3.2.0.

Method 1: Through CocoaPods

1. Ensure that you have installed CocoaPods before performing the following steps. See the installation guide in Getting Started with CocoaPods.

2. In Terminal, navigate to the project path, and run the pod init command to create a Podfile in the project folder.

3. Open the Podfile, delete all contents, and input the following codes. Remember to replace Your App with the target name of your project and replace version with the version of the SDK that you want to integrate. For information about the SDK version, see Release Notes.

   # platform :ios, '9.0'
   target 'Your App' do
    pod 'AgoraRtcEngine_iOS', 'version'
   end

4. Return to Terminal, and run the pod install command to install the Agora SDK. Once you successfully install the SDK, it shows Pod installation complete! in Terminal, and you can see an xcworkspace file in the project folder.

5. Open the generated xcworkspace file.

Method 2: Through your local storage

You need to use different integration methods to integrate different versions of the SDK. Click the following version categories to expand the corresponding integration steps.

Distribution consideration

If you integrate dynamic libraries under the path of ./libs/ALL_ARCHITECTURE in the SDK package, you need to remove the x86-64 architecture in the libraries before uploading the app to the App Store.

In Terminal, run the following command to remove the x86-64 architecture. Remember to replace ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit with the path of the dynamic library in your project.

lipo -remove x86-64 ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit -output ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit

See more considerations in Preparing Your App for Distribution.

Objective-C code sample

To implement Video Call in your app using Objective-C:

1. Replace the contents in the ViewController.h file with the following:

   #import <UIKit/UIKit.h>
   
   #import <AgoraRtcKit/AgoraRtcEngineKit.h>
   
   @interface ViewController : UIViewController <AgoraRtcEngineDelegate>
   @property (strong, nonatomic) AgoraRtcEngineKit *agoraKit;
   
   @end

2. Replace the contents in the ViewController.m file with the following:

   #import "ViewController.h"
   #import <UIKit/UIKit.h>
   
   @interface ViewController ()
   @property (nonatomic, strong) UIView *localView;
   @property (nonatomic, strong) UIView *remoteView;
   @end
   
   @implementation ViewController
   - (void)viewDidLoad {
       [super viewDidLoad];
       [self initViews];
       [self initializeAndJoinChannel];
   }
   
   - (void)viewDidLayoutSubviews {
       [super viewDidLayoutSubviews];
       self.remoteView.frame = self.view.bounds;
       self.localView.frame = CGRectMake(self.view.bounds.size.width - 90, 0, 90, 160);
   }
   
   - (void)initViews {
       self.remoteView = [[UIView alloc] init];
       [self.view addSubview:self.remoteView];
       self.localView = [[UIView alloc] init];
       [self.view addSubview:self.localView];
   }
   
   - (void)initializeAndJoinChannel {
       // Pass in your App ID here
       self.agoraKit = [AgoraRtcEngineKit sharedEngineWithAppId:@"Your App ID" delegate:self];
       [self.agoraKit enableVideo];
       AgoraRtcVideoCanvas *videoCanvas = [[AgoraRtcVideoCanvas alloc] init];
       videoCanvas.uid = 0;
       videoCanvas.renderMode = AgoraVideoRenderModeHidden;
       videoCanvas.view = self.localView;
       [self.agoraKit setupLocalVideo:videoCanvas];
       // Pass in your token and channel name here
       [self.agoraKit joinChannelByToken:@"Your token" channelId:@"Channel name" info:nil uid:0 joinSuccess:^(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed) {
       }];
   }
   
   - (void)rtcEngine:(AgoraRtcEngineKit *)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed {
       AgoraRtcVideoCanvas *videoCanvas = [[AgoraRtcVideoCanvas alloc] init];
       videoCanvas.uid = uid;
       videoCanvas.renderMode = AgoraVideoRenderModeHidden;
       videoCanvas.view = self.remoteView;
       [self.agoraKit setupRemoteVideo:videoCanvas];
   }
   
     - (void)viewDidDisappear:(BOOL)animated {
     [super viewDidDisappear:animated];
     [self.agoraKit leaveChannel:nil];
     [AgoraRtcEngineKit destroy];
   }
   @end