The function start accepts connection settings and opens new connection. Here opt – it’s an object with connecting options.
cometApi.start({dev_id:15, user_id:1, user_key:"userHash", node:"app.comet-server.ru"})
To reconnecting to server use the restart function.
cometApi.restart({dev_id:15, user_id:1, user_key:"userHash"})
To reconnecting you can override connection parameters or left ‘em previous.
The function subscription adds subscribes on channel, events and delivery reports.
cometApi.subscription("channel_name", function(data){ console.log(data) } )
Pay attention that as the body of message may be json line. If it’s true then is can automatically converted to object.
cometApi.subscription( "pipe_name.event_name", function(e){ console.log(["event", e])})
Subscription on channel “channel_name”
cometApi.subscription("channel_name", function(e){ console.log(e)})
Subscription on channel’s events “event_name”on channel “channel_name”
cometApi.subscription("channel_name.event_name", function(e){ console.log(e)})
Subscription on delivery report on channel “channel_name”
cometApi.subscription("#channel_name", function(e){ console.log(e)})
Subscription on all incoming messages from all of the channels which subscribed current client
cometApi.subscription(function(e){ console.log(e)})
An example with online demo How to accept message from channel in JavaScript
The subscription function returns the subscription_id line which can be necessary if we want to unsubscribe of receiving messages.
var subscriptionId = cometApi.subscription("channel_name.event_name", function(e){ console.log(e)})
For unsubscription of receiving messages, call:
cometApi.unsubscription(subscriptionId)
The main article reserved channel names.
Also we already have some channels with extra properties:
The subscription on messages from server, delivered in order to authorization data (by user’s id):
cometApi.subscription("msg", function(e){ console.log(e)})
The subscription on messages from server with event name “event_name”, delivered in order to authorization data (by user’s id):
cometApi.subscription("msg.event_name", function(e){ console.log(e)})
It is possible to subscribe from JS on notifications about some user’s activity on comet server.
When user has authorized on comet server then server automatically sends a signal to channel user_status_{user_identifier} with event name online. When user is went offline, server generates some event too.
// Subscribe on notification that user with id=12 is online cometApi.subscription("user_status_12.online", function(event) { console.log("User with id=12 online") }) // Subscribe on notification that user with id=12 is offline cometApi.subscription("user_status_12.offline", function(event) { console.log("User with id=12 offline") })
Channels with a name like track_* automatically generate events subscription and unsubscription inside every time someone subscribes or unsubscribes from this channel
cometApi.Subscription("track_online.subscription", function(msg) { // Event Processing that someone went to the website and subscribe to the channel track_online }); cometApi.Subscription("track_online.unsubscription", function(msg) { // Event Processing that someone left the site and / or unsubscribe from the channel track_online });
This type of channel is designed specifically to facilitate the creation of dynamically updated lists of online users. Main article list of online users
The function web_pipe_send allows sending messages from JavaScript to channel by passing your server (directly calls comet server). It allows resending messages between clients without loading your server. Also, owing to direct call to comet server, delivery time of message from client to client is minimal.
cometApi.web_pipe_send("web_pipe_name", "event_name", "message")
To getting a report about message delivery to channel “channel_name” use “subscription”.
cometApi.subscription("#channel_name", function(e){ console.log(e)})
Since comet server supports users’ authorization, it automatically adds user id to message such a way that a sender can’t send foreign id. To deactivate this option, is needed to add symbol “@” before channel name which would accept message. In this case, delivered message would be look alike that it was sent by non-authorized user.
cometApi.web_pipe_send("@web_pipe_name", "event_name", "message")
data: {} // User’s message
server_info:
event: "undefined" // Event name
history: false // If true then it’s the data downloaded from channel’s history, not incoming at that moment
marker: undefined // Special identifier, implemented just only when history equals true
pipe: "web_chat_pipe" // Channel’s name which directed message
user_id: 0 // Sender id, if=0 then is omitted. It will be add automatically if sender was authorized on comet server.
Field server_info.user_id in incoming message fills out by some information besides zero just if message was sent to channel from JavaScript API and sender was authorized on comet server. Also, it contains sender’s user_id.
The comet server includes possibility to activated storing the last N messages mechanism for some channels.
If logging function is active, then method call “get_pipe_log” initiate sending all messages from history to client.
cometApi.get_pipe_log("web_pipe_name")
Delivered from history messages will have a property “history=true”.
The function “count_user_in_pipe” can help to determine a number of subscribes for current channel.
Also, this function has the first argument – name of channel and the second is callback function which holds an answer.
cometApi.count_users_in_pipe("web_chat_pipe", function(res) { console.log("count_users_in_pipe", res, res.data.user_in_pipe) })
Besides of CometQL query, this function can show a number of subscribers only for those channels which names begin with “web_” (for example, for “web_chat_pipe” it will work but for “chat_pipe” – will not work). This limitation entered in order to be able to create such a channel which a number of subscribers can’t be accessible for anyone via JS API.
The main article An authorization on comet server
The comet server has an opportunity to authorize users. An authorizing can be useful for determination of sender, who create message.
You can track down changing authorization status on comet server from JavaScript API.
// Adding the callback function for notification about successful authorization cometApi.onAuthSuccess(function(){ console.log("Connection and authorization were successful") }) // Adding the callback function for notification about unsuccessful authorization cometApi.onAuthFalill(function(){ console.log("Connection was successful, but no authorization found") })
These functions will be called when authorization status will be changing. I.e. at least once an authorization will be successful or unsuccessful when connecting to comet server or while status will be changed.
You can also call the function “isAuthorized” to determine authorization status.
cometApi.isAuthorized()
The function “isAuthorized” may return 3 different values:
JavaScript API has one function which chooses from several tabs and granted one of these tabs as a “chief” tab – this tab called like master tab and others automatically determines like salve tabs. The function isMaster may return true if it performs like “chief” tab and return false if it performs like salve tab.
cometApi.isMaster()
Determination of which tab can be the master tab may be useful if you want to perform some action just on one tab. For example, you have opened a chat by 3 pages and at every income message plays audio notification. Here might be a good thing if just only one of these tabs will be make a sound, rather than all.
For more details about cooperation between these tabs, search in article Message exchange between browser tabs.
In some cases file CometServer.js is inserted in the following way:
<script src="//comet-server.ru/CometServerApi.js" type="text/javascript"></script>
This approach can be right just only for tests and during developing period but not for permanent using. You can find the last version of JavaScript API here. Check it please to avoid some situation of incompatibility of your app with this soft. New version of JavaScript API might appear as soon as possible. To prevent this situation you can just only once download the file with CometServerApi.js on your server and you can use it until you won’t need updating.