-
Notifications
You must be signed in to change notification settings - Fork 46
Adds USPs to spaces docs #3057
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Adds USPs to spaces docs #3057
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. [See evidence here 🕵️](/docs/platform/architecture/infrastructure-operations#resource-implications)</Aside> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The positioning of this is not the greatest, it's immediately below another Aside. Is it also relevant to the page content? |
||
|
|
||
| ## 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. | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. [See evidence here 🕵️](/docs/platform/architecture/scalability)</Aside> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think this could be better placed just above the Spaces SDK header. What do you think? |
||
|
|
||
| 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. | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. [See evidence here 🕵️](/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)</Aside> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. As this is a page about the member location within the page. Could this aside cause some confusion over what region we're talking about etc? Also, I think this could be splitting up two paragraphs that would be best without a separation? |
||
|
|
||
| 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). | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. [See evidence here 🕵️](/docs/platform/architecture/edge-network)</Aside> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should we be adding an Aside immediately after another? And would this aside be better placed further down the page somewhere? Such as maybe before: Subscribe to lock events header? |
||
|
|
||
| ## 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. | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. [See evidence here 🕵️](/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)</Aside> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I feel this would disrupt the reading of client connections. Instead maybe move it further down the page after the 2 paragraphs? |
||
|
|
||
| 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. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. [See evidence here 🕵️](/docs/platform/architecture/message-ordering)</Aside> | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I feel this interrupts the reading of the headed section. Would this be better moved somewhere like above: |
||
|
|
||
| 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`. | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Although this could be relevant to the page I think it splits up the two paragraphs that are relevant to each other. Do you think we could move this somewhere?