Presence

The Presence object exposes the following public properties:

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

When a channel is attached, the Ably service immediately synchronizes 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 synchronization 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 callback can optionally be passed in to be notified of success or failure to enter.

enter(callback(ErrorInfo err))

Enter a presence channel without any data. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

enter(Object data, callback(ErrorInfo err))

Enter a presence channel and provide data that is associated with the current present member. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

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 callback can optionally be passed in to be notified of success or failure to leave.

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 callback can optionally be passed in to be notified of success or failure to update the member data.

update(Object data, callback(ErrorInfo err))

Update the current member’s data and broadcast an update event to all subscribers. data may be null. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling update will implicitly attach the channel.

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 synchronized, so if the synchronization is not yet complete following a channel being attached, this method will wait until the presence member set is synchronized.

When a channel is attached, the Ably service immediately synchronizes 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 synchronization process down.

When a channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling get will implicitly attach the channel.

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“:/docs/api/realtime-sdk/connection#id string

waitForSync

true A boolean value that by default waits for the initial presence synchronization following channel attachment to complete before returning the members present. When false, the current list of members is returned without waiting for a complete synchronization

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.

Parameters

action

The presence action event to subscribe toType: String

listener

is a function of the form function(message) to be called for each matching presence message event

Considerations

• If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling subscribe will implicitly attach the channel. However, regardless of the implicit attach outcome, the listener will still be registered
• If subscribe is called more than once with the same listener, then duplicates will be registered. For example, if you subscribe twice with the same listener and a presence message is later received, the same listener will be invoked twice
• The registered listener remains active on the presence channel regardless of the underlying channel state. For example, if you call subscribe when the underlying channel is attached and it later becomes detached or even failed, when the channel is reattached and a presence message is received, the listeners originally registered will still be invoked. Listeners are only removed when calling unsubscribe or when the underlying channel is released using the Realtime.channels.release(name) method
• If an exception is thrown in the subscribe listener and bubbles up to the event emitter, it will be caught and logged at error level, so as not to affect other listeners for the same event

There are six overloaded versions of this method:

unsubscribe(String action, listener)

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

unsubscribe(listener)

Unsubscribe the given listener from 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 unsubscribe fromType: String

actions

An array of actions to unsubscribe fromType: String[]

listener

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 callback can optionally be passed in to be notified of success or failure to enter.

enterClient(String clientId, callback(ErrorInfo err))

Enter a presence channel on behalf of the provided clientId without any data. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

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

Enter a presence channel and provide data that is associated with the current present member. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

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 callback can optionally be passed in to be notified of success or failure to leave.

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 callback can optionally be passed in to be notified of success or failure to update the member data.

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. If the channel is initialized (i.e. no attempt to attach has yet been made for this channel), then calling enter will implicitly attach the channel.

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 providedString, StringBuffer, JSON Object

extras

Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the push, ref and privileged objects.Type: JSON Object

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

JavaScript
JavaScript v2.6

var PresenceActions = [
  'absent', // (reserved for internal use)
  'present',
  'enter',
  'leave',
  'update'
]

Copy
Copied!

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

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.

JavaScriptNode.jsJavaAndroidC# .NETRubyPythonPHPObjective-CSwiftGo
JavaScript v2.6

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());
  });
});

Copy
Copied!