Connect to server (iOS)

Learn how to configure a server to synchronize your files and annotations or setup and try sample server projects.

Server configuration

Configuring server for realtime document collaboration in Xamarin.iOS

This page only applies to Xamarin.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.

Server requirements

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.

Create a new collaboration service

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.

Send updates to the server

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

// Xamarin.iOS csharp coming soon.
// Please see iOS Swift/Obj-C documentation for snippets

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:

// Xamarin.iOS csharp coming soon.
// Please see iOS Swift/Obj-C documentation for snippets

Receive updates from the server

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:

// Xamarin.iOS csharp coming soon.
// Please see iOS Swift/Obj-C documentation for snippets

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:

// Xamarin.iOS csharp coming soon.
// Please see iOS Swift/Obj-C documentation for snippets

Miscellaneous

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.

1. 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.

1. The PTCollaborationServerCommunication protocol does not have any opinion on where/how server login is performed.

Server samples

Server samples for realtime document collaboration in Xamarin.iOS

This page only applies to Xamarin.iOS.

The iOS SDK includes a realtime collaboration sample app with the .dmg download (found in Samples/Other/Collaboration). It includes support for two different back-end servers:

1. A demonstration Apryse collaboration server.
2. Google's Firebase Realtime Database

This guide will step you through running the sample.

Download .dmg

Collaborate with the Apryse Demonstration sServer

The Apryse demonstration server uses WebSockets to communicate annotation changes and messages between the client and the server. The WebSocket API is provided by SocketRocket, and is integrated via CocoaPods.

1. Open the workspace Collaboration.xcworkspace, and run the sample. The device will show the PDF viewer.
2. Check Xcode's sample for a URL you can open in your computer's browser.

Now, when you create annotations on the device or the computer's browser, the annotation will show up on the other.

Collaborate with Firebase Realtime Database

Use Apryse's demonstration Firebase database.

Firebase's Realtime Database is a NoSQL database. Accessing firebase requires Google's Firebase SDK, which is integrated via Cocoapods:

1. Open the workspace Collaboration.xcworkspace.
2. Open the file ViewController.m, and in the method -(void)viewDidAppear:(BOOL)animated, comment out the line of code under "OPTION 1" (which uses the Apryse demonstration server), and uncomment the line under "OPTION 2" (which uses Firebase).
3. Run the sample. The device will show the PDF viewer.
4. Check Xcode's sample for a URL you can open in your computer's browser.

Now, when you create annotations on the device or the computer's browser, the annotation will show up on the other.

Use a different Firebase database.

The firebase sample can be configured to connect to your own Firebase instance. To do this, follow these instructions:

1. If you have not already done so, create a Firebase account.
2. Using the Firebase console, in the Authentication section, under Sign-in method, enable Anonymous sign-in as a provider.
3. Using the Firebase console, in the Database section, create a new Realtime Database.
4. Using the Firebase console, in Project Settings (found by clicking the gear icon), create a new iOS app. Download its config file ("GoogleService-Info.plist"), and replace the sample's file of the same name with the newly downloaded version.
5. Run the project. If you run the project a second time on a different device or simulator, you can collaborate using the 2 (or more) instances of the app.