This package has been deprecated

Author message:

The Spaces library is advancing into beta and has moved to @ably/spaces. @ably-labs/spaces is now deprecated. If you have any questions, reach out on [e-mail]

@ably-labs/spaces

Ably Collaborative Spaces SDK

Ably is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the Ably documentation.

---

The Ably Collaborative Spaces SDK enables you to implement realtime collaborative features in your applications.

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 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?

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 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?

Changes to the app state made by users not only need to be synced with your backend for validation and long term storage, but also be immediately reflected in the UI so that users are always viewing the latest information. For example, in a spreadsheet application, if one user has entered a value in a cell, all other users need to see that change instantly. Live updates help accomplish this in a collaborative space.

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 for early access and are welcome to provide us with feedback.

Quickstart

Get started quickly using this section, or take a look at:

• more detailed usage instructions
• class definitions
• how the Spaces SDK uses Ably internally

Prerequisites

To begin, you will need the following:

• An Ably account. You can sign up for free.
• An Ably API key. You can create API keys in an app within your Ably account.
  • The API key needs the following capabilities: publish, subscribe, presence and history.

You can use basic authentication for testing purposes, however it is strongly recommended that you use token authentication in production environments.

Authenticate and instantiate

Install the Collaborative Spaces SDK and the Ably JavaScript SDK:

npm install ably @ably-labs/spaces

To instantiate the Spaces SDK, create an Ably client and pass it into the Spaces constructor:

import Spaces from '@ably-labs/spaces';
import { Realtime } from 'ably';

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 so that clients are identifiable. If you are prototyping, you can use a package like nanoid to generate an ID.

CDN

You can also use Spaces with a CDN, such as unpkg:

<script src="https://cdn.ably.com/lib/ably.min-1.js"></script>
<script src="https://unpkg.com/@ably-labs/spaces@0.0.10/dist/iife/index.bundle.js"></script>

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.

Space membership is used to build avatar stacks and find out which members are online within a space.

// Create a new space
const space = await spaces.get('demoSlideshow');

// Register a listener to subscribe to events of when users enter or leave the space
space.subscribe('membersUpdate', (members) => {
  console.log(members);
});

// Enter a space, publishing a memberUpdate event, including optional profile data
space.enter({
  username: 'Claire Lemons',
  avatar: 'https://slides-internal.com/users/clemons.png',
});

The following is an example membersUpdate event received by listeners when a user enters a space:

[
  {
    "clientId": "clemons#142",
    "connectionId": "hd9743gjDc",
    "isConnected": true,
    "lastEvent": {
      "name": "enter",
      "timestamp": 1677595689759
    },
    "location": null,
    "profileData": {
      "username": "Claire Lemons",
      "avatar": "https://slides-internal.com/users/clemons.png"
    }
  }
]

Location

Member locations enable you to track where users are within an application. A location could be a form field, multiple cells in a spreadsheet or a slide in a slide deck editor. Subscribe to all location updates, specific location, or locations changes for a given member.

// Register a listener to subscribe to events of when users change location
space.locations.on('locationUpdate', (locationUpdate) => {
  console.log(locationUpdate);
});

// You need to enter a space before setting your location
space.enter({
  username: 'Claire Lemons',
  avatar: 'https://slides-internal.com/users/clemons.png',
});

// Publish locationUpdate event with a client's location when they select a UI element
space.locations.set({ slide: '3', component: 'slide-title' });

The following is an example locationUpdate event received by subscribers when a user changes location:

{
  "member": {
    "clientId": "clemons#142",
    "connectionId": "hd9743gjDc",
    "isConnected": true,
    "profileData": {
      "username": "Claire Lemons",
      "avatar": "https://slides-internal.com/users/clemons.png"
    },
    "location": {
      "slide": "3",
      "component": "slide-title"
    },
    "lastEvent": {
      "name": "update",
      "timestamp": 1
    }
  },
  "previousLocation": {
    "slide": "2",
    "component": null
  },
  "currentLocation": {
    "slide": "3",
    "component": "slide-title"
  }
}

Cursors

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:

// You need to enter a space before setting your cursor updates
space.enter({
  username: 'Claire Lemons',
  avatar: 'https://slides-internal.com/users/clemons.png',
});

// Publish a CursorUpdate with the location of a mouse, including optional data for the current member
window.addEventListener('mousemove', ({ clientX, clientY }) => {
  space.cursors.set({ position: { x: clientX, y: clientY }, data: { color: 'red' } });
});


// Listen to events published on "mousemove" by all members
space.cursors.on('cursorsUpdate', (cursorUpdate) => {
  console.log(cursorUpdate);
});

The above listener will receive a CursorUpdate event:

{
  "connectionId": "hd9743gjDc",
  "clientId": "clemons#142",
  "position": { "x": 864, "y": 32 },
  "data": { "color": "red" }
}