Important Notice
This project is not abandoned or inactive. On 20th Feb 2019, major updates will be pushed.
Updates:
- Native Support for iOS & Windows (UWP only)
- New API
- SSL/TLS support on Android, iOS & Windows
- Better config validation.
- Resolution of bugs
cordova-plugin-mqtt is plugin for building MQTT client for multiple platforms in Apache Cordova. Currently Android platform is present and next support is planned for iOS & Windows Phone.
5.x (CLI) 4.x (Cordova Android) & above.
From v0.3.x, the eventListner implementation shall be deprecated. Kindly take a note of this.
Install plugins via plugin repository or GitHub
$ cordova plugin add cordova-plugin-mqtt$ cordova plugin add https://github.com/arcoirislabs/cordova-plugin-mqtt.git- Adding temporary support to iOS platform until a stable native support arrives.
[UPDATE]
We have written a tutorial for this plugin over here. Kindly check out before you start developing. Cheers
Default listeners you can program anywhere for following events
- connected
- disconnected
- failure (connection)
- subscribed
- not subscribed
- published
- not published
For example you can configure the event in this way
//Deprecated
document.addEventListener("connected",function(e){
console.log(e.type)
},false)To connect to a broker. This plugin doesn't supports mqtt:// protocol. Use tcp:// instead.
cordova.plugins.CordovaMqTTPlugin.connect({
url:"tcp://test.mosquitto.org", //a public broker used for testing purposes only. Try using a self hosted broker for production.
port:1883,
clientId:"YOUR_USER_ID_LESS_THAN_24_CHARS",
connectionTimeout:3000,
willTopicConfig:{
qos:0, //default is 0
retain:true, //default is true
topic:"<will topic>",
payload:"<will topic message>"
},
username:"uname",
password:'pass',
keepAlive:60,
isBinaryPayload: false, //setting this 'true' will make plugin treat all data as binary and emit ArrayBuffer instead of string on events
success:function(s){
console.log("connect success");
},
error:function(e){
console.log("connect error");
},
onConnectionLost:function (){
console.log("disconnect");
},
routerConfig:{
router:routerObject //instantiated router object
publishMethod:"emit", //refer your custom router documentation to get the emitter/publishing function name. The parameter should be a string and not a function.
useDefaultRouter:false //Set false to use your own topic router implementation. Set true to use the stock topic router implemented in the plugin.
}
})To publish to a channel. You can use this function.
cordova.plugins.CordovaMqTTPlugin.publish({
topic:"sampletopic",
payload:"hello from the plugin",
qos:0,
retain:false,
success:function(s){
},
error:function(e){
}
})In order to debug the publish call you can either go for callbacks in the function or events. Once published the function will call the "published" event & the success callback else the function will call both "not published" event & error callback.
To subscribe to a channel. You can use this function. You can also use wildcard based subscription using following ways
//Simple subscribe
cordova.plugins.CordovaMqTTPlugin.subscribe({
topic:"sampletopic",
qos:0,
success:function(s){
},
error:function(e){
}
});
//Single level wildcard subscribe
cordova.plugins.CordovaMqTTPlugin.subscribe({
topic:"/+/sampletopic",
qos:0,
success:function(s){
},
error:function(e){
}
});
//multi level wildcard subscribe
cordova.plugins.CordovaMqTTPlugin.subscribe({
topic:"/sampletopic/#",
qos:0,
success:function(s){
},
error:function(e){
}
});
//Using both kinds of wildcards
cordova.plugins.CordovaMqTTPlugin.subscribe({
topic:"/+/sampletopic/#",
qos:0,
success:function(s){
},
error:function(e){
}
})The success callback can notify you once you are successfully subscribed, so it will be called only once. The onPublish method is deprecated. If you want to read the payload, you can listen to the event by the name of the topic. For example if you have subscribed to the topic called "sampletopic". You can read the payload in this way.
#####Update:- We are introducing topic pattern support to listen to certain topics in a way the developer wishes to. This topic pattern helps developer to make a common listener to different topics sharing same levels using single and multi-level wildcards.
//Deprecated
document.addEventListener("sampletopic",function(e){
console.log(e.payload)
},false);
//New way to listen to topics
cordova.plugins.CordovaMqTTPlugin.listen("/topic/+singlewc/#multiwc",function(payload,params){
//Callback:- (If the user has published to /topic/room/hall)
//payload : contains payload data
//params : {singlewc:room,multiwc:hall}
})To unsubscribe to a channel. You can use this function.
cordova.plugins.CordovaMqTTPlugin.unsubscribe({
topic:"sampletopic",
success:function(s){
},
error:function(e){
}
})This function will also fire the unsubscribe event which yiu can listen to using the document.addEventListener function. Also the event listener for the topic is removed automatically once the client successfully unsubscibes.
To disconnect yourself from a server, use following function
cordova.plugins.CordovaMqTTPlugin.disconnect({
success:function(s){
},
error:function(e){
}
})This function provides you the access to all the topic router functions you have used. If you have used a the stock topic router you can access the payload for a topic by this method.
//Declare this function in any scope to access the router function "on" to receive the payload for certain topic
cordova.plugins.CordovaMqTTPlugin.router.on("/topic/+singlewc/#multiwc",function(payload,params){
//Callback:- (If the user has published to /topic/room/hall)
//payload : contains payload data
//params : {singlewc:room,multiwc:hall}
});
//To get a callback on topic subscribe/unsubscribe event, you can listen by this method
cordova.plugins.CordovaMqTTPlugin.router.onadd(function(topic){
});
cordova.plugins.CordovaMqTTPlugin.router.onremove(function(topic){
});This function lets you listen to certain topic pattern specifically constructed by topic patters as shown below.
//Declare this function in any scope to access the router function "on" to receive the payload for certain topic
cordova.plugins.CordovaMqTTPlugin.listen("/topic/+singlewc/#multiwc",function(payload,params){
//Callback:- (If the user has published to /topic/room/hall)
//payload : contains payload data
//params : {singlewc:room,multiwc:hall}
});
- Add a stable iOS support in v0.3.0
- Plan support for new platform (Windows Phone)
- Add background service support in Android version to save the payload related from certain topics in a DB when the app is in background.
MIT