2017.8 Migration Guide | Seamless PSPDFKit Server Upgrade | Nutrient

PSPDFKit for Web 2017.8 changes annotation IDs from integers to strings.

This requires that all clients (iOS, Android, and Web) and PSPDFKit Server are updated to the latest version at the same time.

How Will Instant Clients React to Incompatible Server Versions?

Older native Instant clients will no longer be able to connect. New clients connecting to the old server will also refuse to connect. Our protocol check ensures that the server version is compatible and thus prevents any mismatch or potential data loss.

Instant clients starting with PSPDFKit 7.1 for iOS and PSPDFKit 4.1 for Android show a more specific error message reporting the server mismatch and show a message to the user. Older clients will report a more generic “invalid request” error and do not show a message to the user.

Why Was This Change Necessary?

This change was required to immediately create a unique identifier as soon as annotations are created, without the requirement to sync data first. This was a highly requested feature and allows you to map custom data to annotation data at creation time, without sync state tracking and error-prone updating of temporary IDs.

What You Will Have to Do

  1. We recommend rolling out updated Instant clients with PSPDFKit 7.1 for iOS and PSPDFKit 4.1 for Android to improve the error experience.

  2. Once this rollout is complete, prepare apps with the new version of the Instant clients (PSPDFKit 7.2 for iOS and PSPDFKit 4.2 for Android).

  3. Roll out the new apps and update the server at the same time. Users who haven’t updated their native clients will get an error message. No data will be lost.

We realize this is tricky to orchestrate, and we are working on better interoperability between different client and server versions as Instant matures.

Annotation API Changes

  • During the migration, all annotation records will have their id casted to string. For an annotation with id 1234, the new string ID will also be "1234".

  • The ids returned from all annotation endpoints will now be of type string.

For more detail, check out our updated Annotation guides.

Migrate PSPDFKit for Web

For more information, please take a look at the PSPDFKit for Web 2017.8 Migration Guide.

For a full list of changes, check out the changelog.