Skip to content

Commit

Permalink
fixup! Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
m-hulbert committed Jul 10, 2023
1 parent 54a086a commit fe7505a
Showing 1 changed file with 14 additions and 13 deletions.
27 changes: 14 additions & 13 deletions README.md
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>
Expand All @@ -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

Expand All @@ -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:
Expand All @@ -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/):

Expand All @@ -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/spaces@0.0.10/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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).

0 comments on commit fe7505a

Please sign in to comment.