Saving PDF Annotations

PSPDFKit for Web allows making changes to documents in these two fundamental ways:

• Changes to the document records (including annotations, form field values, comments, or bookmarks). These changes can be saved without touching the original document.

• Changes to the document itself either via the Document Editor or when digitally signing the document. These require saving the whole document.

This article explains the annotation saving mechanism. Refer to the Save a Document guides to learn more about document saving itself.

The annotation saving mechanism depends on whether PSPDFKit for Web is using the Server-Backed or Standalone operational mode.

Server-Backed

By default, changes to annotations are always synced to the server. This means you can always use the backend API to interact with annotations. This auto-save behavior can be configured by the instantiation configuration option, Configuration#autoSaveMode. You can learn more about this option in our Auto-Save guide.

Before the change is sent to the server, we assign a stable ID (ULID). This ID is also used by the server, and it allows you to track updates that happen to the annotation before the server responds.

ℹ️ Note: Each change sent to the server requires a unique ID. If you need to reference the annotation ID before it’s created (for example, when creating form fields with their widgets), a suitable ULID can be generated via PSPDFKit#generateInstantId().

If you’d like to ensure a new annotation has been saved by the server, you can use Instance#ensureChangesSaved:

PSPDFKit.load(configuration).then(async (instance) => {
	const createdAnnotations = await instance.create(newAnnotation);
	const [savedAnnotation] = await instance.ensureChangesSaved(
		createdAnnotations,
	);
	console.log(savedAnnotation.id); // => '01BS964AM5Z01J9MKBK64F22BQ'
});

Before annotations are saved, annotations.willSave is emitted. When this event occurs, you can be sure we’ll commit changes to the underlying backend. As an example, this event can be used to display a loading indicator.

After the server responds to our changes, annotations.didSave is emitted. This event will always follow annotations.willSave.

Standalone

In a PSPDFKit for Web installation that’s deployed in Standalone mode, annotations will be stored in memory until they’re exported. See the guide on exporting and importing XFDF, Instant JSON or using Server-Backed mode for more information.

Standalone mode has the same annotation persistence steps as Server-Backed mode. This means we still differentiate between saved and unsaved annotations in standalone, and the exported Instant JSON will only contain annotations that are saved. You can configure the auto-save behavior by the instantiation configuration option, Configuration#autoSaveMode. Learn more about this option in our Auto-Save guide.