
Migration Guide from TokBox to Agora: iOS Edition
Agora’s voice, video, and live-broadcasting software runs on a Software Defined Real-Time Network (SD-RTN™), which is a real-time transmission network built by Agora and the only network infrastructure specifically designed for Real-Time Engagement in the world. All voice and video services provided by the Agora SDK are deployed and transmitted through the Agora SD-RTN™.
The Agora SD-RTN™ may be one motivation for adopting the Agora iOS SDK for all of your voice, video, and live-broadcasting needs. Or you may be looking for ease of use or lower latency. Whatever the need may be, this guide details how a generically functional app with a working TokBox video integration may be disintegrated to provide essentially the same functionality but on a totally different infrastructure, with a smaller set of required methods, and an entirely new feel.
Agora offers this guide to drive adoption. To make things straightforward, we will be using the TokBox Quickstart sample app as a baseline:
- Codebase for the sample application: https://github.com/opentok/opentok-ios-sdk-samples/tree/master/Basic-Video-Chat
The codebase for the sample application is a standardized, generic, and minimalistic set of basic features or functionalities (call button, answer button, mute button, hang-up button, and programmatic video display view). This guide shows you how to convert these features from TokBox to the Agora SDK.
Overview
TokBox, which runs on media servers, has three layers comparable to Agora: session, token, and publishing and subscribing. The primary differences are that (1) sessions in TokBox are like channels in Agora, which exist independently of a user in Agora, (2) tokens are like Agora’s two options of security, and (3) subscribing and publishing is a much more redundant pattern for simply joining a channel. But no one-to-one correspondence like a bijection from one function in TokBox to another exists in Agora. This is primarily because of the difference in architecture. TokBox, for instance, relies heavily on delegates, while Agora’s architecture is based on a singleton.
Since TokBox relies heavily on the delegation design pattern, your first step in disintegrating TokBox is to eliminate the publisher, subscriber, and session delegates. Your next step is to integrate Agora’s singleton design pattern, which replaces tokens as well as sessions. Agora’s setup for remote or local video is similar but requires you to remove TokBox’s publish and subscribe architecture. With these steps completed, the remainder of the guide focuses on joining or leaving a channel.
After an instance of the AgoraRtcEngine is initialized, nearly all of the important aspects of the SDK’s functionality are called through its methods. In other words, all of the important SDK functions are its methods: setupLocalVideo
, setupRemoteVideo
, enableVideo
, setChannelProfile
, joinChannel
, and leaveChannel
. When you know how to use these methods, the Agora iOS SDK is at your fingertips.
Step One
The first step to replacing TokBox’s delegate design pattern with Agora’s singleton design pattern is to create an easily accessible variable in the
ViewController.swift
:
let AppID = "appID"
Step Two
This step requires replacing both the TokBox pod and the imports. In the Podfile
, add AgoraRtcEngine_iOS
in place of the OpenTok
pod, and then run pod install
in Terminal. At the top of the ViewController
file, replace the import OpenTok
with AgoraRtcKit
.
Step Three
This step requires replacing the three TokBox delegates with an instance of the Agora singleton. At the bottom of the ViewController
, remove the three extensions: OTPublisherDelegate
, OTSessionDelegate
, and OTSubscriberDelegate
. With these three delegates removed, create a function for initializing an instance of the Agora singleton:
func initializeAgoraEngine() {
agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId:
AppID, delegate: self)
}
Here you pass your AppID into the sharedEngine
method, assigning the delegate as “self.” With the initialization function set up, make sure to call the function in viewDidLoad
. Finally, make sure to create a property at the top of your ViewController
file for initialization:
var agoraKit: AgoraRtcEngineKit!
That is essentially all you need to completely replace TokBox’s delegate-heavy design pattern with Agora’s singleton design pattern. With the design pattern of the app’s architecture transformed, the next steps replace TokBox’s publisher and subscriber functionality with Agora’s local and remote video setups.
Step Four
To replace TokBox’s publisher and subscriber functionality with Agora’s local and remote video setups, remove the publisher and subscriber methods:
- doPublish()
- doSubscribe()
- cleanupSubscriber()
- cleanupPublisher()
- handleError(_ error: OTError?)
With these methods removed, you need to enable video, set up video, and configure the canvas or video display through a delegate, which is standard in iOS.
- Add a function for enabling video:
Agora’s AgoraVideoEncoderConfiguration is designed primarily to empower developers with the ability to set a video dimension, a frame rate, a bitrate, and an orientation so that you can control how to deliver your video.
- Add a function for setting up local video:
This example uses a stackView to quickly add the camera views to the view hierarchy, which you need to add to the Main.Storyboard
. You can also create views in the Storyboard directly, or set up your UI in any other way you like. All you need is a UIView somewhere that you can reference from the AgoraRtcVideoCanvas
.
The local video is the video stream from the local device. This is the equivalent of Tokbox’s doPublish
functionality. Once you join a channel, that video is streamed to other devices as remote video, which you set up a little later.
- Add an extension to ViewController for the AgoraRtcEngineDelegate to configure the canvas or video:
Agora’s delegate method didJoinedOfUid
kicks off the reception of another user’s local video when it joins the channel. Remember that another user’s local video comes into your device as remote video. If that UID drops off, didOfflineOfUid
handles the user’s departure and its consequences for the call.
Finally, add a call to setupLocalVideo
in viewDidLoad
.
Step Five
The final step is joining a channel. Users join channels with .joinChannel
, a single method in the Agora iOS SDK:
Although important for production, byToken is not important for our purposes, since Agora enables you to get up and running ASAP without having to deal with tokens by default. If you want to read more about tokens in the Agora SDK, check out the documentation or this blog.
The joinChannel
function replaces the doConnect
function and should also be called from viewDidLoad
.
Run
There you go! If it builds and runs, then you have successfully adopted Agora. Congratulations! Welcome to the benefits of the Agora SD-RTN™!
Although it would be impossible to account for all of the various integrations, you should note that you replaced all of the salient generic features of TokBox with those of Agora in only five steps. Now it should be easy to simulate fully a large-scale adoption with Agora. The necessary changes include the shift in design pattern architecture and the new concepts, such as local vs. remote video (as opposed to publish or subscribe), together with joining a channel.
Additional Resources
You can find the completed project here. For further reading and details on how to implement more specific features of the Agora engine, you can take a look at our documentation, join our Slack community, or email us at devrel@agora.io.