space namespace consists of a state object that represents the realtime status of all members in a given virtual space. This includes a list of which members are currently online or have recently left and each member’s location within the application. The position of members’ cursors are excluded from the space state due to their high frequency of updates. The UI components that members have locked are also excluded from the space state.
Space state can be subscribed to in the space namespace. Alternatively, subscription listeners can be registered for individual features, such as avatar stack events and member location updates. These individual subscription listeners are intended to provide flexibility when implementing collaborative features. Individual listeners are client-side filtered events, so irrespective of whether you choose to subscribe to the space state or individual listeners, each event only counts as a single message.
To subscribe to any events in a space, you first need to create or retrieve a space.
Create or retrieve a space
Aspace object is a reference to a single space and is uniquely identified by its unicode string name. A space is created, or an existing space is retrieved from the spaces collection using the get() method.
The following restrictions apply to space names:
- Avoid starting names with
[or: - Ensure names aren’t empty
- Exclude whitespace and wildcards, such as
* - Use the correct case, whether it be uppercase or lowercase
10100.
Enter a space
Entering a space will register a client as a member and emit anenter event to all subscribers. Use the enter() method to enter a space.
Being entered into a space is required for members to:
- Update their profile data.
- Set their location.
- Set their cursor position.
101001.
Leave a space
Leaving a space will emit aleave event to all subscribers.
The following is an example of explicitly leaving a space:
Members will implicitly leave a space after 15 seconds if they abruptly disconnect. If experiencing network disruption, and they reconnect within 15 seconds, then they will remain part of the space and no leave event will be emitted.
Profile data
Profile data can be set when entering a space. It is optional data that can be used to associate information with a member, such as a preferred username, or profile picture that can be subsequently displayed in their avatar. Profile data can be any arbitrary JSON-serializable object. Profile data is returned in the payload of all space events. The following is an example of setting profile data when entering a space:Update profile data
Profile data can be updated at any point after entering a space by callingupdateProfileData(). This will emit an updateProfile event. If a client hasn’t yet entered the space, updateProfileData() will instead enter the space, with the profile data, and emit an enter event.
The following is an example of updating profile data:
A function can be passed to updateProfileData() in order to update a field based on the existing profile data:
Subscribe to space state
Subscribe to space state updates by registering a listener. Use thesubscribe() method on the space object to receive updates.
The following events will trigger a space event:
- A member enters the space
- A member leaves the space
- A member is removed from the space state after the offlineTimeout period has elapsed
- A member updates their profile data
- A member sets a new location
members. Any events that trigger a change in space state will always return the current state of the space as an array of member objects.
The following is an example of subscribing to space events:
The following is an example payload of a space event.
The following are the properties of an individual member within a space event payload:
| Property | Description | Type |
|---|---|---|
| clientId | The client identifier for the member. | String |
| connectionId | The unique identifier of the member’s connection. | String |
| isConnected | Whether the member is connected to Ably or not. | Boolean |
| profileData | The optional profile data associated with the member. | Object |
| location | The current location of the member. | Object |
| lastEvent.name | The most recent event emitted by the member. | String |
| lastEvent.timestamp | The timestamp of the most recently emitted event. | Number |
Unsubscribe from space events
Unsubscribe from space events to remove previously registered listeners. The following is an example of removing a listener:Retrieve space state
The current state of the space can be retrieved in a one-off call. This will return an array of allmember objects currently in the space. This is a local call and retrieves the membership of the space retained in memory by the SDK.
The following is an example of retrieving the current space state. Ths includes members that have recently left the space, but have not yet been removed:
Advanced properties
The following sections are only relevant if you want to further customize a space, or understand more about the Spaces SDK. They aren’t required to get up and running with the basics.Space options
An additional set of optional properties may be passed when creating or retrieving a space to customize the behavior of different features. The following properties can be customized:| Property | Description | Type |
|---|---|---|
| offlineTimeout | Number of milliseconds after a member loses connection or closes their browser window to wait before they are removed from the member list. The default is 120,000ms (2 minutes). | Number |
| cursors | A cursor options object for customizing live cursor behavior. | Object |
| cursors.outboundBatchInterval | The interval, in milliseconds, at which a batch of cursor positions are published. This is multiplied by the number of members in a space, minus 1. The default value is 100ms. | Number |
| cursors.paginationLimit | The number of pages searched from history for the last published cursor position. The default is 5. | Number |
spaces.get():
Space foundations
The Spaces SDK is built upon existing Ably functionality available in Ably’s Core SDKs. Understanding which core features are used to provide the abstractions in the Spaces SDK enables you to manage space state and build additional functionality into your application. A space is created as an Ably channel. Members attach to the channel and join its presence set when they enter the space. Avatar stacks, member locations, and component locking are all handled on this channel. To manage the state of the space, you can monitor the state of the underlying channel. The channel object can be accessed throughspace.channel.
The following is an example of registering a listener to wait for a channel to become attached: