Migration Guide from TokBox to Agora: iOS Edition

November 13, 2020 By Jonathan Fotland In Developer

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.