Presence
Methods
get
Get the current presence member set for this channel. In the REST client library this method directly queries Ably’s REST presence API
get(Object options, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))
Gets an array of members present on the channel as PresenceMessage objects.
Parameters
- options
- an optional object containing query parameters as specified below.
- callback
- is a function of the form:
function(err, <a href="#paginated-result">PaginatedResult</a><<a href="#presence-message">PresenceMessage</a>> resultPage)
options parameters
- clientId
- when provided, will filter array of members returned that match the provided
clientIdstring - connectionId
- when provided, will filter array of members returned that match the provided
connectionId“:/docs/api/realtime-sdk/connection#id string
Callback result
On success, resultPage contains a PaginatedResult encapsulating an array of PresenceMessage objects corresponding to the current page of members currently present on the channel. PaginatedResult supports pagination using next() and first() methods.
On failure to retrieve the current presence member set, err contains an ErrorInfo object with the failure reason.
History
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)
Callback result
On success, resultPage contains a PaginatedResult encapsulating an array of PresenceMessage objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.
On failure to retrieve message history, err contains an ErrorInfo object with the failure reason.
Related types
PresenceMessage
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
String,StringBuffer,JSON Object - extras
- Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the
push,refandprivilegedobjects.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
datapayloadType:String
PresenceMessage constructors
PresenceMessage.fromEncoded
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
Presence action
Presence action is a String with a value matching any of the Realtime Presence states & events.
var PresenceActions = [
'absent', // (reserved for internal use)
'present',
'enter',
'leave',
'update'
]
CopyCopied!PaginatedResult
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
first(callback(ErrorInfo err, PaginatedResult resultPage))
Returns a new PaginatedResult for the first page of results.
hasNext
Boolean hasNext()
Returns true if there are more pages available by calling next and returns false if this page is the last page available.
isLast
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
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.
Example
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());
});
});
CopyCopied!