Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/pages/docs/spaces/avatar.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -324,4 +324,6 @@ space.members.subscribe('remove', (member) => {

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.

<Aside data-type='see-evidence'>Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/connection-recovery)</Aside>

Avatar stacks build upon the functionality of the Ably Pub/Sub [presence](/docs/presence-occupancy/presence) feature. Members are entered into the presence set when they [enter the space](/docs/spaces/space#enter).
2 changes: 2 additions & 0 deletions src/pages/docs/spaces/cursors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Live cursor updates are not available as part of the [space state](/docs/spaces/
Live cursors are a great way of providing contextual awareness as to what members are looking at within an application. However, too many cursors moving across a page can often be a distraction rather than an enhancement. As such, Ably recommends a maximum of 20 members simultaneously streaming their cursors in a space at any one time for an optimal end-user experience.
</Aside>

<Aside data-type='see-evidence'>With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)</Aside>

## Set cursor position <a id="set"/>

Set the position of a member's cursor using the [`set()`](https://sdk.ably.com/builds/ably/spaces/main/typedoc/classes/Cursors.html#set) method. A position must contain an X-axis value and a Y-axis value to set the cursor position on a 2D plane. Calling `set()` will emit a cursor event so that other members are informed of the cursor movement in realtime.
Expand Down
2 changes: 2 additions & 0 deletions src/pages/docs/spaces/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ Whether you're adding realtime collaborative capabilities to an existing applica
| [Live cursors](/docs/spaces/cursors) | a way to efficiently track the cursor positions of users in realtime. |
| [Component locking](/docs/spaces/locking) | a way to optimistically lock stateful UI components before letting users edit them. |

<Aside data-type='see-evidence'>Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/scalability)</Aside>

There are several benefits provided by the fact that the Spaces SDK is built on top of the Ably JavaScript SDK:

* [Authentication](/docs/auth) and [connection management](/docs/connect) are handled by the underlying SDK.
Expand Down
2 changes: 2 additions & 0 deletions src/pages/docs/spaces/locations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -234,4 +234,6 @@ await space.locations.set({ slide: 0, elementId: 'title' });

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.

<Aside data-type='see-evidence'>Users in the same region will have a consistent experience with all subscribers observing messages in the same order. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)</Aside>

Member locations build upon the functionality of the Ably Pub/Sub [presence](/docs/presence-occupancy/presence) feature. Members are entered into the presence set when they [enter the space](/docs/spaces/space#enter).
2 changes: 2 additions & 0 deletions src/pages/docs/spaces/locking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Each lock is identified by a unique string ID, and only a single member may hold
Optimistic locking means that there is a chance that two members may begin editing the same UI component before it is confirmed which member holds the lock. On average, the time taken to reconcile which member holds a lock is in the hundreds of milliseconds. Your application needs to handle the member that successfully obtained the lock, as well as the member that had their request invalidated.
</Aside>

<Aside data-type='see-evidence'>Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)</Aside>

## Lock states <a id="states"/>

Component locking is handled entirely client-side. Members may begin to optimistically edit a component as soon as they call [`acquire()`](#acquire) on the lock identifier related to it. Alternatively, you could wait until they receive a `locked` event and display a spinning symbol in the UI until this is received. In either case, a subsequent `unlocked` event may invalidate that member's lock request if another member acquired it earlier. The time for confirmation of whether a lock request was successful or rejected is, on average, in the hundreds of milliseconds. However, your code should handle all possible lock state transitions.
Expand Down
2 changes: 2 additions & 0 deletions src/pages/docs/spaces/setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,4 +88,6 @@ Only the promises version of the Ably JavaScript is supported when using Spaces,

A Spaces client exposes the underlying [connection](/docs/connect) to Ably that is established via the Ably JavaScript SDK. This means that Spaces clients benefit from the same functionality available in the Ably JavaScript SDK, such as automatic transport selection and [connection state recovery](/docs/connect/states) in the event of brief disconnections.

<Aside data-type='see-evidence'>If a client reconnects within two minutes, full connection recovery with exactly-once delivery is guaranteed. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)</Aside>

Connections transition through multiple states throughout their lifecycle. Whilst these transitions are handled by the Ably SDK, there are certain cases where you may need to observe and handle them within your application. Ably SDKs enable these transitions to be observed and triggered using methods available on the `connection` object. The Spaces SDK exposes the underlying connection with `spaces.connection`, which is a reference to [`client.connection`](/docs/api/realtime-sdk/connection) in the Ably JavaScript SDK.
2 changes: 2 additions & 0 deletions src/pages/docs/spaces/space.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,8 @@ const space = await spaces.get('board-presentation', {

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.

<Aside data-type='see-evidence'>Messages published using Realtime have consistent ordering for all subscribers, with each message assigned a unique serial number to preserve its place. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering)</Aside>

A space is created as an Ably [channel](/docs/channels). Members [attach](/docs/channels/states#attach) to the channel and join its [presence set](/docs/presence-occupancy/presence) when they [enter](#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](/docs/channels/states). The channel object can be accessed through `space.channel`.
Expand Down