-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
14 additions
and
13 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,6 @@ | ||
# Ably Collaborative Spaces SDK | ||
|
||
<p align="center"> | ||
<p align="left"> | ||
<a href=""> | ||
<img src="https://badgen.net/badge/development-status/alpha/yellow?icon=github" alt="Development status" /> | ||
</a> | ||
|
@@ -16,23 +16,21 @@ The [Ably](https://ably.com) Collaborative Spaces SDK enables you to implement r | |
|
||
![Example collaboration GIF](/docs/images/collab.gif) | ||
|
||
> The Collaborative Spaces SDK is currently under development. If you are interested in being an early adopter and providing feedback then you can [sign up](https://go.ably.com/spaces-early-access) for early access and are welcome to [provide us any feedback](https://go.ably.com/spaces-feedback). | ||
Rather than having to coordinate resources on calls, or send documents and spreadsheets back and forth using a combination of tools, having in-app realtime collaboration features has proven to boost productivity in remote workplaces. Try out a [live demo](https://space.ably.dev) of a slideshow application for an example of realtime collaboration in action. | ||
|
||
Realtime collaboration enables users to have contextual awareness of other users within an application. This means knowing: | ||
|
||
### Who is in the application? | ||
**Who is in the application?** | ||
|
||
One of the most important aspects of collaboration is knowing who else you're working with. The most common way to display this is using an "Avatar Stack" to show who else is currently online, and those that have recently gone offline. | ||
|
||
### Where is each user within the application? | ||
**Where is each user within the application?** | ||
|
||
Knowing where each user is within an application helps you understand their intentions without having to explicitly ask them. For example, seeing that a colleague is currently viewing slide 2 of a slideshow means that you can carry out your own edits to slide 3 without interfering with their work. Displaying the locations of your users can be achieved by highlighting the UI element they have selected, displaying a miniature avatar stack on the slide they are viewing, or showing the live location of their cursors. | ||
|
||
### What is everyone doing in the application? | ||
**What is everyone doing in the application?** | ||
|
||
Seeing where users are within an application aids in understanding what they may be working on. It's possible to go one step further though and see what changes they're making to an application. For example, you can display a typing indicator when a colleague is editing a cell in a spreadsheet, or even update the contents of the cell as they type it. | ||
All users should be working on the latest state of the application. If one user makes a change or an update, this change should be synced to a backend database and be immediately reflected in the UI for all users. For example, you can display a typing indicator when a colleague is editing a cell in a spreadsheet. As soon as they save their update, the new cell contents should be visible to all users. | ||
|
||
## Quickstart | ||
|
||
|
@@ -54,10 +52,11 @@ You can use [basic authentication](https://ably.com/docs/auth/basic) for testing | |
|
||
### Authenticate and instantiate | ||
|
||
Install the Collaborative Spaces SDK: | ||
Install the Collaborative Spaces SDK and the Ably JavaScript SDK: | ||
|
||
```sh | ||
npm install ably @ably-labs/spaces | ||
npm install ably | ||
``` | ||
|
||
To instantiate the Spaces SDK, create an [Ably client](https://ably.com/docs/getting-started/setup) and pass it into the Spaces constructor: | ||
|
@@ -66,13 +65,13 @@ To instantiate the Spaces SDK, create an [Ably client](https://ably.com/docs/get | |
import Spaces from '@ably-labs/spaces'; | ||
import { Realtime } from 'ably'; | ||
|
||
const client = new Realtime.Promise(options); | ||
const client = new Realtime.Promise({key: "<API-key>", clientId: "<client-ID"}); | ||
const spaces = new Spaces(client); | ||
``` | ||
|
||
You can create an Ably client with just an API key, however to use Spaces you must also set a [`clientId`](https://ably.com/docs/auth/identified-clients) so that clients are identifiable. If you are prototyping, you can use a package like [nanoid](https://www.npmjs.com/package/nanoid) to generate an ID. | ||
|
||
### CDN | ||
#### CDN | ||
|
||
You can also use Spaces with a CDN, such as [unpkg](https://www.unpkg.com/): | ||
|
||
|
@@ -81,8 +80,6 @@ You can also use Spaces with a CDN, such as [unpkg](https://www.unpkg.com/): | |
<script src="https://unpkg.com/@ably-labs/[email protected]/dist/iife/index.bundle.js"></script> | ||
``` | ||
|
||
**Note**: when you use a CDN, you need to include the Ably SDK as well. | ||
|
||
### Space membership | ||
|
||
A space is the virtual, collaborative area of an application you want to monitor. A space can be anything from a web page, a sheet within a spreadsheet, an individual slide in a slideshow, or the slideshow itself. Create a space and listen for events to see when clients enter and leave. | ||
|
@@ -196,7 +193,7 @@ The following is an example `locationUpdate` event received by subscribers when | |
|
||
### Cursors | ||
|
||
Use the Cursors API to track client pointer events across an application: | ||
Use the Cursors API to track client pointer events across an application. Events can also include associated data, such as pointer attributes and the IDs of associated UI elements: | ||
|
||
```ts | ||
// Register a cursor instance | ||
|
@@ -224,3 +221,7 @@ The above listener will receive a `CursorUpdate` event: | |
"data": { "color": "red" } | ||
} | ||
``` | ||
|
||
## Status | ||
|
||
The Collaborative Spaces SDK is currently under development. If you are interested in being an early adopter and providing feedback then you can [sign up](https://go.ably.com/spaces-early-access) for early access and are welcome to [provide us with feedback](https://go.ably.com/spaces-feedback). |