TestsTested | ✓ |
LangLanguage | Obj-CObjective C |
License | Apache 2 |
ReleasedLast Release | Oct 2016 |
Maintained by Ably, Toni Cárdenas, Ricardo Pereira.
Depends on: | |
SocketRocket | = 0.5.1 |
msgpack | = 0.1.8 |
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.
git clone [email protected]:ably/ably-ios.git
ably-ios/ably-ios
into your project as a group.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
}];
}];
authCallback
A callback to call to obtain a signed token request.
ARTClientOptions
and ARTRealtime
objects can be instantiated as follow:
Swift
let clientOptions = ARTClientOptions()
clientOptions.authCallback = { params, callback in
getTokenRequestJSONFromYourServer(params) { json, error in
//handle error
let tokenParams = ARTTokenParams(clientId:json["clientId"])
let tokenRequest = ARTTokenRequest(tokenParams:tokenParams,
keyName:json["keyName"],
nonce:json["nonce"],
mac:json["mac"])
tokenRequest.clientId = json["clientId"]
tokenRequest.ttl = json["ttl"]
tokenRequest.capability = json["capability"]
tokenRequest.timestamp = NSDate(timeIntervalSince1970:(json["timestamp"] / 1000))
callback(tokenRequest, nil)
}
}
let client = ARTRealtime(options:clientOptions)
Objective-C
ARTClientOptions *clientOptions = [[ARTClientOptions alloc] init];
clientOptions.authCallback = ^(ARTTokenParams *params, void(^callback)(id<ARTTokenDetailsCompatible>, NSError*)) {
[self getTokenRequestJSONFromYourServer:params completion:^(NSDictionary *json, NSError *error) {
//handle error
ARTTokenParams *tokenParams = [[ARTTokenParams alloc] initWithClientId:json[@"clientId"]];
ARTTokenRequest *tokenRequest = [[ARTTokenRequest alloc] initWithTokenParams:tokenParams
keyName:json[@"keyName"]
nonce:json[@"nonce"]
mac:json[@"mac"]];
tokenRequest.clientId = json[@"clientId"];
tokenRequest.ttl = [json[@"ttl"] doubleValue];
tokenRequest.capability = json[@"capability"];
tokenRequest.timestamp = [NSDate dateWithTimeIntervalSince1970:[json[@"timestamp"] doubleValue] / 1000];
callback(tokenRequest, nil);
}];
};
ARTRealtime *client = [[ARTRealtime alloc] initWithOptions:clientOptions];
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];
}];
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.
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)Copyright (c) 2015 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.