diff --git a/src/pages/docs/spaces/avatar.mdx b/src/pages/docs/spaces/avatar.mdx index fd148ec7df..4bd964941c 100644 --- a/src/pages/docs/spaces/avatar.mdx +++ b/src/pages/docs/spaces/avatar.mdx @@ -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. + + 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). diff --git a/src/pages/docs/spaces/cursors.mdx b/src/pages/docs/spaces/cursors.mdx index 2b3e30f231..40442f5031 100644 --- a/src/pages/docs/spaces/cursors.mdx +++ b/src/pages/docs/spaces/cursors.mdx @@ -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. + + ## Set cursor position 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. diff --git a/src/pages/docs/spaces/index.mdx b/src/pages/docs/spaces/index.mdx index 6c4392dc7d..f8da545673 100644 --- a/src/pages/docs/spaces/index.mdx +++ b/src/pages/docs/spaces/index.mdx @@ -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. | + + 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. diff --git a/src/pages/docs/spaces/locations.mdx b/src/pages/docs/spaces/locations.mdx index e55ff8af5a..ccfe54971b 100644 --- a/src/pages/docs/spaces/locations.mdx +++ b/src/pages/docs/spaces/locations.mdx @@ -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. + + 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). diff --git a/src/pages/docs/spaces/locking.mdx b/src/pages/docs/spaces/locking.mdx index 3f88a6c094..b85d1a758b 100644 --- a/src/pages/docs/spaces/locking.mdx +++ b/src/pages/docs/spaces/locking.mdx @@ -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. + + ## Lock 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. diff --git a/src/pages/docs/spaces/setup.mdx b/src/pages/docs/spaces/setup.mdx index 5fc928839d..9bca81359e 100644 --- a/src/pages/docs/spaces/setup.mdx +++ b/src/pages/docs/spaces/setup.mdx @@ -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. + + 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. diff --git a/src/pages/docs/spaces/space.mdx b/src/pages/docs/spaces/space.mdx index e544e70d21..3a4fd3414f 100644 --- a/src/pages/docs/spaces/space.mdx +++ b/src/pages/docs/spaces/space.mdx @@ -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. + + 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`.