Parse has OpenTok iOS SDK’s back(end), so you don’t have to

Developing an iOS App itself is a huge undertaking: you want your product to be beautiful, interactive, and functional. That’s why Parse makes so much sense, it helps you avoid writing a backend server to power your App by giving you a data store and providing the most basic web services. These days many web services are incredibly powerful and help developers do really amazing things, like OpenTok, but they are targeted at having a backend. That’s where Parse Cloud Code comes in: it gives developers the ability to leverage the best of a back-end server in the path of least resistance.

TL;DR: Upload the code from this repo into your Parse Cloud Code application. Include it into your own script (here’s an example). Now you can create Sessions, generate Tokens, and more right from your own iOS (or any Parse powered) App by calling your cloud functions right from your client code (another example).

A few words about Security

OpenTok uses an API Key/Secret mechanism to authenticate a developer’s server-side requests when performing actions like making a new Session. The Secret is also used to sign data that you want to store in a Token. What you don’t want to do is include that Secret in your client side App, whether it be Javascript for a web App or an iOS App. This is important because there are real costs that come from a stream being published in your sessions with your API Key, you wouldn’t want to be picking up a malicious person’s minutes tab.

Parse has built-in authentication and authorization mechanisms that really come in handy here. As a developer, you get to decide how to handle login (maybe you want to use Twitter or Facebook or just plain email/password) to authenticate your users. Then you can use ACLs (Access Control Lists) to define what users are allowed to do (read public data, write private data, identify as part of a group, etc); this is authorization. Or maybe your application isn’t as intense and you are cool with simple anonymous users with all of the data being publicly readable and writable. The choice is yours, you know your needs the best, and thats the important part. We can piggyback off of these mechanisms to help you describe exactly who can make OpenTok Sessions, and to choose what data (like the Role) goes into their Tokens. Poof! You now have a solid security story behind your App.

Our Example App: Broadcasts

I’m going to take you through building an example App called Broadcasts to help illustrate how to set up an integration for yourself. The goal for Broadcasts is pretty simple, we want an App that lets any user start a Broadcast and lets any of the other users of the App watch. When a certain user creates a Broadcast, only that user can Publish video to it, and the rest can subscribe (this adds a little bit of authorization logic to our example).

There still are two parts to Broadcasts, the iOS code and the server-side code. The main difference here is that the server code is easy to write and deploy because its just a few functions using the existing Parse objects in the App, and I’ll show you how to write them.

You need to have an OpenTok Account for an API Key and Secret, and a Parse Application (call it Broadcasts) for an Application ID and Client Key. Let’s get started.

Setting Up: Let’s first set up Cloud Code for your App by installing the command line tool and creating a new directory to hold the project (more detailed instructions):

https://gist.github.com/4329703#file_setting_up.txt

Now parse/cloud/main.js is the file we will write our functions within. But before we do that we need to pull in the OpenTok library that I’ve provided. Copy the contents of this repository into a new directory called opentok so that you now have the directory layout as seen below:

https://gist.github.com/4329703#file_added_opentok_library.txt

Writing our Cloud Code: Now we’re going to create a few functions inside main.js. This code is customized to how we want Broadcasts to work. I’ve decided beforehand that the App contains objects of the class Broadcast that have two important properties: sessionId and owner. Note that I’m not calling it a Session; I’ve assigned it a name that is meaningful for the logic of this App (Broadcast) and then referenced an OpenTok Session with its sessionId property. The owner property is a Parse.User object and helps us figure out who is authorized to publish to the Broadcast. Use the code below and substitute your OpenTok API Key and Secret:

https://gist.github.com/4329703#file_main.js

The comments in the code above should help you understand what’s going on. You are not limited to follow the exact same logic, all that I’ve done is use the Parse JavaScript API to describe how I want to handle creating my Sessions (before a Broadcast object is saved) and generating my Tokens (when I call the function). Lets deploy it:

https://gist.github.com/4329703#file_deploy.txt

Server-side, done.

Setting iOS Up: Now we just hook the backend up to the iOS App. I’ve already provided a shell of the Broadcasts App for you. Download it into the iOS directory so your directory structure is as below:

https://gist.github.com/4329703#file_added_ios_shell.txt

The first thing you need to do is to add your OpenTok API Key, Parse Application ID, and Parse Client Key to the iOS/Broadcasts/Constants-sample.h file and then rename it to Constants.h. Now open Broadcasts.xcodeproj in Xcode. If you run the App now, you will see that you can create a Broadcast by tapping the ‘+’ in the top right, naming it, and hitting done. If you then select that row, you will go into that Broadcast but nothing will happen, there is a Label at the bottom that says we are Disconnected from OpenTok.

Sessions: You may have not realized, but this part is already done. When a new Broadcast gets saved, the beforeSave function we created in the Cloud Code should run and attach a sessionId property to each Broadcast object. Use the Parse Data Explorer to confirm this.

Tokens: There are two pieces we need to correctly generate a token: owners and calling the getBroadcastToken Cloud function

Owners: In the shell, the Broadcast object has no concept of an owner. We will be creating anonymous users through Parse so that every user has some sort of identity, and then assign a Broadcast’s owner when a new one is saved. Then we will use that information to help display which Broadcasts can be published to by the current user in the Table View. Lastly, we will use that owner information to decide whether we should publish or subscribe when we have opened a particular Broadcast. Follow the code examples below.

https://gist.github.com/4329703#file_BroadcastsAppDelegate.m

Add Line 9 above to make sure an anonymous user is created.

https://gist.github.com/4329703#file_BroadcastsCreationViewController.m

Add Lines 9-14 above to add an owner property to new Broadcasts before they are saved, and specify that they are publicly readable but only writable by the owner.

https://gist.github.com/4329703#file_BroadcastTableViewController.m

Edit the line matching line 8 to enable a ★ icon next to the Broadcasts in the Table that is owned by the current user.

https://gist.github.com/4329703#file_owner-BroadcastViewController.m

Create the method on lines 3-5 as a helper to find out of the current Broadcast is owned by the current user. Then use that method in the if statements that wrap the code on lines 12-15 and 23-25.

Calling getBroadcastToken in the Cloud: The last part is to call our Cloud Code function, which returns asynchronously, and then we use the result to finally connect to the OpenTok session.

https://gist.github.com/4329703#file_function-BroadcastViewController.m

Add the method call on lines 11-18 which contains a block that connects to the Session.

Build and Run: If all went well, you should be able to Run and play with the completed Broadcasts App. If you have any problems you can compare with the completed version of the App.

But wait, there’s more…

Why limit ourselves to using Parse for iOS Apps? You can also use their JavaScript API to save you the trouble of writing a backend for your web Apps, too. With the security model benefits I highlighted before, that might not be such a bad idea after all.