-
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
2 changed files
with
46 additions
and
64 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,44 +1,56 @@ | ||
| # Ably | ||
| # Ably Collaborative Spaces SDK | ||
|
|
||
| _[Ably](https://ably.com/) is the platform that powers realtime experiences at scale, including live chat, data broadcast, notifications, audience engagement and collaboration._ | ||
| <p align="center"> | ||
| <a href=""> | ||
| <img src="https://badgen.net/badge/development-status/alpha/yellow?icon=github" alt="Development status" /> | ||
| </a> | ||
| <a href=""> | ||
| <img src="https://github.com/ably-labs/spaces/actions/workflows/dev-ci.yml/badge.svg?branch=main" alt="CI status" /> | ||
| </a> | ||
| <a href=""> | ||
| <img src="https://badgen.net/github/license/3scale/saas-operator" alt="License" /> | ||
| </a> | ||
| </p> | ||
|
|
||
| ## Collaborative Spaces SDK | ||
| The [Ably](https://ably.com) Collaborative Spaces SDK enables you to implement realtime collaborative features in your applications. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| The Collaborative Spaces SDK enables you to implement realtime collaborative features in your applications. | ||
| > 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). | ||
| Go to ["Why do I need realtime collaboration?"](#why-do-I-need-realtime-collaboration) to read why we think you should add realtime collaboration to your application. | ||
| 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. | ||
|
|
||
| ### Development status | ||
| Realtime collaboration enables users to have contextual awareness of other users within an application. This means knowing: | ||
|
|
||
| ### 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. | ||
|
|
||
| The Collaborative Spaces SDK is currently under development. | ||
| ### Where is each user within the application? | ||
|
|
||
| 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). | ||
| 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. | ||
|
|
||
| ## Getting started | ||
| ### What is everyone doing in the application? | ||
|
|
||
| Use the following snippets to quickly get up and running. | ||
| 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. | ||
|
|
||
| See the [docs](/docs) directory for: | ||
| ## Quickstart | ||
|
|
||
| - more detailed [usage instructions](/docs/usage.md) | ||
| - [class definitions](/docs/class-definitions.md) | ||
| - details on how Spaces uses [Ably internally](/docs/channel-behaviors.md) | ||
| Get started quickly using this section, or take a look at: | ||
|
|
||
| You can also view a [live demo](https://space.ably.dev) which uses an example slideshow app to demonstrate updating an avatar stack, displaying user locations and live cursors. | ||
| * more detailed [usage instructions](/docs/usage.md) | ||
| * [class definitions](/docs/class-definitions.md) | ||
| * how the Spaces SDK uses [Ably internally](/docs/channel-behaviors.md) | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| To begin, you will need the following: | ||
|
|
||
| - An Ably account. You can [sign up](https://ably.com/signup) for free. | ||
| - An Ably API key. You can create API keys in an app within your [Ably account](https://ably.com/dashboard). | ||
| - The API key needs the following [capabilities](https://ably.com/docs/realtime/authentication#capabilities-explained): `publish`, `subscribe`, `presence` and `history`. | ||
| * An Ably account. You can [sign up](https://ably.com/signup) for free. | ||
| * An Ably API key. You can create API keys in an app within your [Ably account](https://ably.com/dashboard). | ||
| * The API key needs the following [capabilities](https://ably.com/docs/auth/capabilities): `publish`, `subscribe`, `presence` and `history`. | ||
|
|
||
| You can use [basic authentication](https://ably.com/docs/realtime/authentication#basic-authentication) for testing purposes, however it is strongly recommended that you use [token authentication](https://ably.com/docs/realtime/authentication#token-authentication) in any production environments. | ||
| You can use [basic authentication](https://ably.com/docs/auth/basic) for testing purposes, however it is strongly recommended that you use [token authentication](https://ably.com/docs/auth/token) in production environments. | ||
|
|
||
| ### Authenticate and instantiate | ||
|
|
||
|
|
@@ -48,17 +60,7 @@ Install the Collaborative Spaces SDK: | |
| npm install ably @ably-labs/spaces | ||
| ``` | ||
|
|
||
| Instantiate Spaces with your Ably API key and a [clientId](https://ably.com/docs/realtime/authentication?lang=javascript#identified-clients) (if prototyping, you can use a package like [nanoid](https://www.npmjs.com/package/nanoid) to generate an id): | ||
|
|
||
| ```ts | ||
| import Spaces from '@ably-labs/spaces'; | ||
|
|
||
| const spaces = new Spaces({ key: ABLY_API_KEY, clientId: 'id' }); | ||
| ``` | ||
|
|
||
| Spaces will create an Ably realtime client for you. This client will be accessible on the instance via `spaces.ably`. See the [Ably docs](https://ably.com/docs) for details. | ||
|
|
||
| Alternatively, if you already have an Ably realtime client, you can instantiate by passing it to the `Spaces` constructor: | ||
| To instantiate the Spaces SDK, create an [Ably client](https://ably.com/docs/getting-started/setup) and pass it into the Spaces constructor: | ||
|
|
||
| ```ts | ||
| import Spaces from '@ably-labs/spaces'; | ||
|
|
@@ -68,22 +70,22 @@ const client = new Realtime.Promise(options); | |
| 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 | ||
|
|
||
| You can also use Spaces with a CDN like [unpkg](https://www.unpkg.com/): | ||
| You can also use Spaces with a CDN, such as [unpkg](https://www.unpkg.com/): | ||
|
|
||
| ```html | ||
| <script src="https://cdn.ably.com/lib/ably.min-1.js"></script> | ||
| <script src="https://unpkg.com/@ably-labs/[email protected]/dist/iife/index.bundle.js"></script> | ||
| ``` | ||
|
|
||
| Note that when you use a CDN, you need to include the Ably SDK as well. | ||
|
|
||
| ## API | ||
| **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 to events for when clients enter and leave it. | ||
| 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. | ||
|
|
||
| Space membership is used to build avatar stacks and find out which members are online within a space. | ||
|
|
||
|
|
@@ -194,19 +196,19 @@ The following is an example `locationUpdate` event received by subscribers when | |
|
|
||
| ### Cursors | ||
|
|
||
| Use the Cursors API to track client pointer events (like a `mousemove`) across an application: | ||
| Use the Cursors API to track client pointer events across an application: | ||
|
|
||
| ```ts | ||
| // Register a cursor instance | ||
| const mouseMove = space.cursors.get('mousemove'); | ||
| const demoCursors = space.cursors.get('demoSlideshow-cursors'); | ||
|
|
||
| // Publish a CursorUpdate with the location of a mouse, including optional data for the current member | ||
| window.addEventListner('mousemove', ({ clientX, clientY }) => { | ||
| mouseMove.set({ position: { x: clientX, y: clientY }, data: { color: 'red' } }); | ||
| window.addEventListener('mousemove', ({ clientX, clientY }) => { | ||
| demoCursors.set({ position: { x: clientX, y: clientY }, data: { color: 'red' } }); | ||
| }); | ||
|
|
||
| // Listen to events published on "pointer" by all members | ||
| mouseMove.on('cursorUpdate', (cursorUpdate) => { | ||
| // Listen to events published on "mousemove" by all members | ||
| demoCursors.on('cursorUpdate', (cursorUpdate) => { | ||
| console.log(cursorUpdate); | ||
| }); | ||
| ``` | ||
|
|
@@ -215,30 +217,10 @@ The above listener will receive a `CursorUpdate` event: | |
|
|
||
| ```js | ||
| { | ||
| "name": "pointer", | ||
| "name": "demoSlideshow-cursors", | ||
| "connectionId": "hd9743gjDc", | ||
| "clientId": "clemons#142", | ||
| "position": { "x": 864, "y": 32 }, | ||
| "data": { "color": "red" } | ||
| } | ||
| ``` | ||
|
|
||
| ## Why do I need realtime collaboration? | ||
|
|
||
| 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. | ||
|
|
||
|  | ||
|
|
||
| Realtime collaboration enables users to have contextual awareness of other users within an application. This means knowing: | ||
|
|
||
| ### 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? | ||
|
|
||
| Knowing where each user is within an application helps you understand their attentions without always needing 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? | ||
|
|
||
| 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. | ||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.