API v 0.8
JavaScript

Presence

The Presence object exposes the following public properties:

A boolean field indicating whether the presence member set is synchronised with server after a channel attach.

When a channel is attached, the Ably service immediately synchronises the presence member set with the client. Typically this process completes in milliseconds, however when the presence member set is very large, bandwidth constraints may slow this synchronisation process down.

In order to enter and be present on a channel, the client must be identified by having a client ID, have permission to be present, and be attached to the channel. For simplicity, the library will implicitly attach to a channel when entering. Entering when already entered is treated as an update.

There are two overloaded versions of this method. With both versions, a <span lang=“default”>callback can optionally be passed in to be notified of success or failure to enter.</span>

enter(callback(ErrorInfo err))

Enter a presence channel without any data.

enter(Object data, callback(ErrorInfo err))

Enter a presence channel and provide data that is associated with the current present member.

Parameters

data
data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.Type: Object
callback
is a function of the form function(err) which is called upon completion

In order to leave the presence set of a channel, the client must have already entered and been present.

There are two overloaded versions of this method. With both versions, a <span lang=“default”>callback can optionally be passed in to be notified of success or failure to leave.</span>

leave(callback(ErrorInfo err))

Leave a presence channel without emitting any data.

leave(Object data, callback(ErrorInfo err))

Leave a presence channel and emit data that is associated with the current leaving member.

Parameters

data
data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.Type: Object
callback
is a function of the form function(err) which is called upon completion

Clients can update their member data on the channel which will trigger a broadcast of this update to all presence subscribers. The pre-requisites for update are the same as for enter. If an attempt to update is made before the client has entered the channel, the update is treated as an enter.

A <span lang=“default”>callback can optionally be passed in to be notified of success or failure to update the member data.</span>

update(Object data, callback(ErrorInfo err))

Update the current member’s data and broadcast an update event to all subscribers. data may be null.

Parameters

data
data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.Type: Object
callback
is a function of the form function(err) which is called upon completion

Get the current presence member set for this channel. Typically, this method returns the member set immediately as the member set is retained in memory by the client. However, by default this method will wait until the presence member set is synchronised, so if the synchronisation is not yet complete following a channel being attached, this method will wait until the presence member set is synchronised.

When a channel is attached, the Ably service immediately synchronises the presence member set with the client. Typically this process completes in milliseconds, however when the presence member set is very large, bandwidth constraints may slow this synchronisation process down.

get(Object options, callback(ErrorInfo err, PresenceMessage[] members))

Gets an array of members present on the channel as PresenceMessage objects.

options parameters

clientId
when provided, will filter array of members returned that match the provided clientId string
connectionId
when provided, will filter array of members returned that match the provided connectionId“:/api/realtime-sdk/connection#id string
waitForSync
true A boolean value that by default waits for the initial presence synchronisation following channel attachment to complete before returning the members present. When false, the current list of members is returned without waiting for a complete synchronisation

history(Object options, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))

Gets a paginated set of historical presence message events for this channel. If the channel is configured to persist messages to disk, then the presence message event history will typically be available for 24 – 72 hours. If not, presence message events are only retained in memory by the Ably service for two minutes.

Parameters

options
an optional object containing query parameters, as specified in the presence history API documentation.
callback
is a function of the form: function(err, resultPage)

Further details of the supported options params, see presence history API documentation.

There are overloaded versions of this method:

subscribe(listener(PresenceMessage))

Subscribe to presence message events on this channel. The caller supplies a listener function, which is called each time one or more presence events occurs such as a member entering or leaving a channel.

subscribe(String action, listener(PresenceMessage))

Subscribe to presence message events with a given action on this channel. The caller supplies a listener function, which is called each time one or more presence events occurs such as a member entering or leaving a channel.

subscribe(String[] actions, listener(PresenceMessage))

Subscribe a single listener to messages on this channel for multiple name values.

Parameters

action
The presence action event to subscribe toType:
actions
An array of action events to subscribe toType: String[]
listener
is a function of the form function(message) to be called for each matching presence message event

There are three overloaded versions of this method:

unsubscribe(String action, listenerCallback)

Unsubscribe to presence message events on this channel for the given action. This removes an earlier event-specific subscription.

unsubscribe(listenerCallback)

Unsubscribe to presence message events on this channel. This removes an earlier subscription.

unsubscribe()

