Satori

Subscription

Subscription

new Subscription(subscriptionId, _opts)

Subscription represents a subscription to a channel. Its functions manage the subscription state and respond to subscription events.

Use Subscription functions to specify code that executes when an event occurs or when the subscription enters a specific state.

For example, use Subscription.on("rtm/subscription/data", fn()) to specify a function that's executed when the subscription receives a message. Use Subscription.on("enter-subscribed", fn()) to specify a function that's executed when the subscription is active.

When your application receives a channel message, the data event occurs and the message is passed as a Protocol Data Unit (PDU) to the function specified for Subscription.on("rtm/subscription/data", fn()).

The format of the PDU in messages you receive is the same as the subprotocol you specify in the client constructor RTM. RTM automatically converts messages before it sends them.

You can also specify an event handler function that executes when the subscription enters or leaves subscribed state. For example, to specify an event handler for the enter-subscribed event, use Subscription.on("enter-subscribed", fn()}.

Note: When the connection from the client to RTM drops, all subscriptions are unsubscribed and then resubscribed when the connection is restored.

Source:
Parameters:
Name Type Description
subscriptionId string

unique identifier for the subscription. If you don't use the filter parameter to specify a streamview, subscriptionId is treated as a channel name.
_opts Object

additional subscription options

Name Type Attributes Default Description
mode boolean <optional>

subscription mode
bodyOpts object <optional>
 {}

Additional options for the subscription. These options are sent to RTM in the body element of the PDU that represents the subscribe request. The keys in bodyOpts are documented in the parameter list for RTM.subscribe()
Throws:

indicates that mandatory parameters are missing or invalid.

Type
TypeError
Example
// Creates an RTM client
var rtm = new RTM('YOUR_ENDPOINT', 'YOUR_APPKEY');
// create a new subscription to the channel named 'your-channel'
var subscription = rtm.subscribe('your-channel');

subscription.on('rtm/subscription/data', function (pdu) {
    pdu.body.messages.forEach(console.log);
});
subscription.on('enter-subscribed', function () {
    console.log('Subscribed!');
});
subscription.on('data', function (pdu) {
    if (pdu.action.endWith('/error')) {
        rtm.restart();
    }
});

Extends

Methods

fire(name, …args) → {void}

Executes all handlers attached for the specified event type.

The event specified in name is an RTM or Subscription event that has an attached event handler function (see the on() function).

Inherited From:
Source:
Parameters:
Name Type Attributes Description
name string

name of an event that has attached handlers
args Object <repeatable>

event arguments.
Returns:
Type:
void

off(name, fn) → {void}

Removes an event handler.

The event specified in name is an RTM or Subscription event that has an attached event handler function (see the on() function).

The Protocol Data Unit (PDU) for the event is passed to the fn function parameter.

Inherited From:
Source:
Parameters:
Name Type Description
name string

event name
fn function

event handler function
Returns:
Type:
void

on(name, fn) → {void}

Attaches an event handler function for the event specified in name.

The event is usually related to a client or subscription state. It may also be an event that occurs when the client or subscription receives information from RTM. For example, the the following are RTM client events:

  • data: The client received a PDU from RTM.
  • enter-connected: The client is now connected to RTM.
A possible event for a Subscription is enter-subscribed.

The fn parameter is a function that's invoked when the event occurs. The PDU for the event is passed to this function.

Inherited From:
Source:
Parameters:
Name Type Description
name string

event name
fn function

event handler function
Returns:
Type:
void