Introduction to Instant Comments

As of PSPDFKit for iOS 10.3, PSPDFKit provides user interface components for viewing, adding, and deleting comments in PDF documents. This feature, Instant Comments, is available only if you’re using PSPDFKit Instant.

You can use Instant Comments to build collaborative workflows where multiple users can discuss specific sections of a document without ever leaving the viewer. They receive updates in real time thanks to our PSPDFKit Instant engine.

Licensing

Instant Comments is a separate component in your PSPDFKit license. Without this feature included in your license, your app won’t be able to view, search, or add comments. Please contact our sales team to add this feature to your license, or ask for a trial license if you want to try out this feature.

Terminology

Before continuing, let’s first define some terminology as it relates to Instant Comments:

  • root annotation — This is the annotation to which all the comments in a single thread are linked.

  • comment thread — This is a group of comments with the same root annotation.

  • comment — This is a single comment added by any user.

Introduction

All comments are linked to their respective root annotations. The comments with the same root annotation are part of a single comment thread. There can be two types of root annotations:

  • TextMarkupAnnotation — You can start a new comment thread by selecting some text and tapping the comment menu item (comment icon). In this case, the text markup annotation created will act as a root annotation.

  • InstantCommentMarkerAnnotation — A comment marker annotation is a new annotation which can be added anywhere in the PDF document and can be used to start comment threads.

Getting Started

The PSPDFKit Instant Comments tool is disabled by default. If your PSPDFKit Server license includes it, then you need to explicitly add the .instantCommentMarker annotation type to the editableAnnotationTypes of the PDFConfiguration instance you’re using:

let instantController = InstantViewController(document: pdfDocument, configuration: InstantViewController.defaultConfiguration.configurationUpdated {
    // Add `.instantCommentMarker` to the `editableAnnotationTypes` to enable editing of Instant Comments.
    $0.editableAnnotationTypes?.insert(.instantCommentMarker)
})
PSPDFInstantViewController *instantVC = [[PSPDFInstantViewController alloc] initWithDocument:document configuration:[PSPDFInstantViewController.defaultConfiguration configurationUpdatedWithBuilder:^(PSPDFConfigurationBuilder *builder) {
    // Add `PSPDFAnnotationStringInstantCommentMarker` to the `editableAnnotationTypes` to enable editing of Instant Comments.
    NSMutableSet *editableAnnotationTypes = [builder.editableAnnotationTypes mutableCopy];
    [editableAnnotationTypes addObject:PSPDFAnnotationStringInstantCommentMarker];
    builder.editableAnnotationTypes = editableAnnotationTypes;
}]];

Additionally, we don’t show the comment tool (comment icon) in the annotation toolbar. This is because we want you to think about the workflow you want for your users and then decide whether or not you want to add it in the annotation toolbar. For example, if you want to allow the creation of comments from the annotation toolbar and disable note annotations, you’ll have to customize the annotation toolbar to add a custom button item to the annotation toolbar and remove the note button item. You can read more about this in our Customizing the Annotation Toolbar guide. You can also take a look at the custom annotation toolbar subclass from our ConstructionExample.swift.

Adding a Comment

Since there are two types of root annotations, there are two ways you can add comments using the user interface.

Annotation Creation Menu

comment-long-press-menu

This method involves the creation of InstantCommentMarkerAnnotation before the creation of comments. To add a comment marker, you need to long press at the location on the page where you want to place the comments to invoke the page’s long press menu. Once the long press menu is visible, you’ll find the comment option in it, which you can tap on to add the comment marker at that location in the page.

Using Text Markup Annotations

comment-markup-menu

If you want to add a comment linked to text in the document, you can do so by adding a comment to a text markup annotation. To do this, select some text, then tap on the comment option (comment icon) from the menu. This will present a comment editor where you can add your first comment and start the new thread.

Note that, at the moment, we don’t support the addition of comments or comment marker annotations using programmatic APIs. This is something that might change in future.

Deleting a Comment

You can delete an individual comment by invoking the menu for the comment and tapping the Delete Comment option. If all the comments of a thread are deleted, the corresponding root annotation is automatically deleted.

ℹ️ Note: Comment editing is not supported in the current version.

Disabling New Comment Thread Creation

By default, creating new Instant Comments threads is disabled in the PSPDFKit Instant SDK. The .instantCommentMarker annotation type is not included in the default value of editableAnnotationTypes. Hence, you don’t have to take any additional steps to disable the creation of new Instant Comments threads.