Ably iOS client library
An iOS client library for ably.io, the realtime messaging service, written in Objective-C.
Visit https://www.ably.io/documentation for a complete API reference and more examples.
You can install Ably for iOS through CocoaPods, Carthage or manually.
Installing through CocoaPods (recommended)
Add this line to your application's Podfile:
# For Xcode 7.3 and newer
pod 'AblyRealtime', '~> 0.8'
# For Xcode 7.2 and older
pod 'AblyRealtime', :git => 'https://github.com/ably/ably-ios.git', :tag => '0.8-swift2.1'
And then install the dependency:
$ pod install
Installing through Carthage
Add this line to your application's Cartfile:
# For Xcode 7.3 and newer
github "ably/ably-ios" ~> 0.8
# For Xcode 7.2 and older
github "ably/ably-ios" == "0.8-swift2.1"
And then run carthage update to build the framework and drag the built Ably.framework into your Xcode project.
- Get the code from GitHub from the release page, or clone it to get the latest, unstable and possibly underdocumented version:
git clone git@github.com:ably/ably-ios.git - Drag the directory
ably-ios/ably-iosinto your project as a group. - Ably depends on SocketRocket 0.5.1; get it from the releases page and follow its manual installation instructions.
- Ably also depends on msgpack 0.1.8; get it from the releases page and link it into your project.
All examples assume a client has been created as follows:
Swift
// basic auth with an API key
let client = ARTRealtime(key: "xxxx:xxxx")
// using token auth
let client = ARTRealtime(token: "xxxx")Objective-C
// basic auth with an API key
ARTRealtime* client = [[ARTRealtime alloc] initWithKey:@"xxxx:xxxx"];
// using token auth
ARTRealtime* client = [[ARTRealtime alloc] initWithToken:@"xxxx"];Instantiating ARTRealtime starts a connection by default. You can catch connection success or error by listening to the connection's state changes:
Swift
client.connection.on { stateChange in
let stateChange = stateChange!
switch stateChange.current {
case .Connected:
print("connected!")
case .Failed:
print("failed! \(stateChange.reason)")
default:
break
}
}Objective-C
[client.connection on:^(ARTConnectionStateChange *stateChange) {
switch (stateChange.current) {
case ARTRealtimeConnected:
NSLog(@"connected!");
break;
case ARTRealtimeFailed:
NSLog(@"failed! %@", stateChange.reason);
break;
default:
break;
}
}];You can also connect manually by setting the appropiate option.
Swift
let options = ARTClientOptions(key: "xxxx:xxxx")
options.autoConnect = false
let client = ARTRealtime(options: options)
client.connection.connect()Objective-C
ARTClientOptions *options = [[ARTClientOptions alloc] initWithKey:@"xxxx:xxxx"];
options.autoConnect = false;
ARTRealtime *client = [[ARTRealtime alloc] initWithOptions:options];
[client.connection connect];Given:
Swift
let channel = client.channels.get("test")Objective-C
ARTRealtimeChannel *channel = [client.channels get:@"test"];Subscribe to all events:
Swift
channel.subscribe { message in
print(message.name)
print(message.data)
}Objective-C
[channel subscribe:^(ARTMessage *message) {
NSLog(@"%@", message.name);
NSLog(@"%@", message.data);
}];Only certain events:
Swift
channel.subscribe("myEvent") { message in
print(message.name)
print(message.data)
}Objective-C
[channel subscribe:@"myEvent" callback:^(ARTMessage *message) {
NSLog(@"%@", message.name);
NSLog(@"%@", message.data);
}];Swift
channel.publish("greeting", data: "Hello World!")Objective-C
[channel publish:@"greeting" data:@"Hello World!"];Swift
channel.history { messagesPage, error in
let messagesPage = messagesPage!
print(messagesPage.items)
print(messagesPage.items.first)
print((messagesPage.items.first as? ARTMessage)?.data) // payload for the message
print(messagesPage.items.count) // number of messages in the current page of history
messagesPage.next { nextPage, error in
// retrieved the next page in nextPage
}
print(messagesPage.hasNext) // true, there are more pages
}Objective-C
[channel history:^(ARTPaginatedResult<ARTMessage *> *messagesPage, ARTErrorInfo *error) {
NSLog(@"%@", messagesPage.items);
NSLog(@"%@", messagesPage.items.firstObject);
NSLog(@"%@", messagesPage.items.firstObject.data); // payload for the message
NSLog(@"%lu", (unsigned long)[messagesPage.items count]); // number of messages in the current page of history
[messagesPage next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
// retrieved the next page in nextPage
}];
NSLog(@"%d", messagesPage.hasNext); // true, there are more pages
}];Swift
let channel = client.channels.get("test")
channel.presence.enter("john.doe") { errorInfo in
channel.presence.get { members, errorInfo in
// members is the array of members present
}
}Objective-C
[channel.presence enter:@"john.doe" callback:^(ARTErrorInfo *errorInfo) {
[channel.presence get:^(ARTPaginatedResult<ARTPresenceMessage *> *result, ARTErrorInfo *error) {
// members is the array of members present
}];
}];Swift
channel.presence.history { presencePage, error in
let presencePage = presencePage!
if let first = presencePage.items.first as? ARTPresenceMessage {
print(first.action) // Any of .Enter, .Update or .Leave
print(first.clientId) // client ID of member
print(first.data) // optional data payload of member
presencePage.next { nextPage, error in
// retrieved the next page in nextPage
}
}
}Objective-C
[channel.presence history:^(ARTPaginatedResult<ARTPresenceMessage *> *presencePage, ARTErrorInfo *error) {
ARTPresenceMessage *first = (ARTPresenceMessage *)presencePage.items.firstObject;
NSLog(@"%lu", (unsigned long)first.action); // Any of ARTPresenceEnter, ARTPresenceUpdate or ARTPresenceLeave
NSLog(@"%@", first.clientId); // client ID of member
NSLog(@"%@", first.data); // optional data payload of member
[presencePage next:^(ARTPaginatedResult<ARTPresenceMessage *> *nextPage, ARTErrorInfo *error) {
// retrieved the next page in nextPage
}];
}];### Introduction
All examples assume a client and/or channel has been created as follows:
Swift
let client = ARTRest(key: "xxxx:xxxx")
let channel = client.channels.get("test")Objective-C
ARTRest *client = [[ARTRest alloc] initWithKey:@"xxxx:xxxx"];
ARTRestChannel *channel = [client.channels get:@"test"];Swift
channel.publish("myEvent", data: "Hello!")Objective-C
[channel publish:@"myEvent" data:@"Hello!"];Swift
channel.history { messagesPage, error in
let messagesPage = messagesPage!
print(messagesPage.items.first)
print((messagesPage.items.first as? ARTMessage)?.data) // payload for the message
messagesPage.next { nextPage, error in
// retrieved the next page in nextPage
}
print(messagesPage.hasNext) // true, there are more pages
}Objective-C
[channel history:^(ARTPaginatedResult<ARTMessage *> *messagesPage, ARTErrorInfo *error) {
NSLog(@"%@", messagesPage.items.firstObject);
NSLog(@"%@", messagesPage.items.firstObject.data); // payload for the message
NSLog(@"%lu", (unsigned long)[messagesPage.items count]); // number of messages in the current page of history
[messagesPage next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
// retrieved the next page in nextPage
}];
NSLog(@"%d", messagesPage.hasNext); // true, there are more pages
}];Swift
channel.presence.get { membersPage, error in
let membersPage = membersPage!
print(membersPage.items.first)
print((membersPage.items.first as? ARTPresenceMessage)?.data) // payload for the message
membersPage.next { nextPage, error in
// retrieved the next page in nextPage
}
print(membersPage.hasNext) // true, there are more pages
}Objective-C
[channel.presence get:^(ARTPaginatedResult<ARTPresenceMessage *> *membersPage, ARTErrorInfo *error) {
NSLog(@"%@", membersPage.items.firstObject);
NSLog(@"%@", membersPage.items.firstObject.data); // payload for the message
[membersPage next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
// retrieved the next page in nextPage
}];
NSLog(@"%d", membersPage.hasNext); // true, there are more pages
}];Swift
channel.presence.history { presencePage, error in
let presencePage = presencePage!
if let first = presencePage.items.first as? ARTPresenceMessage {
print(first.clientId) // client ID of member
presencePage.next { nextPage, error in
// retrieved the next page in nextPage
}
}
}Objective-C
[channel.presence history:^(ARTPaginatedResult<ARTPresenceMessage *> *presencePage, ARTErrorInfo *error) {
ARTPresenceMessage *first = (ARTPresenceMessage *)presencePage.items.firstObject;
NSLog(@"%@", first.clientId); // client ID of member
NSLog(@"%@", first.data); // optional data payload of member
[presencePage next:^(ARTPaginatedResult<ARTPresenceMessage *> *nextPage, ARTErrorInfo *error) {
// retrieved the next page in nextPage
}];
}];Swift
client.auth.requestToken(nil, withOptions: nil) { tokenDetails, error in
let tokenDetails = tokenDetails!
print(tokenDetails.token) // "xVLyHw.CLchevH3hF....MDh9ZC_Q"
let client = ARTRest(token: tokenDetails.token)
}Objective-C
[client.auth requestToken:nil withOptions:nil callback:^(ARTTokenDetails *tokenDetails, NSError *error) {
NSLog(@"%@", tokenDetails.token); // "xVLyHw.CLchevH3hF....MDh9ZC_Q"
ARTRest *client = [[ARTRest alloc] initWithToken:tokenDetails.token];
}];### Fetching your application's stats
Swift
client.stats { statsPage, error in
let statsPage = statsPage!
print(statsPage.items.first)
statsPage.next { nextPage, error in
// retrieved the next page in nextPage
}
}Objective-C
[client stats:^(ARTPaginatedResult<ARTStats *> *statsPage, ARTErrorInfo *error) {
NSLog(@"%@", statsPage.items.firstObject);
[statsPage next:^(ARTPaginatedResult<ARTStats *> *nextPage, ARTErrorInfo *error) {
// retrieved the next page in nextPage
}];
}];Swift
client.time { time, error in
print(time) // 2016-02-09 03:59:24 +0000
}Objective-C
[client time:^(NSDate *time, NSError *error) {
NSLog(@"%@", time); // 2016-02-09 03:59:24 +0000
}];Please visit http://support.ably.io/ for access to our knowledgebase and to ask for any assistance.
You can also view the community reported Github issues.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Ensure you have added suitable tests and the test suite is passing
- Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Copyright (c) 2015 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.