Getting started: Pub/Sub in Objective-C

This guide will get you started with Ably Pub/Sub in Objective-C.

You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history.

Prerequisites

1. Sign up for an Ably account.
2. Create a new app, and create your first API key in the API Keys tab of the dashboard.
3. Your API key will need the publish, subscribe, presence and history capabilities.
4. Install Xcode and create a new Objective-C project.
5. Add the Ably Pub/Sub Objective-C SDK as a dependency.

For CocoaPods, add the following to your Podfile:

pod 'Ably'

For Swift Package Manager, add the following URL:

https://github.com/ably/ably-cocoa

(Optional) Install Ably CLI

The Ably CLI provides a command-line interface for managing your Ably applications directly from your terminal.

1. Install the Ably CLI:

npm install -g @ably/cli

2. Run the following to log in to your Ably account and set the default app and API key:

ably login

Step 1: Connect to Ably

Clients establish a connection with Ably when they instantiate an SDK instance. This enables them to send and receive messages in realtime across channels.

Open up the dev console of your first app before instantiating your client so that you can see what happens.

Replace the contents of your main.m file with functionality to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use token authentication in production environments. A clientId ensures the client is identified, which is required to use certain features, such as presence:

#import <Foundation/Foundation.h>
#import <Ably/Ably.h>

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        // Initialize the Ably Realtime client
        ARTClientOptions *options = [[ARTClientOptions alloc] initWithKey:@"demokey:*****"];
        options.clientId = @"my-first-client";
        ARTRealtime *realtime = [[ARTRealtime alloc] initWithOptions:options];

        // Wait for the connection to be established
        [realtime.connection on:ARTRealtimeConnectionEventConnected callback:^(ARTConnectionStateChange *stateChange) {
            NSLog(@"Made my first connection!");
        }];

        // Keep the program running
        [[NSRunLoop currentRunLoop] run];
    }
    return 0;
}

You can monitor the lifecycle of clients' connections by registering a listener that will emit an event every time the connection state changes. For now, run the program to log a message to the console to know that the connection attempt was successful. You'll see the message printed to your console, and you can also inspect the connection event in the dev console of your app.

Step 2: Subscribe to a channel and publish a message

Messages contain the data that a client is communicating, such as a short 'hello' from a colleague, or a financial update being broadcast to subscribers from a server. Ably uses channels to separate messages into different topics, so that clients only ever receive messages on the channels they are subscribed to.

Add the following lines to your main function, above the line // Keep the program running, to create a channel instance and register a listener to subscribe to the channel:

// Get a channel instance
ARTRealtimeChannel *channel = [realtime.channels get:@"my-first-channel"];

// Subscribe to messages on the channel
[channel subscribe:^(ARTMessage *message) {
    NSLog(@"Received message: %@", message.data);
}];

Use the Ably CLI to publish a message to your first channel. The message will be received by the client you've subscribed to the channel, and be logged to the console.

ably channels publish my-first-channel 'Hello!' --name "myEvent"

In a new terminal tab, subscribe to the same channel using the CLI:

ably channels subscribe my-first-channel

Publish another message using the CLI and you will see that it's received instantly by the client you have running locally, as well as the subscribed terminal instance.

To publish a message in your code, you can add the following line to your main function, above the line // Keep the program running, after subscribing to the channel:

[channel publish:nil data:@"A message sent from my first client!"];

Step 3: Join the presence set

Presence enables clients to be aware of one another if they are present on the same channel. You can then show clients who else is online, provide a custom status update for each, and notify the channel when someone goes offline.

Add the following lines to your main function, above the line // Keep the program running, to subscribe to, and join, the presence set of the channel:

// Subscribe to presence events on the channel
[channel.presence subscribe:^(ARTPresenceMessage *presenceMessage) {
    NSLog(@"Event type: %@ from %@ with the data %@",
          ARTPresenceActionToStr(presenceMessage.action),
          presenceMessage.clientId,
          presenceMessage.data);
}];

// Enter the presence set
[channel.presence enter:@"I'm here!" callback:nil];

You can have another client join the presence set using the Ably CLI:

ably channels presence enter my-first-channel --data '{"status":"learning about Ably!"}'

Step 4: Retrieve message history

You can retrieve previously sent messages using the history feature. Ably stores all messages for 2 minutes by default in the event a client experiences network connectivity issues. You can extend the storage period of messages if required.

If more than 2 minutes has passed since you published a regular message (excluding the presence events), then publish some more before trying out history. You can use the Pub/Sub SDK, Ably CLI or the dev console to do this.

For example, using the Ably CLI to publish 5 messages:

ably channels publish --count 5 my-first-channel "Message number {{.Count}}" --name "myEvent"

Add the following lines to your main function, above the line // Keep the program running, to retrieve any messages that were recently published to the channel:

// Retrieve message history
[channel history:nil callback:^(ARTPaginatedResult<ARTMessage *> *result, ARTErrorInfo *error) {
    if (error) {
        NSLog(@"Error retrieving history: %@", error.message);
        return;
    }

    if (result.items.count > 0) {
        NSLog(@"Message History:");
        for (ARTMessage *message in result.items) {
            NSLog(@"%@", message.data);
        }
    } else {
        NSLog(@"No messages in history.");
    }
}];

The output will look similar to the following:

[
  'Message number 5',
  'Message number 4',
  'Message number 3',
  'Message number 2',
  'Message number 1'
]

Next steps

Continue to explore the documentation with Objective-C as the selected language:

• Understand token authentication before going to production.
• Understand how to effectively manage connections.
• Explore more advanced Pub/Sub concepts.

You can also explore the Ably CLI further, or visit the Pub/Sub API references.