MigratoryData Presence API
Developer's Guide and Reference Manual
Developer's Guide

This guide includes the following sections:

Overview

This Application Programming Interface (API) contains all the necessary operations for building presence extensions for MigratoryData Server.

Before reading this manual, it is recommended to read MigratoryData Architecture Guide (PDF, HTML).

Creating a Presence Extension for MigratoryData Server

A typical API usage is as follows:

Step 1 - Import in your application the API as follows:

import com.migratorydata.extension.MigratoryDataPresenceListener;

Step 2 - Implement the interface MigratoryDataPresenceListener

The interface MigratoryDataPresenceListener is available under the folder doc/Extensions/presence/api of the MigratoryData server installation.

Step 4 - Building the jar of the extension

Build a jar consisting in the object code of the class defined at Step 2. In addition, the jar must also include a folder named services in its META-INF folder. Moreover, the folder services must include a file named com.migratorydata.extension.MigratoryDataPresenceListener which must have as content the fully qualified name of the class defined at Step 2.

Step 5 - Install the extension

Rename the JAR built at Step 4 to presence-extension.jar and deploy it to the folder extensions of your MigratoryData server installation.

Step 6 - Configure the MigratoryData server to load the presence extension

In the configuration file of the MigratoryData server, configure the parameter Extension.Presence as follows:

Extension.Presence = true

For deployments using Custom entitlement rules, there are two additional optional parameters that could be configured Extension.Presence.Subject and Extension.Presence.EntitlementToken to enable user presence replication across the cluster. The default value of the parameter Extension.Presence.Subject is /__migratorydata__/presence, and the default value of the parameter Extension.Presence.EntitlementToken is the values of the parameter EntitlementAllowToken. Your custom entitlement rules should allow subscriptions and publications on the subject and entitlement token defined by these two parameters. See MigratoryData Configuration Guide for further details.

Step 7 - Restart the MigratyData server

Step 8 - Assign the external token to a mobile client

In order for a user to be taken into account by the presence extension, the user needs an external token which is typically used by the presence extension to send messages through an external service such as Firebase Cloud Messaging (FCM) or Apple Push Notification Service (APNS) when the user goes offline (e.g. its mobile app goes to background or its mobile devices enters into sleep mode).

The API method MigratoryDataClient.setExternalToken() should be used to attach an external token to a mobile client of the MigratoryData server. This API method is available for the client libraries for Android and iOS.

Examples

An example built with this API is available in the folder doc/Extensions/presence/examples of your MigratoryData server installation. Start with the README file which explains how to compile and run the example.