iOSiOSJavaScriptChatEnginePubNub ChatEngine iOS Framework v0.9.2

ChatEngine can be integrated into your project using CocoaPods. Next two steps will help prepare environment and project for ChatEngine usage:

  1. Latest version of CocoaPods required. Following commands can be used to install and/or update CocoaPods:

    gem install cocoapods
    gem update cocoapods
  2. Create or update existing Podfile in your project root folder and add:

    pod 'CENChatEngine'

PubNub ChatEngine is an object oriented event emitter based framework for building chat applications in Objective-C. It reduces the time to build chat applications drastically and provides essential components like typing indicators, online presence monitoring and message history out of the box.

The real time server component is provided by PubNub. ChatEngine is designed to be extensible and includes a plugin framework to make adding new features simple.

PubNub ChatEngine is an object oriented event emitter based framework for building chat applications in Objective-C. PubNub ChatEngine makes it easy to build Slack, Flowdock, Discord, Skype, Snapchat, or WhatsApp with ease.

The real time server component is provided by PubNub. PubNub ChatEngine is extensible and includes a plugin framework to make dropping in features simple.

Include ChatEngine

#import <CENChatEngine/ChatEngine.h>

Refer to our QuickStart Tutorial to deploy a ChatEngine application in about 5 minutes.

Follow the instructions below to create a simple chat lobby where you can see who's online and invite one another to private chats.

First, we need to connect to ChatEngine via ChatEngine.connect. The values input into ChatEngine.connect create a new User called Me that this client will act as.

self.client.connect(@"serhii").state(@{  "team": @"red" }).perform();

This will connect to ChatEngine with Me.uuid equal to serhii a Me.state of @{ @"team": @"red" }.

Because ChatEngine must do some work to connect to the server, we must wait for it to respond before working with Chats and Users.

When ChatEngine is ready, it will emit $.ready. We can subscribe to this event with ChatEngine.on.

self.client.on(@"$.ready", ^(CENMe *me) {
    NSLog(@"ChatEngine ready to go!");
});

The $ represents a system event. You can read more about system events in the tutorial on Namespaces. You can subscribe to all system events via self.client.on(@"$.*"), read more in the tutorial on Wildcards.

When ChatEngine.on is fired, Me is supplied.

self.client.connect(@"serhii").state(@{  "team": @"red" }).perform();

self.client.on(@"$.ready", ^(CENMe *me) {
    self.me = me; // serhii
});

All calls made to ChatEngine are made on behalf of Me.

Let's create Chat for us to join. We'll make a Chat through which our users can communicate.

CENChat *lobby = self.client.Chat().name(@"lobby").create();

This will create a new Chat. We'll be connected to it automatically.

So how do we see other other people online? Well Me is automatically recorded as joining our Chat, and any other person who runs this program will see serhii as a user online on the Chat.

You can get a list of online users via Chat.users.

NSLog(@"Users: %@", lobby.users);

Will output:

{
    "serhii": <CENUser::0x000000 uuid: 'serhii'; state set: NO>
}

If we were to open another window and connect as stephen, we would see stephen in lobby.users.

self.client.connect(@"stephen").state(@{  "team": @"blue" }).perform();

Let's chat with stephen.

In order to chat, all we need to do is use the Chat.emit method to send a message over the internet to all other clients who have the program running.

lobby.emit(@"message").data(@{ @"text": @"hey" }).perform();

message is an event name that is just a string identifier. It helps us tell the difference between different events. See Events Namespaces and Wildcards for more.

data accept NSDictionary which represent the message payload. This data is sent over the internet to all subscribing parties.

We can get notified a new message by using Chat.on. The text value is available as payload[CENEventData.data][@"text"].

lobby.on(@"message", ^(NSDictionary *payload) {
    NSLog(@"Greetings: %@", payload[CENEventData.data][@"text"]);
});

We can also get the User that sent the message and the Chat the message was sent to. For more on this, see Event Payload.

lobby.on(@"message", ^(NSDictionary *payload) {
    CENChat *chat = payload[CENEventData.chat];
    CENUser *sender = payload[CENEventData.sender];

    NSLog(@"%@ sent a message to %@ with value: %@", sender.uuid, chat.name, payload[CENEventData.data]);
});

But hey, what if we want more information about the user that sent the message. Remember how we supplied @{ @"team": @"red" } during ChatEngine.connect?

self.client.connect(@"serhii").state(@{  "team": @"red" }).perform();

We can get that value with User.state. This value will be the same on every machine because state is synced between everybody.

lobby.on(@"message", ^(NSDictionary *payload) {
    CENUser *sender = payload[CENEventData.sender];

    NSLog(@"%@ sent a message: %@", sender.uuid, payload[CENEventData.data][@"text"]);
    NSLog(@"the are on '%@' team", sender.state[@"team"]);
});

What if we want to invite stephen into a private chat? We can find stephen from our list of users in the lobby. See Chat.users.

We can use stephen's uuid to get his User.

CENUser *stephen = lobby.users[@"stephen"];

Ok, let's make a new chat and invite him to it. We'll create a new Chat and then fire the Chat.invite which invites a User to a Chat.

CENChat *privateChat = self.client.Chat().name(@"private").private(YES).create();
privateChat.invite(stephen);

So how does stephen know that he got invited? Chat.invite sends stephen a direct message that nobody else can see over a special Chat called User.direct.

stephen can find out when someone invites him by subscribing to the $.invite event via Me.direct. The key for the new chat that we created is available as payload[CENEventData.data][@"channel"].

me.direct.on(@"$.invite", ^(NSDictionary *payload) {
    CENChat *invitedChat = self.client.Chat().name(payload[CENEventData.data][@"channel"]).create();

    invitedChat.emit(@"message").data(@{ @"text": @"hello everybody!" }).perform();
});

What if we want to support Markdown in our messages? We can use a ChatEngine plugin. Plugins are loaded via the Chat.plugin, User.plugin, Me.plugin, or ChatEngine.proto.

First, we need to add corresponding plugin to Podfile:

pod 'CENChatEngine/Plugin/Markdown'

Import plugin into file, where Chat will be created and plugin registered:

#import <CENChatEngine/CENMarkdownPlugin.h>

Then we create a new Chat and attach the plugin to it via Chat.plugin.

CENChat *pluginChat = self.client.Chat().name(@"markdown-chat").create();
pluginChat.plugin([CENMarkdownPlugin class]).store();

And now, when someone sends a message via Chat.emit...

pluginChat.emit(@"This is some *markdown* **for sure**.").perform();

The markdown plugin will parse markdown and replace it as NSAttributedString.

Check out the tutorials on Plugins and how Build a Plugin.