ORTC Module

Description

This module allows to integrate ORTC service with Titanium Mobile applications.

The ORTC (Open Real-Time Connectivity) was developed to add a layer of abstraction to real-time full-duplex web communications platforms by making real-time web applications independent of those platforms.

ORTC provides a standard software API (Application Programming Interface) for sending and receiving data in real-time over the web.

Requirements: Android <= 2.3.3

Installation

For information how to use Titanium Modules, please follow the guide here.

Accessing the ORTC Module

To access this module from JavaScript, you would do the following:

var ORTC = require("co.realtime.ortc");

The ORTC variable is a reference to the Module object.

Reference

Properties

clusterUrl

The cluster server URL

Example:

ORTC.clusterUrl = 'http://ortc-developers.realtime.co/server/2.1';

url

The server URL

Example:

ORTC.url = 'http://ortc-developers-euwest1-S0001.realtime.co/server/2.1';

connectionMetadata

The client connection metadata

Example:

ORTC.connectionMetadata = 'Titanium Client';

announcementSubchannel

The client announcement subchannel

Example:

ORTC.announcementSubchannel = 'announcementSubchannel';

sessionId (readonly)

The client session identifier

Example:

alert(ORTC.sessionId);

Events

onException

Event fired whenever exception occurs. The event parameter passed on the callback function has defined following property: - info [string]: description of the exception

Example:

ORTC.addEventListener('onException', function(e) {  
    alert('Exception: '+e.info);
});

onConnected

Event fired whenever module connects.

Example:

ORTC.addEventListener('onConnected', function(e) {
    alert('Connected');
});

onDisconnected

Event fired whenever module disconnects.

Example:

ORTC.addEventListener('onDisconnected', function(e) {
    alert('Disconnected');
});

onReconnected

Event fired whenever module reconnects.

Example:

ORTC.addEventListener('onReconnected', function(e) {
    alert('Reconnected');
});

onReconnecting

Event fired whenever module connects.

Example:

ORTC.addEventListener('onReconnecting', function(e) {
    alert('Reconnecting');
});

onSubscribed

Event fired when module subscribes to a channel. The event parameter passed on the callback function has defined following property: - channel [string]: the channel name

Example:

ORTC.addEventListener('onSubscribed', function(e) { 
    alert('Subscribed to channel: '+e.channel);
});

onUnsubscribed

Event fired when module unsubscribes from a channel. The event parameter passed on the callback function has defined following property: - channel [string]: the channel name

Example:

ORTC.addEventListener('onUnsubscribed', function(e) { 
    alert('Unsubscribed from: '+e.channel);
});

onMessage

Event fired when module receives a message on the subscribed channel. The event parameter passed on the callback function has defined following properties: - channel [string]: the channel name - message [string]: the message

Example:

ORTC.addEventListener('onMessage', function(e) {
    alert('(Channel: '+e.channel+') Message received: '+e.message);
});

onPresence

Event fired as a response for presence request. The event parameter passed on the callback function has defined following properties: - channel [string]: the channel name - result [string]: JSON string containing the presence response - error [string]: the error description, if occurs, otherwise empty string

Example:

ORTC.addEventListener('onPresence', function(e) {
    if (e.error != ""){
        alert('(Channel: '+e.channel+') Presence error: ' + e.error);
    } else {
        alert('(Channel: '+e.channel+') Presence: '+e.result);
    }
});

Methods

connect

Connects the client using the supplied application key and authentication token. Parameters: - application_key [string]: Your ORTC application key. - authentication_token [string]: - Your ORTC authentication token (this parameter is optional).

Example:

ORTC.connect('yourApplicationKey');
or
ORTC.connect('yourApplicationKey', 'yourAuthenticationToken');

disconnect

Disconnects the client.

Example:

ORTC.disconnect();

subscribe

Subscribes to the supplied channel to receive messages sent to it. Parameters: - channel [string]: The channel name. - subscribe_on_reconnect [bool] -Indicates whether the client should subscribe to the channel when reconnected (if it was previously subscribed when connected).

Example:

ORTC.subscribe('yellow', true);

unsubscribe

Unsubscribes from the supplied channel to stop receiving messages sent to it. Parameter: - channel [string]: The channel name.

Example:

ORTC.unsubscribe('yellow');

send

Sends the supplied message to the supplied channel. Parameters: - channel [string]: The channel name. - message [string]: The message to send.

Example:

ORTC.send('yellow', 'This is the message');

isSubscribed

Returns boolean value which indicates whether the client is subscribed to the supplied channel. Parameter: - channel [string]: The channel name.

Example:

alert(ORTC.isSubscribed('yellow'));

isConnected

Returns boolean value which indicates whether the client is connected.

Example:

alert(ORTC.isConnected());

presence

Gets a dictionary indicating the subscriptions number in the specified channel and if active the first 100 unique metadata. Parameter: - channel [string]: The channel name with presence data active.

Example:

ORTC.presence('yellow');

Usage

Please see the examples files included in the directory 'example'

Author

ortc@realtime.co