Automatic and Manual Syncing

By default PSPDFKit Instant automatically synchronizes annotations with your PSPDFKit Sever in real-time. This is configurable, and it can even only sync manually when your app requests this.

Using the network, especially the cellular network, is one of the most energy intensive tasks on mobile devices. While we do our best to minimize the energy impact of Instant, it can be reduced further by disabling listening for changes from the server or by syncing less often after local changes are made.

Syncing after making local changes and listening for server changes can be configured separately. However, syncing always sends all local changes, and fetches all changes from the server. It is not possible to fetch remote changes without pushing local changes, or to push local changes without fetching remote changes.

Automatic Syncing

By default, when you show a document managed by Instant in a PSPDFInstantViewController, real-time syncing of annotations is fully automatic: Instant will push local changes to the server as they happen and will listen for changes from the server.

If you don’t show the document in a PSPDFInstantViewController, you can enable listening for changes using startListeningForServerChanges and stopListeningForServerChanges on the PSPDFInstantDocumentDescriptor.

Instant will use the network efficiently by coalescing changes with a one second delay by default. You can reduce energy consumption at the cost of less immediate syncing by increasing the delayForSyncingLocalChanges property of a document descriptor. Unless syncing after local changes is disabled entirely (see below) if the app enters the background and there are local changes that have not been synced, Instant will attempt to sync immediately.

Disabling Listening for Server Changes

If your app does not require real-time sync it may be better to fetch changes from the server manually to reduce energy consumption — for example, when the view showing the document appears, or with a button the user can tap.

If you show the document in a PSPDFInstantViewController you can disable listening using the shouldListenForServerChangesWhenVisible property, then sync manually whenever you want to by calling syncChanges:. This method is marked with IBAction for easy set up in Interface Builder.

If you use a custom view controller or something else, there’s nothing to do: just sync manually when required by calling sync on the document descriptor.

Disabling Syncing After Local Changes

In addition to disabling listening for changes from the server (see above), you can disable syncing after local changes are made by setting a document descriptor’s delayForSyncingLocalChanges property to the special constant PSPDFInstantSyncingLocalChangesDisabled. This means Instant will never sync annotations with the server unless your app requests this by calling sync or syncChanges: — these do the same thing so use whichever is more convenient for you.

It is possible to configure Instant to not sync after local changes are made, but to listen for changes. This combination makes little sense and is not recommended, as the local changes would be pushed at seemingly random times when changes are received from the server.