Javascript Library Documentation


Catapush allows a reliable and traceable push notification service. This library can be used to add the Catapush service in an html project. In particularly, the client will connect to the Catapush XMPP server through the Bidirectional-streams Over Synchronous HTTP (BOSH) protocol.

Download

The library can be downloaded here: full version, minified version. If you are using npm (package.json) you can install it with:

npm install catapush

Usage

Load the library and its dependencies:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/strophe.js/1.2.6/strophe.min.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/ydn.db/0.9.2/ydn.db-isw-core-qry.js"></script>
<script type="text/javascript" src="https://npmcdn.com/catapush/dist/catapush.min.js"></script>

Start the library, connect using an existing Catapush user

var appKey = '2e8a6bdf6ac5c414500e5f91c33r478a'; // appkey (retrieved from the app panel)
var platform = catapush.PLATFORM.ANDROID; // environment
var user = 'test'; // user / identifier
var password = 'test'; // password

// Get a new instance
var catapush = Catapush.get();

// Configure
catapush.setApp(appKey, platform).setUser(user, password);

// Event on connection established
catapush.onConnected(function() {
    console.log('Connected');
});
// Event on disconnection
catapush.onDisconnected(function() {
    console.log('Disconnected');
});
// Event on message received
catapush.onMessageReceived(function(message) {
    console.log('Message received', message);

    // Send message read
    catapush.setMessageRead(message.id);
});
// Retrieve latest received messages
catapush.getLastMessages(10, function(lastMessages) {
    for (var i = 0; i < lastMessages.length; i++) {
        console.log('Last message ' + i, lastMessages[i]);
    }
});
// Connect
catapush.start();

API

Constants

  • PLATFORMS - possible environments

Methods

  • setApp(appKey, platform) - setup application key and platform
  • setUser(user, password) - setup mobile user and password
  • connect() - connect to the xmpp backend
  • getLastMessages(limit, callback) - retrieve last messages retrieved
  • getMessagesFromMessageId(limit, previous, fromMessageId, callback) - retrieve messages received before or after an other message
  • setMessageRead(messageId, callback) - set a message as read
  • resetStorage() - reset all stored data
  • resetConnection() - reset xmpp connection
  • updatePushToken() - update push token (for mobile devices)

Events

  • onConnecting (callback) - on connecting to xmpp
  • onConnected (callback) - after successfull connection to xmpp
  • onDisconnected (callback) - after disconnection from xmpp
  • onReconnected (callback) - after reconnection to xmpp due to a network problem
  • onUserSet(callback) - after global authentication
  • onMessageReceived(callback) - message received
  • onConnectError(callback) - connection error

Dependencies

The app depends on three libraries:

  • jQuery - v. 1.7.0 and higher - a fast, small, and feature-rich JavaScript library;
  • Strophe.js - v. 1.2.6 and higher - an XMPP library for JavaScript. Its primary purpose is to enable web-based, real-time XMPP applications that run in any browser;
  • ydn-db - v. 0.9.2 and higher - Javascript database library for IndexedDB, WebSQL and WebStorage.

Can also been installed using npm (package.json):

..
  "dependencies": {
    "jquery": "*",
    "strophe.js": "*",
    "ydn.db": "*"
  },
..

Related projects

  • jQuery Widget - a jQuery plugin that shows the message received;
  • Phonegap / Cordova library - based on the jQuery Widget, contains a set of tools to implement native push notification.