Latest 0.9.3
Homepage https://github.com/pubnub/chat-engine-apple
License MIT PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworks
Copyright (c) 2018 PubNub Inc.
http://www.pubnub.com/
http://www.pubnub.com/terms

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworks
Copyright (c) 2014 PubNub Inc.
http://www.pubnub.com/
http://www.pubnub.com/terms

Platforms ios 9.0, osx 10.11, tvos 9.0, requires ARC
Dependencies PubNub
Authors

Build Status

Documentation

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.

Docs

You can find the full docs on the full documentation website. Concepts are linked below for convenience.

Concepts

  • Me – It’s you dummy. The user that represents the current application.
  • Users and State – Explains how to interact with other users using ChatEngine and get additional information about them.
  • Chats – ChatEngine’s bread and butter. These are isolated rooms that users can talk to each other in.
  • Events – Events are things that happen in a chat. Like message or image_upload for example.
  • Event Payload – The data that comes with an event. Includes things like who sent the event and what chat it was sent to.
  • Namespaces – ChatEngine has a lot of events, so we use name spacing to isolate them.
  • Wildcards – Get all the events of a single namespace, like $.online.* to get all types of online events.
  • Search – Retrieve old events that happened in the past. Usually done when your application boots up to show what happened before.
  • Global Chat – The chat that all users connect to. It’s used for state management and application wide events.
  • Online List – Get all the users online in the chat room.
  • Authentication – How to use auth keys to identify your users and protect access to channels.
  • Privacy – Every user has a special feed chat that only they can publish to, and a direct chat that nobody else can read from. Outlines other ways of handling permissions as well.
  • Private Chats – Create private chats that nobody else can join.
  • Errors – Sometimes things don’t go as planned, here’s how you can catch errors gracefully.
  • Plugins – Drop in extra functionality, like emojii or typing indicators with plugins.
  • Building a Plugin – If what you need doesn’t exist, it’s easy to build yourself. Share it with us!
  • PubNub Functions – ChatEngine uses PubNub functions as a server component and details about that can be found here.
  • PubNub Channel Topology – Describes what PubNub channels ChatEngine is using under the hood.

Plugins

Image Uploads

Uses UploadCare service to upload images and render them in chats.

Markdown Support

Render Markdown in NSAttributedString when receiving messages.

Mute Users

Allows the current user to stop receiving events from other users.

Online User Search

A simple way to search through the list of users online in the chat.

Typing Indicator

Provides convenience methods that fire when a user starts or stops typing.

Unread Messages

Allows you to mark a chat as being in the background and increments a counter as events are sent to it.

Emoji Support

Uses images as fallback for devices that might not yet support 💩.

Event Status and Read Receipts

Emits additional events when someone reads a receives and/or reads a message.

Push Notifications

Gravatar Support

Uses Gravatar service to create an avatar based on user state information.

Random Usernames

A plugin that gives every use a random username combining a color and an animal.

Development

Setting up environment

It is required to install Xcode and CocoaPods on machine which will be used for application development.
Perform following steps to complete environment preparation:

  1. Install Xcode from AppStore,
  2. After installation will be completed, launch Xcode and follow instruction to install command-line utilities,
  3. Install CocoaPods by running following command from Terminal:
    sudo gem install cocoapods

After completion of these steps you can start building your application.

Running Tests

You should complete environment setup before trying to build and run tests.
At this moment there is 1198 tests in total (80 integration and 1118 unit tests). To run whole
tests suite it will require ~11 minutes.

Xcode project for tests contains various build configurations, where particular type of tests can be chosen:
unit, integration, unit with code coverage, integration with code coverage and all tests with code coverage.

To be able to run tests, follow next instruction:

  1. Clone repository:
    git clone [email protected]:pubnub/chat-engine-apple.git
  2. Navigate to Tests project directory:
    cd <path to clone location>/chat-engine-apple/Tests
  3. Install required dependencies (list of dependencies can be seen in Podfile):
    pod install
  4. After dependencies will be installed you should open project using ChatEngine Tests.xcworkspace file.
  5. At top left of opened window you should be able to find drop down list with following targets:
    • [Test] Code Coverage (Full)
    • [Test] Code Coverage (Integration)
    • [Test] Code Coverage (Unit)
    • [Test] iOS Integration
    • [Test] iOS Unit
  6. After desired target has been chosen, ensure what iPhone simulator (with blue background) is chosen for
    tests deployment.
  7. Hit shortcut Cmd+U to launch test suite.

Migration from 0.9.2 to 0.9.3

Events handler signature has been changed for better Swift support. From now on all events handler will
receive only instance of CENEmittedEvent type.

Here is how handler looks like now:

self.client.me.direct.on(@"$.invite", ^(CENEmittedEvent *event) {
    NSDictionary *payload = ((NSDictionary *)event.data)[CENEventData.data];
    CENUser *sender = payload[CENEventData.sender];

    CENChat *secretChat = self.client.Chat().name(payload[@"channel"]).create();
});

Support

  • If you need help, have a general question a feature request or to file a bug, contact [email protected]

Latest podspec

