Catapush NPM | npm.io

Catapush Javascript Library

Introduction

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)
sendMessage() - send a message (2way)
uploadFile() - upload a file to the cdn
logoutStoredUser() - resetConnection,resetStorage and removes remote token

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
onMessageSentReceiptReceived(callback) - received a receipt after sending a 2way message

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.