# js-collaboration-presence

## Content

`js-collaboration-presence` is a plugin based on `js-collaboration` for real-time collaboration, providing user presence state management and sharing functionality. It is divided into the client side ([js-collaboration-presence-client](/spreadjs/api/v18/collaboration/js-collaboration-presence-client/README#spreadjs-api)) and the server side ([js-collaboration-presence](/spreadjs/api/v18/collaboration/js-collaboration-presence/README#spreadjs-api)).

* **Client Side** ([Presence](/spreadjs/api/v18/collaboration/js-collaboration-presence-client/classes/Presence)): Responsible for capturing the local user's state, sending it to the server, and receiving other users' states.
* **Server Side** ([presenceFeature](/spreadjs/api/v18/collaboration/js-collaboration-presence/README#presencefeature)): Responsible for broadcasting and coordinating the states of all clients, ensuring state data consistency within the collaboration room.

## Applicable Scenarios

Suitable for scenarios that require real-time display of user activity states, such as showing:

* collaborators' cursor positions in text documents
* selected areas in spreadsheets

## Core Features

**Real-Time User State Sharing**

* **Feature Description:** `js-collaboration-presence`can manage and share real-time position information of clients within a document. This information includes the user's cursor position, selected area, etc., allowing other users to understand the current collaboration status of the document in real time.
* **Application Scenarios**
    * In multi-user collaborative document editing, users can clearly see the positions where other users are editing, avoiding duplicate edits or conflicts.
    * In spreadsheet collaboration, users can see in real time the cells or areas other users are working on, facilitating coordinated work.

**User Event Listening and Notification**
![overview](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/overview.e3bf59.png)

* **Feature Description:** `js-collaboration-presence-client`allows developers to subscribe to and listen for user state changes, enabling specific actions to be performed when a user's presence state changes. These events include users joining, leaving, or updating their state (including position updates, selection changes, etc.).
* **Application Scenarios**
    * When a new user joins the collaboration space, the interface can be automatically updated to display the new user's presence state.
    * When a user updates their presence state (e.g., changing cursor position), the interface can be updated in real time to ensure all users see consistent information.

**Multi-User Collaboration Support**

![architecture1](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/architecture1.41753b.png)

* **Feature Description:** `js-collaboration-presence` seamlessly integrates with `js-collaboration` and `js-collaboration-ot` to build a complete collaboration platform. Through the bidirectional linking provided by `js-collaboration` and the data synchronization and conflict resolution provided by `js-collaboration-ot`, `js-collaboration-presence` can manage user presence states in a real-time collaboration environment.
* **Application Scenarios:** In a complete collaboration platform, `js-collaboration-presence` is responsible for managing user presence states, while `js-collaboration` and `js-collaboration-ot` handle data synchronization and consistency, together providing users with a smooth collaboration experience.

## Limitation

`js-collaboration-presence` does not support data persistence. Presence data is only retained in the server's memory, storing the latest states of each user.

### Potential Impact

* **Data Loss**: When the server restarts or a client disconnects, all stored presence states (including user positions and selections) will be lost.
* **No Persistent Storage**: Presence does not provide functionality to save user states to disk or a database, so it is not suitable for scenarios requiring persistent user states.

### Recommended Solutions

* **Periodic Backup**: Although Presence does not support built-in persistence, you can consider periodically backing up the in-memory state information to external storage.
* **Custom Persistence**: Developers can implement custom persistence logic to save user states to a database and restore these states when the server starts.

## Next steps

Follow the step-by-step tutorial to build a collaborative rich text editor with Presence: [Tutorial：Add Presence Functionality to a Real-Time Collaborative Text Editor](/spreadjs/docs/v18/spreadjs-collaboration-server/collaboration-framework/js-collaboration-presence/tutorialadd-presence-functionality-to-a-real-time-collaborative-text-editor)
Master core concepts and APIs:

* [Presence Client](/spreadjs/docs/v18/spreadjs-collaboration-server/collaboration-framework/js-collaboration-presence/presence-client)
* [Presence Server](/spreadjs/docs/v18/spreadjs-collaboration-server/collaboration-framework/js-collaboration-presence/presence-server)

Each module will demonstrate practical usage via code examples.