Presence

Ably::Realtime::Presence Attributes

The Presence object exposes the following public attributes:

sync_complete?

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.

Methods

enter

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

Deferrable enter() -> yields

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.

Deferrable enter(Object data) -> yields

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

Returns

A Deferrable object is returned from the method.

On successfully entering the channel, the registered success blocks for the Deferrable and any block provided to the method are executed. On failure to enter, the errback callbacks of the Deferrable are called with an ErrorInfo argument describing the failure reason.

leave

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

Deferrable leave() -> yields

Leave a presence channel without emitting any data.

Deferrable leave(Object data) -> yields

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

Parameters

Returns

A Deferrable object is returned from the method.

On successfully leaving the channel, the registered success blocks for the Deferrable and any block provided to the method are executed. On failure to leave, the errback callbacks of the Deferrable are called with an ErrorInfo argument describing the failure reason.

update

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.

Deferrable update(Object data) -> yields

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

Returns

A Deferrable object is returned from the method.

On successfully updating the data, the registered success blocks for the Deferrable and any block provided to the method are executed. On failure to update, the errback callbacks of the Deferrable are called with an ErrorInfo argument describing the failure reason.

get

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.

Deferrable get(Hash options) -> yields PresenceMessage[]

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

Parameters

options parameters

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield an array of PresenceMessage objects to the current set of present members on the channel.

Failure to retrieve the current presence member set will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

history

Deferrable history(Hash options) -> yields PaginatedResult<PresenceMessage>

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

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

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield a PaginatedResult that encapsulates an array of PresenceMessage objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

Failure to retrieve the message history will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

subscribe

There are overloaded versions of this method:

subscribe → yields PresenceMessage

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

subscribe(PresenceMessage::ACTION action) → yields PresenceMessage

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

subscribe(PresenceMessage::ACTION *actions) → yields PresenceMessage

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

Parameters

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 block will still be registered
• If subscribe is called more than once with the same block, then duplicates will be registered. For example, if you subscribe twice with the same block and a presence message is later received, the same block will be invoked twice
• The registered block 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 blocks originally registered will still be invoked. Listeners are only removed when calling unsubscribe or when the underlying channel is released using the 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

unsubscribe

There are three overloaded versions of this method:

unsubscribe(PresenceMessage::ACTION action, &listener_proc)

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

unsubscribe(&listener_proc)

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

enter_client

Enter this presence channel for the given client_id. 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 block can optionally be passed in to be notified of success or failure to enter.

Deferrable enter_client(String client_id) -> yields

Enter a presence channel on behalf of the provided client_id 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.

Deferrable enter_client(String client_id, Object data) -> yields

Enter a presence channel on behalf of the provided client_id 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

Returns

A Deferrable object is returned from the method.

On successfully entering the channel, the registered success blocks for the Deferrable and any block provided to the method are executed. On failure to enter, the errback callbacks of the Deferrable are called with an ErrorInfo argument describing the failure reason.

leave_client

Leave this presence channel for the given client_id. 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 block can optionally be passed in to be notified of success or failure to leave.

Deferrable leave_client(String client_id) -> yields

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

Deferrable leave_client(String client_id, Object data) -> yields

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

Parameters

Returns

A Deferrable object is returned from the method.

On successfully leaving the channel, the registered success blocks for the Deferrable and any block provided to the method are executed. On failure to leave, the errback callbacks of the Deferrable are called with an ErrorInfo argument describing the failure reason.

update_client

Clients can update the member data on behalf of the given client_id 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 block can optionally be passed in to be notified of success or failure to update the member data.

Deferrable update_client(String client_id, Object data) -> yields

Update the member data on behalf of the provided client_id 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

Returns

A Deferrable object is returned from the method.

On successfully updating the data, the registered success blocks for the Deferrable and any block provided to the method are executed. On failure to update, the errback callbacks of the Deferrable are called with an ErrorInfo argument describing the failure reason.

Related types

Ably::Models::PresenceMessage

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

Attributes

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

Returns

A PresenceMessage object

PresenceMessage.fromEncodedArray

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

Returns

An Array of PresenceMessage objects

Ably::Models::PresenceMessage::ACTION

Ably::Models::PresenceMessage::ACTION is an enum-like value representing all the Realtime Presence states & events. ACTION can be represented interchangeably as either symbols or constants.

Symbol states

:absent  # => 0 (reserved for internal use)
:present # => 1
:enter   # => 2
:leave   # => 3
:update  # => 4

Constant states

PresenceMessage::ACTION.Absent  # => 0 (internal use)
PresenceMessage::ACTION.Present # => 1
PresenceMessage::ACTION.Enter   # => 2
PresenceMessage::ACTION.Leave   # => 3
PresenceMessage::ACTION.Update  # => 4

Example usage

# Example with symbols
presence.on(:attached) { ... }

# Example with constants
presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... }

# Interchangeable
Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true

Ably::Models::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.

Attributes

Methods

first

PaginatedResult first

Returns a new PaginatedResult for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

has_next?

Boolean has_next?

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

last?

Boolean last?

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

next

PaginatedResult next

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then is returned. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

Example

# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
  next_page = first_page.next
  puts "Page 1 item 1: #{next_page.items[1].data}"
  puts "Last page?: #{next_page.is_last?}"
end

# When using the Realtime EventMachine library
channel.history do |first_page|
  puts "Page 0 item 0: #{first_page.items[0].data}"
  if first_page.has_next?
    first_page.next do |next_page|
      puts "Page 1 item 1: #{next_page.items[1].data}"
      puts "Last page?: #{next_page.is_last?}"
    end
  end
end