Getting the framework
The Kwwika API for iOS is supplied as a framework so that adding it to your application is as easy as possible. The iOS framework will be available after you've setup your Kwwika account.
Getting Started
Connecting to the service
Connecting to the service is a single call:
#import <Kwwika/Kwwika.h>
id<KwwikaConnection> connection = [KwwikaService createKwwikaConnectionWithAPIKey:@"user" domain:@"mydomain"];
Subscribing to data
Once you have connected to Kwwika you can subscribe to data. We use something called a topic to identify information. For instance our example chat application uses the /KWWIKA/EXAMPLES/CHAT topic. When you subscribe to a topic you also pass a listener that defines two methods. updateForTopic is called when information becomes available for the topic you've subscribed to, and errorForTopic is called if there is a problem with your subscription such as the topic does not exist within Kwwika.
The following example shows an empty listener implementation:
#import <Kwwika/Kwwika.h>
@interface MyKwwikaSubscriptionListener : NSObject<KwwikaSubscriptionListener> {
}
@implementation MyKwwikaSubscriptionListener
-(void)errorForTopic:(NSString *)topic withError:(Kwwika_TopicError)error
{
}
-(void)updateForTopic:(NSString *)topic updatedFieldValues:(NSDictionary *)fieldValues isImage:(BOOL)image
{
}
@end
To subscribe to a subject, we just call subscribeToTopic:subscriptionListener on the KwwikaConnection object:
id<KwwikaConnection> connection;
id<KwwikaSubscriptionListener> mySubscriptionListener;
[connection subscribeToSubject:@"/KWWIKA/EXAMPLES/CHAT" subscriptionListener:mySubscriptionListener];
Publishing Data
We've tried to keep publishing data as simple as possible. All you need to do is specify the topic you want to publish to, the names and values that you want to publish, and provide an listener that will be informed about whether your attempt to publish succeeded or not.
id<KwwikaConnection> connection;
id<KwwikaCommandListener> myCommandListener;
// Create a dictionary of values to contribute
NSMutableDictionary *dict = [[NSMutableDictionary alloc] init];
[dict setObject:@"phil" forKey:@"name"];
[dict setObject:@"Hello from the iOS Kwwika API!" forKey:@"text"];
[connection publishToSubject:@"/KWWIKA/EXAMPLES/CHAT" fieldValues:dict commandListener:myCommandListener];
Maintaining a connection
You don't need to worry about maintaining a connection when network conditions change: the Kwwika API automatically chooses the best transport (wifi or 3G/edge/2G), switching between them if you go out of range of a wireless network. You can choose to receive notifications of the state of the connection by passing in a KwwikaConnectionListener implementation into alternate factory methods on the KwwikaService object.
Handling Multitasking
iOS devices running iOS >= 4.0 support multitasking and adding support for it in your application is easy. In order to conserve battery life (and valuable data allowances), you can tell the Kwwika API to close down its network connections whilst your application is frozen. When your app resumes, you can tell the Kwwika API to re-establish network connections.
Further Documentation
We're currently working on completely documenting the API, explaining the nuances of network connectivity and other iOS related topics. More extensive documentation will be available in the iOS framework download.
