Configuring server for realtime document collaboration on iOS

Support for realtime collaboration is included with the SDK, including demonstration implementations for using WebViewer Server and Firebase as a central server. You may consult these implementations in the Collaboration Sample as reference implementations (found in the .dmg download at /Samples/Other/Collaboration/Collaboration/, TRNWebViewerServerService.m and TRNFirebaseCommunicationService.m).

This guide will demonstrate how to add support for a new realtime collaboration server in an iOS app.

In realtime collaboration, the role of the server is to:

• Store the annotations associated with a given document (these are provided by the SDK in an XML format)
• Send the annotations for a particular document to a user when requested
• Accept annotation creation/modification/deletion events from a user
• Broadcast annotation create/modification/deletion events to a user

If your server is capable of the above, it can serve as the back-end to Apryse's realtime collaboration.

This guide will explain how to configure an iOS app to interface with a server that fulfils the above requirements.

To add support for a new server backend, you need to implement a single class, referred to here as the Collaboration Service. The purpose of the Collaboration Service object is to mediate between the server and the Apryse SDK. The Collaboration Service translates messages received from the server in its data format (for example json data) into to a format that the SDK understands (specifically a PTCollaborationAnnotation), and vice versa.

A Collaboration Service must implement the PTCollaborationServerCommunication protocol. The purpose of each API defined in the protocol will be described in the sections below.

The Collaboration Service implements 3 methods defined in PTCollaborationServerCommunication in order to process changes made on the device:

1-(void)localAnnotationAdded:(PTCollaborationAnnotation*)collaborationAnnotation;
2-(void)localAnnotationModified:(PTCollaborationAnnotation*)collaborationAnnotation;
3-(void)localAnnotationRemoved:(PTCollaborationAnnotation*)collaborationAnnotation;

1func localAnnotationAdded(_ collaborationAnnotation: PTCollaborationAnnotation)
2func localAnnotationModified(_ collaborationAnnotation: PTCollaborationAnnotation)
3func localAnnotationRemoved(_ collaborationAnnotation: PTCollaborationAnnotation)

Each of these methods is called by the PTCollaborationManager to communicate when a change has occurred on the device. They pass an object of type PTCollaborationAnnotation, which the collaboration service must then convert to a format appropriate for the server, and sends it to the server.

Here is a theoretical example:

1-(void)localAnnotationModified:(PTCollaborationAnnotation*)collaborationAnnotation
2{
3    MYServerMessage* serverMessage = [[MYServerMessage alloc] init];
4    
5    serverMessage.action = @"annotationModified";
6    serverMessage.xfdf = collaborationAnnotation.xfdf;
7    serverMessage.annotationID = collaborationAnnotation.annotationID;
8    serverMessage.userID = self.userID;
9    
10    [self.myServer sendMessage:serverMessage];
11}

1func localAnnotationModified(_ collaborationAnnotation: PTCollaborationAnnotation) {
2    let serverMessage = MYServerMessage()
3
4    serverMessage.action = "annotationModified"
5    serverMessage.xfdf = collaborationAnnotation.xfdf
6    serverMessage.annotationID = collaborationAnnotation.annotationID
7    serverMessage.userID = userID
8
9    myServer.send(serverMessage)
10}

Likewise, the collaboration service is responsible for receiving updates from the server and communicating them to the Collaboration Manager, referenced in its PTCollaborationManager property.

This is done by calling the following Collaboration Manager methods:

1-(void)remoteAnnotationAdded:(PTCollaborationAnnotation*)collaborationAnnotation;
2-(void)remoteAnnotationModified:(PTCollaborationAnnotation*)collaborationAnnotation;
3-(void)remoteAnnotationRemoved:(PTCollaborationAnnotation*)collaborationAnnotation;

1func remoteAnnotationAdded(_ collaborationAnnotation: PTCollaborationAnnotation)
2func remoteAnnotationModified(_ collaborationAnnotation: PTCollaborationAnnotation)
3func remoteAnnotationRemoved(_ collaborationAnnotation: PTCollaborationAnnotation)

As in the localAnnotationAdded/Modified/Removed methods described in the previous section, these methods take a PTCollaborationAnnotation parameter. It is the job of the collaboration service to receive a server message, translate it into a PTCollaborationAnnotation object, and call the appropriate method.

Here is a theoretical example:

1-(void)didReceiveServerJson:(NSString*)serverJson
2{
3    MYServerMessage* serverMessage = [[MYServerMessage alloc] initFromJson:serverJson];
4
5    PTCollaborationAnnotation* collabAnnot = [[PTCollaborationAnnotation alloc] init];
6
7    collabAnnot.xfdf = serverMessage.xfdf;
8    collabAnnot.userName = serverMessage.authorName;
9    collabAnnot.annotationID = serverMessage.annotationID;
10    collabAnnot.userID = serverMessage.userID;
11    collabAnnot.parent = serverMessage.parent;
12    collabAnnot.documentID = serverMessage.documentID;
13
14    if( [serverMessage.action isEqualToString:@"annotationAdded"] )
15    {
16        [self.collaborationManager remoteAnnotationAdded:collabAnnot];
17    }
18    else if( [serverMessage.action isEqualToString:@"annotationModified"] )
19    {
20        [self.collaborationManager remoteAnnotationModified:collabAnnot];
21    }
22    else if( [serverMessage.action isEqualToString:@"annotationRemoved"] )
23    {
24        [self.collaborationManager remoteAnnotationRemoved:collabAnnot];
25    }
26
27}

1func didReceiveServerJson(_ serverJson: String) {
2    let serverMessage = MYServerMessage(fromJson: serverJson)
3
4    let collabAnnot = PTCollaborationAnnotation()
5
6    collabAnnot.xfdf = serverMessage.xfdf
7    collabAnnot.userName = serverMessage.authorName
8    collabAnnot.annotationID = serverMessage.annotationID
9    collabAnnot.userID = serverMessage.userID
10    collabAnnot.parent = serverMessage.parent
11    collabAnnot.documentID = serverMessage.documentID
12
13    if (serverMessage.action == "annotationAdded") {
14        collaborationManager.remoteAnnotationAdded(collabAnnot)
15    } else if (serverMessage.action == "annotationModified") {
16        collaborationManager.remoteAnnotationModified(collabAnnot)
17    } else if (serverMessage.action == "annotationRemoved") {
18        collaborationManager.remoteAnnotationRemoved(collabAnnot)
19    }
20}

1. The PTCollaborationServerCommunication, which a Collaboration Service must conform to, defines three other required APIs:
   • Property collaborationManager. This should be assigned to the instance of the PTCollaborationManager that exists on a PTToolManager. This is done automatically if using a PTCollaborationDocumentViewController, described below.
   • Method -(void)documentLoaded. This method is intended to be called when a document is first loaded, and so when invoked the service should send all of the document's annotations to the collaborationManager's remoteAnnotationAdded: method.
   • Method (NSString*)userID, which returns the server's unique ID associated with the user. This can be used by the local viewer to restrict which annotations a user can edit.
2. The tools framework includes a class PTCollaborationDocumentViewController, which inherits from the standard PTDocumentController, that implements two useful functions for collaboration:
   • Its constructor takes a PTCollaborationServerCommunication object, and automatically connects it with its PTCollaborationManager.
   • It prevents the user from selecting (and thus editing) annotations that they did not create.
3. The PTCollaborationServerCommunication protocol does not have any opinion on where/how server login is performed.