I am pleased to announce the latest beta release of the Apache Cordova Plugin for Azure App Service Mobile Apps. This plugin provides an API for data access, push registration and authentication to an Azure Mobile App backend written in either Node.js or ASP.NET.

You can find out more about developing an Azure Mobile App backend by referring to the server how-to documentation for ASP.NET or Node.js. You can also generate an Azure Mobile App backend and manage it within the Azure portal by following the simple instructions included in our documentation for the TodoList quick start.

Once you’ve created a service, it's time to create an Apache Cordova client. You will likely have an Apache Cordova client you want to use for this. If you don't then you can use our QuickStart Project.

Installing the Apache Cordova Plugin in your project

The Apache Cordova plugin is installed via the Cordova Plugin command.

cordova plugin add cordova-plugin-ms-azure-mobile-apps

This will make the plugin available in all your supported platforms automatically.

Connecting to the Azure Mobile App backend

The first thing you will want to do is define a connection to the backend service. This is done with the WindowsAzure.MobileServiceClient() call.

var azureConnection = new WindowsAzure.MobileServiceClient('https://mysitename.azurewebsites.net');

All other functions reference this connection object so it's best to store the azureConnection where it can be universally accessible.

Connecting to a SQL Azure Table

To connect to a table:

var tableRef = azureConnection.table('todoitem');

The tableRef object allows you to communicate with the Azure Mobile App backend to read and write to a connected SQL Azure table. Examples include:

var query = tableRef.where({ complete: false });
query.read().then(function (results) {
    var items = $.map(results, function (singleRow) {
        return $('
')
            .attr('data-todoitem-id', item.id)
            .append($('Delete'))
            .append($('').prop('checked', item.complete))
            .append($('
').append($('').val(item.text)));
    });
    $('#listitems').empty().append(items);
});

This example code snippet does a query for incomplete tasks in your todoitem table and produces a series of LI items based on each row of the results table.

You can also connect an event handler that updates an item using the following code snippet.

var isComplete = $(this).prop('checked');
var itemid = $(this).closest('li').attr('data-todoitem-id')
todoItemTable
    .update({ id: itemid, complete: isComplete })
    .then(refreshTodoItems, handleError);

There are similar code snippets for inserting new rows, deleting old rows and changing the text of a todo list.

Authenticating using Azure App Service

After you configur your mobile backend to use Azure App Service Authentication, you can utilize this capability in your Cordova app. Trigger an authentication with the following snippet.

var provider = 'microsoftaccount'; // or facebook,twitter,google,aad
azureConnection.login(provider).done(
    function success(user) {
        console.info('User ' + user + ' has logged in);
    }, function error(error) {
        console.error('Failed to login: ', error);
    });
// azureConnection.currentUser is available after success() is called

Test authentication with an iOS or Android Emulator – the authentication service has limitations when used with the Ripple simulator right now.

Limitations

This is a beta release and we have deliberately optimized this release for Apache Cordova apps running in the emulator or on a device for iOS and Android applications. We understand the authentication flows do not work within Ripple (the standard simulator used when running an Apache Cordova application within Visual Studio).

Authentication flows also do not work when running an Apache Cordova app within an AngularJS based framework like the Ionic framework. We hope to correct both of these issues in a follow-up beta release.

In addition, this plugin does not support Offline Sync capabilities. We will correct this issue prior to general availability for the plugin.

Working with mobile web applications

Mobile web applications utilize a JavaScript library. We are not releasing the associated JavaScript library at this time because the issues with the authentication flows mentioned above also affect browsers in general. We hope to release a JavaScript library for use with mobile web applications at the same time as correcting the authentication flows in Apache Cordova.

Get involved

We are developing our client in the open and our source code repository is available on GitHub. If you have an issue with the code not already addressed by our limitations, please let us know through GitHub Issues.

Get help

We regularly provide assistance through StackOverflow or in the Azure Mobile Services forum. When you post to these forums, please mention the specific version of the Apache Cordova beta plugin you’re using.