Unsubscribes all listeners to presence message events on this channel. This removes all earlier subscriptions.

Parameters

action
The presence action event to subscribe toType:
listenerCallback
is the callback listener function that was previously subscribed

Enter this presence channel for the given clientId. This method is provided to support typically server instances that act on behalf of multiple client IDs. See Managing multiple client IDs for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an API key, or with a token bound to a wildcard client ID.

There are two overloaded versions of this method. With both versions, a <span lang=“default”>callback can optionally be passed in to be notified of success or failure to enter.</span>

enterClient(String clientId, callback(ErrorInfo err))

Enter a presence channel on behalf of the provided clientId without any data.

enterClient(String clientId, Object data, callback(ErrorInfo err))

Enter a presence channel and provide data that is associated with the current present member.

Parameters

data
data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.Type: Object
callback
is a function of the form function(err) which is called upon completion

Leave this presence channel for the given clientId. This method is provided to support typically server instances that act on behalf of multiple client IDs. See Managing multiple client IDs for more info. In order to leave the presence set of a channel, the client must have already entered and been present.

There are two overloaded versions of this method. With both versions, a <span lang=“default”>callback can optionally be passed in to be notified of success or failure to leave.</span>

leaveClient(String clientId, callback(ErrorInfo err))

Leave a presence channel on behalf of the provided clientId without emitting any data.

leaveClient(String clientId, Object data, callback(ErrorInfo err))

Leave a presence channel on behalf of the provided clientId and emit data that is associated with the current leaving member.

Parameters

data
data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.Type: Object
callback
is a function of the form function(err) which is called upon completion

Clients can update the member data on behalf of the given clientId which will trigger a broadcast of this update to all presence subscribers. This method is provided to support typically server instances that act on behalf of multiple client IDs. See Managing multiple client IDs for more info. If an attempt to update is made before the member has entered the channel, the update is treated as an enter.

A <span lang=“default”>callback can optionally be passed in to be notified of success or failure to update the member data.</span>

updateClient(String clientId, Object data, callback(ErrorInfo err))

Update the member data on behalf of the provided clientId and broadcast an update event to all subscribers. data may be null.

Parameters

data
data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null.Type: Object
callback
is a function of the form function(err) which is called upon completion

A PresenceMessage represents an individual presence update that is sent to or received from Ably.

Properties

action
the event signified by a PresenceMessage. See Presence actionType: int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }
data
The presence update payload, if provided
extras
Metadata and/or ancillary payloads, if provided. The only currently valid payload for extras is the push object.Type:
id
Unique ID assigned by Ably to this presence updateType: String
clientId
The client ID of the publisher of this presence updateType: String
connectionId
The connection ID of the publisher of this presence updateType: String
timestamp
Timestamp when the presence update was received by Ably, as milliseconds since the epoch.Type: Integer
encoding
This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payloadType: String

PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) → PresenceMessage

A static factory method to create a PresenceMessage from a deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsg
a PresenceMessage-like deserialized object.Type: Object
channelOptions
an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.Type: Object

Returns

A PresenceMessage object

PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) → PresenceMessage[]

A static factory method to create an array of PresenceMessages from an array of deserialized PresenceMessage-like object encoded using Ably’s wire protocol.

Parameters

encodedPresMsgs
an array of PresenceMessage-like deserialized objects.Type: Array
channelOptions
an optional ChannelOptions. If you have an encrypted channel, use this to allow the library can decrypt the data.Type: Object

Returns

An Array of PresenceMessage objects

A PaginatedResult is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.

Properties

items
contains the current page of results (for example an Array of Message or PresenceMessage objects for a channel history request)Type: Array <Message, Presence, Stats>

Methods

first(callback(ErrorInfo err, PaginatedResult resultPage))

Returns a new PaginatedResult for the first page of results.

Boolean hasNext()

Returns true if there are more pages available by calling next and returns false if this page is the last page available.

Boolean isLast()

Returns true if this page is the last page and returns false if there are more pages available by calling next available.

next(callback(ErrorInfo err, PaginatedResult resultPage))

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned.

JavaScript
channel.history(function(err, paginatedResult) { console.log('Page 0 item 0:' + paginatedResult.items[0].data); paginatedResult.next(function(err, nextPage) { console.log('Page 1 item 1: ' + nextPage.items[1].data); console.log('Last page?: ' + nextPage.isLast()); }); });
Copied!