Realtime

This section explains how to user the realtime functionality from your iOS code. It only requires the basic configuration settings in your AppDelegate (set your project and environment correctly).

Enabling the realtime

If you want to use the real-time API first of all you nead to enable it just calling this method

[Backbeam enableRealTime];

This keeps a connection between the application and the server. At any moment you can also disable the real-time connection calling:

[Backbeam disableRealTime];

Subscribing to real time events You can listen to events generated by other devices (or the server). In order to support subscribing only to certain events all real-time events have a name. Events have also a collection of key-value pairs with more information about that event. This is a sample code that listens to events named chat-room and prints the value of their text parameter.

- (void)viewDidLoad
{
    [super viewDidLoad];

    [Backbeam subscribeToRealTimeEvents:@"chat-room" delegate:self];
    [Backbeam enableRealTime];
}

- (void)realTimeEventReceived:(NSString*)event message:(NSDictionary*)message {
    NSLog(@"received event %@ %@", event, message);
}

If you are no longer interested in some kind of events you should unsubscribe from those events. It is a good practique to do so because this way the SDK stops having a reference to the listener. Otherwise you could start leaking memory. And it also helps to reduce the bandwidth usage because the device will no longer receive those type of events.

[Backbeam unsubscribeFromRealTimeEvents:@"chat-room" delegate:self];

If the realtime connection is broken and it reconnects the SDK will re-subscribe automatically to the previously subscribed events so you don't have to re-subscribe programatically.

Sending real time events

Sending events is also very easy. Just indicate the event name and the data you want to send to the devices subscribed.

[Backbeam sendRealTimeEvent:@"chat-room" message:@{@"text":@"some text"}];

Listening to real time connection changes

You may need to indicate the user whether the realtime connection is available or not. For example you could present the user an activity indicator while the connection is being established.

- (void)viewDidLoad {
    [super viewDidLoad];
    [Backbeam subscribeToRealTimeConnectionEvents:self];
}

- (void)realTimeConnected {
    NSLog(@"connected!");
}

- (void)realTimeConnecting {
    NSLog(@"connecting...");
}

- (void)realTimeDisconnected {
    NSLog(@"disconnected!");
}

- (void)realTimeConnectionFailed:(NSError*)error {
    NSLog(@"connection failed %@", error);
}

Other realtime methods

The Backbeam class has other interesting methods realted to the realtime functionality:

• subscribedRealTimeEvents returns an array of NSString objects indicating all the event names that have at least one subscriber
• unsubscribeAllRealTimeEventDelegates unsubscribes all delegates from the realtime events
• unsubscribeAllRealTimeConnectionDelegates unsubscribes all delegates from realtime connection events
• isRealTimeEnabled returns YES if the realtime API is enabled
• isRealTimeConnected returns YES if the realtime socket is connected