Quick Start: iOS (Objective-C)

  • Jul 5, 2016
  • Starting Guide
  • iOS
  • Objective-C

Get your free API key

Before you can use the Realtime Messaging API you need to register, create a "Realtime Messaging Subscription" and make a note of your Realtime application key (this document will refer to it as APP_KEY).

A note about security

This Quick Start Guide assumes your APP_KEY has authentication disabled (by default and for simplity reasons all Realtime application keys have authentication disabled when they are created).

This means you can use any token to connect to a Realtime server. In the examples below we'll use testToken.

When you're ready for production you should enable authentication (we'll cover this on the Security section ahead).

Swift or Objective-C?

This guide uses the Objective-C language. If you are a Swift developer please check the Swift guide.

Install the client library

The best way to install the Realtime library is using CocoaPods, a library dependency manager for Xcode projects. If you don't have it already installed please follow these setup instructions before proceeding.

Open a terminal window in your project directory and create an empty Podfile by running the following command:

pod init

Open your Podfile (created in your project directory) and enter the Realtime Messaging Pod configuration:

pod 'RealtimeMessaging-iOS'

The Podfile should look like this (for an Objective-C project named iosExample):

# Uncomment this line to define a global platform for your project
# platform :ios, '9.0'

target 'iosExample' do
  # Uncomment this line if you're using Swift or would like to use dynamic frameworks
  # use_frameworks!

  # Pods for iosExample

  pod 'RealtimeMessaging-iOS'

  target 'iosExampleTests' do
    inherit! :search_paths
    # Pods for testing

  target 'iosExampleUITests' do
    inherit! :search_paths
    # Pods for testing


Now that you have your Podfile configured run the following command to install the required dependencies:

pod install     		

Close your Xcode project and open the xcworkspace that was created (a file named {your app name}.xcworkspace in your project directory). This should be the file you use everyday to create your app from now on.

Open a connection to Realtime

Before you can start sending and receiving messages you need to open a connection to a Realtime server. To perform this action start by importing Realtime into the class that wants to make use of the library. In this guide we'll use the Xcode generated ViewController so we simply add it to the ViewController.h file.

#import <OrtcClient.h>

You'll also need to add the interface OrtcClientDelegate to the class that wants to make use of the library. In a single view app it could be the Xcode generated ViewController interface (in your app you'll probably want to create a new interface, but that's up to you). It's also a best practice to keep the Realtime connection as a property in your class.

The ViewController interface definition (ViewController.h) would like this:

@interface ViewController : UIViewController <OrtcClientDelegate>
@property OrtcClient* ortcClient;

Now that we have the proper definitions in place let's handle the code to establish the Realtime connection. Enter the following code in your ViewController viewDidLoad method replacing APP_KEY with your Realtime application key:

_ortcClient = [OrtcClient ortcClientWithConfig:self];
[_ortcClient setClusterUrl:@"https://ortc-developers.realtime.co/server/ssl/2.1"];
[_ortcClient connect:@"APP_KEY" authenticationToken:@"testToken"];

Since you didn't implement the complete OrtcClientDelegate interface (optional in Objective-C) Xcode will raise some warnings but you can ignored them for now.

Subscribe to a channel

Realtime Messaging is a pub/sub system based on channels (aka as topics). This means that each connected client can only receive messages on channels that were subscribed. To subscribe a channel you simply define the channel name and which callback function should handle each message received.

However you must guarantee that your client is propertly connected before you subscribe a channel by implementing the onConnected event delegate handler. This event will be invoked when the connection is ready for subscriptions and/or sending messages.

The following code shows how to subscribe to channel myChannel using the onConnected event:

- (void) onConnected:(OrtcClient*) ortc
    [_ortcClient subscribe:@"myChannel" subscribeOnReconnected:YES
	        onMessage:^(OrtcClient* ortc, NSString* channel, NSString* message) {
	            NSLog(@"Received at %@: %@", channel, message);

You're now ready to build and run your app! The previous code will show each message received through myChannel in your Xcode Debug Area.

To send messages to test your app you can use the simple console available in the Realtime Account Management website or the advanced console available at console.realtime.co

Send a message to a channel

As soon as you are connected you can start sending messages directly from your iOS app using the send method.

[_ortcClient send:@"myChannel" message:@"A simple text message"];		

Note that Realtime messages are text-based (UTF-8 encoded).

To receive messages sent from your app you can use the simple console available in the Realtime Account Management website or the advanced console available at console.realtime.co. Don't forget to subscribe the channel myChannel

More iOS resources

The Realtime iOS Objective-C SDK has more features that are beyond the scope of this quick starting guide. Please refer to the Objective-C Group Chat example in GitHub to test the other SDK features (including push notifications).

Back to Android Quick Start - Next: Security

If you find this interesting please share: