Synchronize Annotations

PSPDFKit Server has been deprecated and replaced by PSPDFKit Document Engine. All PSPDFKit Server and PSPDFKit for Web Server-Backed licenses will work as before and be supported until 15 May 2024 (we will contact you about license migration). To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

When using PSPDFKit Web Server-Backed, there are two strategies that are used when synchronizing annotations between server and client. This guide will give you an overview how each of them work.

With Instant Sync Enabled

If the Instant license component is enabled, PSPDFKit Server can synchronize changes to annotations across multiple users in real time. This allows your users to collaborate in real time. The following should give you an overview of how this works.

Listening for Changes

1. A user opens a document hosted on PSPDFKit Server.

2. An initial sync request is sent, and the response contains all annotations that currently exist in the document.

3. The user’s client will start listening for changes to annotations happening on the server.

4. As soon as a change happens, PSPDFKit Server will send a list of all added, changed, and removed annotations.

5. The client updates its local state and continues listening for changes.

Making Changes

1. A user makes a change to existing annotations.

2. The user’s client sends a request containing the changes to the server.

3. Server sends back a response that tells the client which changes were accepted and which ones were rejected due to conflict.

4. The client updates its local state and continues listening for changes.

Handling Conflicts

1. User A and User B make a change to an existing annotation.

2. User A’s change is processed first, updating Annotation A to Annotation B.

3. User A receives a response containing the applied changes.

4. User A’s local state is updated, and it continues listening for changes.

5. User B’s change is processed second, but the update from Annotation A to Annotation C is rejected since the annotation has changed between this update and the last state User B knew about.

6. User B receives a response that their change was rejected, and that Annotation A was updated to Annotation B.

7. User B’s local state is updated, and it continues listening for changes.

With Instant Sync Disabled

If you don’t have Instant Sync enabled, PSPDFKit Server will use a different strategy when sending annotations to your users. The main drawback of this strategy is that changes to annotations won’t appear for users automatically in real time, but instead only after a page refresh.

1. A user opens a document hosted on PSPDFKit Server.

2. The annotations are fetched for each page as they come into view.

3. For each annotation change, a request is sent to the server updating, deleting, or creating the annotation.

4. Changes made by other users aren’t sent to the user in real time, and they’ll only appear after a page refresh.