<rst>EN::002-API::001-JavaScript API::001-JavaScript API</rst>
<rst>Header: JavaScript API</rst>

====== JavaScript API ======

  * [[http://comet-server.com/CometServerApi.js|Download CometServerApi.js]]
  * [[https://github.com/Levhav/CometServerApi.js|GitHab repository with CometServerApi.js]]

====== Connection with server ======


The function start accepts connection settings and opens new connection. Here opt – it’s an object with connecting options.
<code JavaScript>cometApi.start({dev_id:15, user_id:1, user_key:"userHash", node:"app.comet-server.ru"})</code>
  * dev_id it’s a binding parameter – [[en:comet:dev_id|public developers’ key]]. 
  * user_id it’s a non-binding parameter – user’s identifier is necessary to  [[en:comet:authentication|authorization on the comet server]]; 
  * user_key it’s non-binding parameter – it is an authorization hash which necessary to [[en:comet:authentication|authorize user on the comet server]].  
  * node - If you deploy [[https://github.com/CppComet/comet-server|CppComet]] on your server, you must specify the address of your server

To reconnecting to server use the restart function.
<code JavaScript>cometApi.restart({dev_id:15, user_id:1, user_key:"userHash"})</code>
To reconnecting you can override connection parameters or left ‘em previous. 
====== Subscribe to receive messages from channel ======

The function subscription adds subscribes on channel, events and delivery reports.  
<code JavaScript>cometApi.subscription("channel_name", function(data){ console.log(data) } )</code>
  * First argument – the channel name must be shorter than 32 symbols and may consist of the next symbols: A-Za-z0-9 and “-“ or “_”.
  * Second argument – the callback function which will be call while message is delivering from this channel.

Pay attention that as the body of message may be json line. If it’s true then is can automatically converted to object.
<code JavaScript>cometApi.subscription( "pipe_name.event_name", function(e){ console.log(["event", e])})</code>
Subscription on channel “channel_name” 
<code JavaScript>cometApi.subscription("channel_name", function(e){ console.log(e)})</code>
Subscription on channel’s events “event_name”on channel “channel_name”
<code JavaScript>cometApi.subscription("channel_name.event_name", function(e){ console.log(e)})</code>
Subscription on delivery report on channel “channel_name” 
<code JavaScript>cometApi.subscription("#channel_name", function(e){ console.log(e)})</code>
Subscription on all incoming messages from all of the channels which subscribed current client 
<code JavaScript>cometApi.subscription(function(e){ console.log(e)})</code>

An example with online demo [[en:comet:faq:js-api-subscription|How to accept message from channel in JavaScript]]

====== Unsubscription of receiving messages from channel ======

The subscription function returns the subscription_id line which can be necessary if we want to unsubscribe of receiving messages.
<code JavaScript>var subscriptionId = cometApi.subscription("channel_name.event_name", function(e){ console.log(e)})</code>

For unsubscription of receiving messages, call: 
<code JavaScript>cometApi.unsubscription(subscriptionId)</code>

======= Reserved channel names =======

The main article [[en:comet:javascript_api:pipe-types|reserved channel names]].
<note warning>We don’t recommend to use in our project such channels names as «bin_*», «big_*», «push_*», «comet_*» и «sys_*». These names could be used for new functions. And they can have some special properties besides of current channels names.</note>

Also we already have some channels with extra properties:
  * msg – used for sending messages in order to authorizing data;
  * user_status_* - used for automatic notification JS API about users’ status;
  * web_* - channels which can receive messages from CometQL and JS API.
  * track_* - automatic notification JS api about what someone has subscribed or unsubscribed from this channel
====== The subscription on receiving private messages ( pipe msg ) ======
The subscription on messages from server, delivered in order to authorization data (by user’s id):
<code JavaScript>cometApi.subscription("msg", function(e){ console.log(e)})</code>
The subscription on messages from server with event name “event_name”, delivered in order to authorization data (by user’s id):
<code JavaScript>cometApi.subscription("msg.event_name", function(e){ console.log(e)})</code>

<note tip>More details about authorization mechanism on comet server and about private messages you can look in article “[[en:comet:authentication|User’s authorization on comet server]]”</note>

====== Subscription on changing user’s status ( pipes user_status_* ) ======

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. 


<code JavaScript>
    // 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")
    })
</code>


====== List of online users (channels track_*) =======

Channels with a name like track_* automatically generate events subscription and unsubscription inside every time someone subscribes or unsubscribes from this channel

<code JavaScript>
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
});
</code>

This type of channel is designed specifically to facilitate the creation of dynamically updated lists of online users.
Main article [[en:comet:faq:realtime-users-list|list of online users]]
====== Sending messages to channel from JS (pipes web_*) ======

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.

<note important>Sending messages to channel from JavaScript is able when name of channel begins with “web_”. CometQL does not have any limitations in this case.</note>

<code JavaScript>cometApi.web_pipe_send("web_pipe_name", "event_name", "message")</code>

To getting a report about message delivery to channel “channel_name” use “subscription”.
<code JavaScript>cometApi.subscription("#channel_name", function(e){ console.log(e)})</code>

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.
<code JavaScript>cometApi.web_pipe_send("@web_pipe_name", "event_name", "message")</code>
 
<html>
<script async src="//jsfiddle.net/07noamea/3/embed/"></script>
</html>
======= The format of incoming messages =======
<code>
 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.
</code>

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.
====== Getting the last messages from channel ======
The comet server includes possibility to activated storing the last N messages mechanism for some channels.
<note tip>Logging of transferred messages may be activate by CometQL query to table “[[en:comet:cometql|pipes_settings]]”.</note> 

If logging function is active, then method call “get_pipe_log” initiate sending all messages from history to client.
<code JavaScript>cometApi.get_pipe_log("web_pipe_name")</code>
Delivered from history messages will have a property “history=true”.

======= Getting a number of subscribers =======

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.
<code Javascript>
cometApi.count_users_in_pipe("web_chat_pipe", function(res)
{
    console.log("count_users_in_pipe", res, res.data.user_in_pipe)
})
</code>

Besides of [[en:comet:cometql|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.
 
======= Determination of authorization status on comet server =======

The main article [[en:comet:authentication|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.
<code JavaScript>
// 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")
})
</code>
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.
<code JavaScript>cometApi.isAuthorized()</code>
The function “isAuthorized” may return 3 different values: 
  * false – authorization is not complete;
  * true – authorization is complete;
  * undefined – the status in undefined – this answer returns even before an attempt to connect to comet server.

======= Determination of master tab =======

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.

<code JavaScript>cometApi.isMaster()</code>

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 [[https://habrahabr.ru/company/comet-server/blog/250719/|Message exchange between browser tabs]].

======= References =======

In some cases file CometServer.js is inserted in the following way:
<code html>
<script src="//comet-server.ru/CometServerApi.js" type="text/javascript"></script>
</code>
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 [[http://comet-server.ru/CometServerApi.js|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.
  
====== Additional Information ======
 
  * [[en:comet:javascript_api:pipe-types|Reserved channel names]]
  * [[en:comet:cometql|CometQL API]]
  * [[en:comet:dev_id|What is and why do we need "A public developer token" and "Secret developer key"]]