aerogear-js Build Status devDependency Status

JavaScript client library implementation for AeroGear. Eventually, this will include API's for persistence, security, data synchronization and more. For more information and downloads, visit AeroGear.org.

Authorization

This api has been deprecated and removed as of 2.1.0. To use it you will need the latest 1.x release, which can be found here)

Auth

This api has been deprecated. To use it you will need the latest 1.x release, which can be found here)

Crypto

The AeroGear.Crypto namespace provides a straightforward API to provide an easy to use cryptography interface for data encryption and decryption.

See the Crypto API Docs for more info.

DataManager

A collection of data connections (stores) and their corresponding data models. This object provides a standard way to interact with client side data no matter the data format or storage mechanism used.

See the DataManager API docs for more info.

Notifier

This api has been deprecated as of 2.1.0 and will be removed in a future version

Notifier is a collection of adapters which provide a unified or similar API for interacting with different messaging services and protocols.

See the Notifier API docs for more info.

Pipeline

This api has been deprecated. To use it you will need the latest 1.x release, which can be found here)

SimplePushClient

SimplePushClient is a client implementation and polyfill for the Mozilla SimplePush specification. SimplePush allows for simple push notification support in web, as well as Firefox OS, applications. This implementation does differ slightly from the specification in that it only works in applications that are "online" and active in the browser. This implementation also supports connecting to both Mozilla's SimplePush server as well as the AeroGear project's server.

See the SimplePushClient API docs for more info. Also, please see the Mozilla SimplePush specification for more info on SimplePush.

Diff Sync

The Diff Sync client and server are based on an implementation of Google's Differential Synchonrization by Neil Fraser.

The DiffSyncClient connects to the AeroGear Sync Server

The DiffSyncEngine is responsible for the algorithm logic - there are two adapters available: JSON Patch and DiffMatchPatch.

UnifiedPushClient

UnifiedPushClient is used in conjunction with AeroGear's UnifiedPush server to register web applications for push notifications. Using the SimplePushClient, a web application can register for push notifications from a SimplePush network and then inform the UnifiedPush server as to where it should send those push notifications.

See the UnifiedPushClient API docs for more info.

Feature Stability

All features of the library are given a stability rating which is noted in the documentation for that feature. The stability ratings are as follows:

  • Experimental - This feature is new and has not been thoroughly tested outside of development. This feature could be changed or removed at any time. Use of these features in a production environment is at your own risk.
  • Stable - This feature has existed for a full release cycle and has been thoroughly tested. These features are considered safe for use in production environments.
  • Deprecated - This feature is being removed or replaced. As with experimental features, these features could be removed at any time and their use in production environments is at your own risk. For features being replaced, it is recommended to update to the next version and begin using the new feature.

Library Dependencies

Some parts of AeroGear.js depend on external libraries which are not bundled in the same file. Below is a list of each plugin and their adapters along with external dependencies, if they have any. It is recommended to use the latest stable version of each dependency unless otherwise noted.

Crypto

  • SJCL - bundled w/ AeroGear.js

DataManager

Notifier

SimplePush

UnifiedPush

Diff Sync

Building

Grunt

Grunt is used as the build tool which requires Node.js version >= 0.10. Please refer to nodejs.org for details regarding installing Node.js. Please refer to Grunt's getting started guide for details regarding installing Grunt.

Installing Build Dependencies

To install the dependencies of the project run the following command:

$ npm install

This will install the versions of the dependencies declared in package.json. This is only required to be done once before building the first time, or if the dependencies in package.json have been updated.

Building the project

$ grunt

The produced JavaScript will be in the dist directory.

Custom Build

There is a special grunt task called, custom to help create custom builds of the library.

The custom task takes a comma delimited list of "modules".

For example, if you wanted a build with Authorization/OAuth2 and the SimplePushClient, you would do

$ grunt custom:oauth2,simplePush

The produced JavaScript will be in the dist directory as aerogear.custom.js.

For usage and a list of available "modules" run,

$ grunt custom:help

Generating the documentation

To generate the API docs, run the following command:

$ jsdoc-aerogear src/ -r -d docs README.md

or by running the grunt docs task

$ grunt docs

The docs use a slightly modified version of jsdoc

Documentation

For more details about the current release, please consult our documentation.

Development

If you would like to help develop AeroGear you can join our developer's mailing list, join #aerogear on Freenode, or shout at us on Twitter @aerogears.

Also takes some time and skim the contributor guide

Questions?

Join our user mailing list for any questions or help! We really hope you enjoy app development with AeroGear!

Found a bug?

If you found a bug please create a ticket for us on Jira with some steps to reproduce it.