{
    "name": "CENChatEngine",
    "version": "0.9.3",
    "summary": "Framework for building chat applications.",
    "homepage": "https://github.com/pubnub/chat-engine-apple",
    "authors": {
        "PubNub, Inc.": "[email protected]"
    },
    "social_media_url": "https://twitter.com/pubnub",
    "source": {
        "git": "https://github.com/pubnub/chat-engine-apple.git",
        "tag": "v0.9.3"
    },
    "platforms": {
        "ios": "9.0",
        "osx": "10.11",
        "tvos": "9.0"
    },
    "requires_arc": true,
    "dependencies": {
        "PubNub": []
    },
    "default_subspecs": "BuilderInterfaceOn",
    "license": {
        "type": "MIT",
        "text": "            PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworksn            Copyright (c) 2018 PubNub Inc.n            http://www.pubnub.com/n            http://www.pubnub.com/termsnn            Permission is hereby granted, free of charge, to any person obtaining a copyn            of this software and associated documentation files (the "Software"), to dealn            in the Software without restriction, including without limitation the rightsn            to use, copy, modify, merge, publish, distribute, sublicense, and/or selln            copies of the Software, and to permit persons to whom the Software isn            furnished to do so, subject to the following conditions:nn            The above copyright notice and this permission notice shall be included inn            all copies or substantial portions of the Software.nn            THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORn            IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,n            FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEn            AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERn            LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,n            OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS INn            THE SOFTWARE.nn            PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworksn            Copyright (c) 2014 PubNub Inc.n            http://www.pubnub.com/n            http://www.pubnub.com/termsn"
    },
    "subspecs": [
        {
            "name": "Core",
            "source_files": [
                "ChatEngine/{Core,Data,Misc,Network,Plugin}/**/*",
                "ChatEngine/ChatEngine.h"
            ],
            "private_header_files": [
                "ChatEngine/Core/{Emitter,Publish,Search,Session}/*.h",
                "ChatEngine/Data/Managers/*.h",
                "ChatEngine/**/*Private.h",
                "ChatEngine/Misc/{CENDefines,CENConstants,CENPrivateStructures}.h",
                "ChatEngine/Misc/Helpers/{CENDictionary}.h",
                "ChatEngine/Network/**/*.h",
                "ChatEngine/Plugin/CEPPrivateStructures.h"
            ],
            "pod_target_xcconfig": {
                "APPLICATION_EXTENSION_API_ONLY": "NO"
            }
        },
        {
            "name": "BuilderInterfaceOn",
            "dependencies": {
                "CENChatEngine/Core": []
            },
            "xcconfig": {
                "GCC_PREPROCESSOR_DEFINITIONS": "CHATENGINE_USE_BUILDER_INTERFACE=1"
            },
            "pod_target_xcconfig": {
                "APPLICATION_EXTENSION_API_ONLY": "NO",
                "GCC_PREPROCESSOR_DEFINITIONS": "CHATENGINE_USE_BUILDER_INTERFACE=1"
            }
        },
        {
            "name": "BuilderInterfaceOff",
            "dependencies": {
                "CENChatEngine/Core": []
            },
            "xcconfig": {
                "GCC_PREPROCESSOR_DEFINITIONS": "CHATENGINE_USE_BUILDER_INTERFACE=0"
            },
            "pod_target_xcconfig": {
                "APPLICATION_EXTENSION_API_ONLY": "NO",
                "GCC_PREPROCESSOR_DEFINITIONS": "CHATENGINE_USE_BUILDER_INTERFACE=0"
            }
        },
        {
            "name": "Plugin",
            "pod_target_xcconfig": {
                "APPLICATION_EXTENSION_API_ONLY": "NO"
            },
            "subspecs": [
                {
                    "name": "EventStatus",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENEventStatus/**/*"
                },
                {
                    "name": "Uploadcare",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENUploadcare/**/*",
                    "private_header_files": [
                        "Plugins/CENUploadcare/CENUploadcareMiddleware+Private.h"
                    ]
                },
                {
                    "name": "OpenGraph",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENOpenGraph/**/*"
                },
                {
                    "name": "Muter",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENMuter/**/*"
                },
                {
                    "name": "Emoji",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENEmoji/**/*",
                    "private_header_files": [
                        "Plugins/CENEmoji/CENEmojiMiddleware+Private.h"
                    ]
                },
                {
                    "name": "TypingIndicator",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENTypingIndicator/**/*"
                },
                {
                    "name": "RandomUsername",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENRandomUsername/**/*"
                },
                {
                    "name": "UnreadMessages",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENUnreadMessages/**/*"
                },
                {
                    "name": "Markdown",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENMarkdown/**/*",
                    "private_header_files": [
                        "Plugins/CENMarkdown/CENMarkdownParser+Private.h"
                    ]
                },
                {
                    "name": "Gravatar",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENGravatar/**/*"
                },
                {
                    "name": "OnlineUserSearch",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENOnlineUserSearch/**/*"
                },
                {
                    "name": "PushNotifications",
                    "dependencies": {
                        "CENChatEngine/Core": []
                    },
                    "source_files": "Plugins/CENPushNotifications/**/*"
                }
            ]
        }
    ]
}

Pin It on Pinterest

Share This