CommonTime Infinity Messaging

These are the messaging plugins for CommonTime Infinity imported from CommonTime mDesign 8, designed to be publicly available.

To add the plugins to your project, use:

cordova plugins add https://github.com/commontime/com.commontime.cordova.public.messaging.git

or

<plugin name="com.commontime.cordova.public.messaging" spec="https://github.com/commontime/com.commontime.cordova.public.messaging.git" />

There are currently four plugins, one generic and three specific:

• plugins.notify, which provides the generic messaging system
• plugins.asb, which provides the Azure Service Bus (ASB) messaging system
• plugins.rest, which provides the REST messaging system
• plugins.zumo, which provides the Azure App Services messaging system (based on the old Azure Mobile Services, aka ZUMO)

Preferences

The plugins.notify plugin has a single preference, the default push system. This can be specified in the config.xml file, e.g.:

<preference name="defaultPushSystem" value="azure" />

or in or using the setOptions method of the notify plugin. Possible values are "asb", "rest" or "zumo". If this is not specified, you will not be able to receive messages and any sent messages must explicitly set the provider.

The ASB plugin has a number of preferences, which configures the ASB instance. These can be specified in config.xml, for e.g.:

<preference name="sbHostName" value="servicebus.windows.net" />
<preference name="serviceNamespace" value="qa-commontime-sas" />
<preference name="sasKeyName" value="RootManageSharedAccessKey" />
<preference name="sasKey" value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=" />
<preference name="brokerType" value="queue" />
<preference name="brokerAutoCreate" value="true" />

or provide the parameters to the start method of the plugins.asb class.

The REST plugin has no preferences.

The ZUMO plugin has a number of preferences, which configures the ASB instance. These can be specified in config.xml, for e.g.:

<preference name="zumoUrl" value="..." />
<preference name="zumoApplicationKey" value="..." />
<preference name="zumoAuthenticationMethod" value="..." />
<preference name="zumoUseBlobStorage" value="..." />

or provide the parameters to the start method of the plugins.zumo method.

Note, the start method must be called to start sending and receiving notifications for a particular provider.

Calls

plugins.notify.setOptions

var options =
{
  defaultPushSystem: "azure.servicebus"
};

plugins.notify.setOptions(function() { /* success */ }, function(message) { /* error */}, options);

Sets general options for the notification plugins. Currently, only one option is supported, defaultPushSystem, and that only has three values: "azure.servicebus", "rest" or "azure.appservices".

plugins.asb.start

var options =
{
  sbHostName: "servicebus.windows.net",
  serviceNamespace: "commontime-test",
  sasKeyName: "RootManageSharedAccessKey",
  sasKey: "xxxxxxxx",
  brokerType: "queue",
  brokerAutoCreate: true
};

plugins.asb.start(function() { /* success */ }, function(message) { /* error */}, options);

To use the preferences supplied in the config.xml, omit the options parameter.

plugins.rest.start

plugins.rest.start(function() { /* success */ }, function(message) { /* error */});

plugins.zumo.start

var options =
{
  url: "...",
  authenticationMethod: "...",
  applicationKey: "...",
  useBlobStorage: true
};

plugins.zumo.start(function() { /* success */ }, function(message) { /* error */}, options);

To use the preferences supplied in the config.xml, omit the options parameter.

plugins.zumo.logout

plugins.zumo.logout(function() { /* success */ }, function(message) { /* error */});

plugins.notify.addChannel

plugins.notify.addChannel( "newchannel", function( error, channel ) {
  if( error !== null ) console.error(error);
});

plugins.notify.removeChannel

plugins.notify.removeChannel( "oldchannel", function( error, channel ) {
  if( error !== null ) console.error(error);
});

plugins.notify.listChannels

plugins.notify.listChannels( function( error, channels ) {
  if( error !== null ) console.error(error);
  console.dir(channels);
});

plugins.notify.sendMessage

var message = {
  "channel":"newchannel",
  "subchannel":"control",
  "provider": "azure.servicebus", // or "azure.appservices" or "rest"
  "expiry":0,
  "notification": "",
  "content": {"some":"data"}
};

plugins.notify.sendMessage( message, function( error, messageId ) {
  if( error !== null ) console.error(error);
});

plugins.notify.getMessages

plugins.notify.getMessages( "newchannel", "control", function( error, messages ) {
  if( error !== null ) console.error(error);
  console.dir(messages);
});

plugins.notify.getUnreadMessages

plugins.notify.getUnreadMessages( "receiver1", "newchannel", "control", function( error, messages ) {
  if( error !== null ) console.error(error);
  console.dir(messages);
});

plugins.notify.deleteMessage

plugins.notify.deleteMessage( "e4a8e56a-c10a-4454-b9a9-1dd3f2bd0b4f", function( error, messageId ) {
  if( error !== null ) console.error(error);
});

plugins.notify.receiveMessageNotification

plugins.notify.receiveMessageNotification( "receiver1", "newchannel", "control", function( error, message ) {
  if( error !== null ) console.error(error);
  console.dir(message);
});

plugins.notify.cancelMessageNotification

plugins.notify.cancelMessageNotification( "receiver1", function( error, receiver ) {
  if( error !== null ) console.error(error);
});

plugins.notify.cancelAllMessageNotifications

plugins.notify.cancelAllMessageNotifications( function( error ) {
  if( error !== null ) console.error(error);
});

plugins.notify.messageReceivedAck

plugins.notify.messageReceivedAck( "receiver1", "e4a8e56a-c10a-4454-b9a9-1dd3f2bd0b4f", function( error ) {
  if( error !== null ) console.error(error);
});

plugins.notify.receiveInboxChanges

plugins.notify.receiveInboxChanges( "receiver1", function( error, result ) {
  if( error !== null ) { console.error(error); return; }
  console.log( "Action: " + result.action);
  console.dir( result.message );
});

plugins.notify.cancelReceiveInboxChanges

plugins.notify.cancelReceiveInboxChanges( "receiver1", function( error ) {
  if( error !== null ) console.error(error);
});

plugins.notify.receiveOutboxChanges

plugins.notify.receiveOutboxChanges( "receiver1", function( error, result ) {
  if( error !== null ) { console.error(error); return; }
  console.log( "Action: " + result.action);
  console.dir( result.message );
});

plugins.notify.cancelReceiveOutboxChanges

plugins.notify.cancelReceiveOutboxChanges( "receiver1", function( error ) {
  if( error !== null ) console.error(error);
});

Testing

There are frameworks to test the REST and Azure Mobile Services (ZUMO) functionality under the test directory. Create a new Cordova app; add this plugin; replace the index.html and www/index.js with those found in the appropriate test subdirectory (either test/rest or test/zumo); and build and run. Further instructions are contained within the app itself.

The REST test performs a simple GET REST request to the Star Wars API.

The Azure Mobile Services (ZUMO) test performs some requests against the ct-testteam Azure Mobile Service (https://ct-testteam.azure-mobile.net/).

• The message test calls the message API method, which returns a simple JSON object. Application Key authentication is required.
• The messageauth test calls the messageauth API method, which returns a simple JSON object. Azure Active Directory authentication is required. You can use [email protected] with password T35tUser.
• The photo test takes a photo, uploads it to blob storage, and calls the photo API method. Azure Active Directory authentication is required. Note, if you wish to use this you'll have to add the cordova-plugin-camera plugin to the project.