Storing Custom Data in an Annotation

When adding an annotation to a document, PSPDFKit allows storing of additional data that you can specify for each annotation. This data is persistently stored along with the annotation if the annotation is stored in one of the following formats:

  1. Embedded in the PDF

  2. Instant JSON

  3. XFDF

  4. NSCoding-based serialization of Annotation

PSPDFKit automatically handles the serialization of the custom data attached to an annotation for these formats.

Storing Custom Data

PSPDFKit 8.3 for iOS added the customData property to Annotation. This property allows you to store an arbitrary JSON-compliant dictionary in an annotation, like so:

let restaurantInfo: [String: Any] = [
    "name": "Grill House",
    "locations": ["Vienna", "Paris", "New York"],
    "rating": 5,
    "verified": true
]

// The `customData` property is available on all subclasses of `Annotation`.
annotation.customData = restaurantInfo
NSDictionary<NSString *, id> *restaurantInfo = @{
    @"name": @"Grill House",
    @"locations": @[@"Vienna", @"Paris", @"New York"],
    @"rating": @5,
    @"verified": @YES
};

// The `customData` property is available on all subclasses of `Annotation`.
annotation.customData = restaurantInfo

This dictionary is saved to the annotation provider that the annotation belongs to when the document is saved. PSPDFKit does not use this property internally for any reason; you have complete control over its contents.

In addition, the dictionary can only have String keys, and all its values must be serializable to JSON — that is, they must be of the type String, NSNumber, Dictionary, Array, or NSNull. The numbers should not be NaN or infinity. If calling JSONSerialization.isValidJSONObject(_:) on the dictionary does not return true, setting it to customData will result in an exception being raised.

In addition to PSPDFKit’s automated handling of customData when stored to the locations mentioned above, customData is also serialized when using NSKeyedArchiver or Annotation.generateInstantJSON().