Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
en:comet:javascript_api [2017/07/16 16:27] levhav |
en:comet:javascript_api [2019/12/18 02:05] (current) |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | <rst>EN::002-API::001-JavaScript API</rst> | + | <rst>EN::002-API::001-JavaScript API::001-JavaScript API</rst> |
| + | <rst>Header: JavaScript API</rst> | ||
| ====== JavaScript API ====== | ====== JavaScript API ====== | ||
| Line 10: | Line 11: | ||
| The function start accepts connection settings and opens new connection. Here opt – it’s an object with connecting options. | The function start accepts connection settings and opens new connection. Here opt – it’s an object with connecting options. | ||
| - | <code JavaScript>CometServer().start({dev_id:15, user_id:1, user_key:"userHash", node:"app.comet-server.ru"})</code> | + | <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]]. | * 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_id it’s a non-binding parameter – user’s identifier is necessary to [[en:comet:authentication|authorization on the comet server]]; | ||
| Line 17: | Line 18: | ||
| To reconnecting to server use the restart function. | To reconnecting to server use the restart function. | ||
| - | <code JavaScript>CometServer().restart({dev_id:15, user_id:1, user_key:"userHash"})</code> | + | <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. | To reconnecting you can override connection parameters or left ‘em previous. | ||
| ====== Subscribe to receive messages from channel ====== | ====== Subscribe to receive messages from channel ====== | ||
| The function subscription adds subscribes on channel, events and delivery reports. | The function subscription adds subscribes on channel, events and delivery reports. | ||
| - | <code JavaScript>CometServer().subscription("channel_name", function(data){ console.log(data) } )</code> | + | <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 “_”. | * 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. | * 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. | 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>CometServer().subscription( "pipe_name.event_name", function(e){ console.log(["event", e])})</code> | + | <code JavaScript>cometApi.subscription( "pipe_name.event_name", function(e){ console.log(["event", e])})</code> |
| Subscription on channel “channel_name” | Subscription on channel “channel_name” | ||
| - | <code JavaScript>CometServer().subscription("channel_name", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("channel_name", function(e){ console.log(e)})</code> |
| Subscription on channel’s events “event_name”on channel “channel_name” | Subscription on channel’s events “event_name”on channel “channel_name” | ||
| - | <code JavaScript>CometServer().subscription("channel_name.event_name", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("channel_name.event_name", function(e){ console.log(e)})</code> |
| Subscription on delivery report on channel “channel_name” | Subscription on delivery report on channel “channel_name” | ||
| - | <code JavaScript>CometServer().subscription("#channel_name", function(e){ console.log(e)})</code> | + | <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 | Subscription on all incoming messages from all of the channels which subscribed current client | ||
| - | <code JavaScript>CometServer().subscription(function(e){ console.log(e)})</code> | + | <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]] | An example with online demo [[en:comet:faq:js-api-subscription|How to accept message from channel in JavaScript]] | ||
| Line 42: | Line 43: | ||
| The subscription function returns the subscription_id line which can be necessary if we want to unsubscribe of receiving messages. | The subscription function returns the subscription_id line which can be necessary if we want to unsubscribe of receiving messages. | ||
| - | <code JavaScript>var subscriptionId = CometServer().subscription("channel_name.event_name", function(e){ console.log(e)})</code> | + | <code JavaScript>var subscriptionId = cometApi.subscription("channel_name.event_name", function(e){ console.log(e)})</code> |
| For unsubscription of receiving messages, call: | For unsubscription of receiving messages, call: | ||
| - | <code JavaScript>CometServer().unsubscription(subscriptionId)</code> | + | <code JavaScript>cometApi.unsubscription(subscriptionId)</code> |
| ======= Reserved channel names ======= | ======= Reserved channel names ======= | ||
| Line 57: | Line 58: | ||
| * web_* - channels which can receive messages from CometQL and JS API. | * 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 | * 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 receiving private messages ( pipe msg ) ====== |
| The subscription on messages from server, delivered in order to authorization data (by user’s id): | The subscription on messages from server, delivered in order to authorization data (by user’s id): | ||
| - | <code JavaScript>CometServer().subscription("msg", function(e){ console.log(e)})</code> | + | <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): | The subscription on messages from server with event name “event_name”, delivered in order to authorization data (by user’s id): | ||
| - | <code JavaScript>CometServer().subscription("msg.event_name", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("msg.event_name", function(e){ console.log(e)})</code> |
| - | <note tip>More details about authorization mechanism on comet server you and about private messages look in article “[[en:comet:authentication|User’s authorization on comet server]]”</note> | + | <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_* )====== | + | ====== 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. | It is possible to subscribe from JS on notifications about some user’s activity on comet server. | ||
| Line 74: | Line 75: | ||
| <code JavaScript> | <code JavaScript> | ||
| // Subscribe on notification that user with id=12 is online | // Subscribe on notification that user with id=12 is online | ||
| - | CometServer().subscription("user_status_12.online", function(event) | + | cometApi.subscription("user_status_12.online", function(event) |
| { | { | ||
| console.log("User with id=12 online") | console.log("User with id=12 online") | ||
| Line 80: | Line 81: | ||
| // Subscribe on notification that user with id=12 is offline | // Subscribe on notification that user with id=12 is offline | ||
| - | CometServer().subscription("user_status_12.offline", function(event) | + | cometApi.subscription("user_status_12.offline", function(event) |
| { | { | ||
| console.log("User with id=12 offline") | console.log("User with id=12 offline") | ||
| Line 92: | Line 93: | ||
| <code JavaScript> | <code JavaScript> | ||
| - | CometServer().Subscription("track_online.subscription", function(msg) | + | cometApi.Subscription("track_online.subscription", function(msg) |
| { | { | ||
| // Event Processing that someone went to the website and subscribe to the channel track_online | // Event Processing that someone went to the website and subscribe to the channel track_online | ||
| }); | }); | ||
| - | CometServer().Subscription("track_online.unsubscription", function(msg) | + | cometApi.Subscription("track_online.unsubscription", function(msg) |
| { | { | ||
| // Event Processing that someone left the site and / or unsubscribe from the channel track_online | // Event Processing that someone left the site and / or unsubscribe from the channel track_online | ||
| Line 106: | Line 107: | ||
| ====== Sending messages to channel from JS (pipes web_*) ====== | ====== Sending messages to channel from JS (pipes web_*) ====== | ||
| - | The function web_pipe_send lets from JavaScript send messages to channel bypassing 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. | + | 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>Send messages to channel from JavaScript is able when name of channel begins with “web_”. CometQL does not have any limitations in this case.</note> | + | <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>CometServer().web_pipe_send("web_pipe_name", "event_name", "message")</code> | + | <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”. | To getting a report about message delivery to channel “channel_name” use “subscription”. | ||
| - | <code JavaScript>CometServer().subscription("#channel_name", function(e){ console.log(e)})</code> | + | <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 send by non-authorized user. | + | 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>CometServer().web_pipe_send("@web_pipe_name", "event_name", "message")</code> | + | <code JavaScript>cometApi.web_pipe_send("@web_pipe_name", "event_name", "message")</code> |
| <html> | <html> | ||
| Line 132: | Line 133: | ||
| </code> | </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. | + | 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 ====== | ====== Getting the last messages from channel ====== | ||
| - | The comet server includes possibility to activate storing the last N messages mechanism for some channels. | + | 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> | <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. | If logging function is active, then method call “get_pipe_log” initiate sending all messages from history to client. | ||
| - | <code JavaScript>CometServer().get_pipe_log("web_pipe_name")</code> | + | <code JavaScript>cometApi.get_pipe_log("web_pipe_name")</code> |
| Delivered from history messages will have a property “history=true”. | Delivered from history messages will have a property “history=true”. | ||
| ======= Getting a number of subscribers ======= | ======= Getting a number of subscribers ======= | ||
| - | The function “count_user_in_pipe” can helps to determine a number of subscribes for current channel. | + | 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. | + | Also, this function has the first argument – name of channel and the second is callback function which holds an answer. |
| <code Javascript> | <code Javascript> | ||
| - | CometServer().count_users_in_pipe("web_chat_pipe", function(res) | + | cometApi.count_users_in_pipe("web_chat_pipe", function(res) |
| { | { | ||
| console.log("count_users_in_pipe", res, res.data.user_in_pipe) | console.log("count_users_in_pipe", res, res.data.user_in_pipe) | ||
| Line 153: | Line 154: | ||
| </code> | </code> | ||
| - | Besides of [[en:comet:cometql|CometQL query]], this function can show a number of subscribers only for those channels which name begins 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. | + | 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 ======= | ======= Determination of authorization status on comet server ======= | ||
| Line 164: | Line 165: | ||
| <code JavaScript> | <code JavaScript> | ||
| // Adding the callback function for notification about successful authorization | // Adding the callback function for notification about successful authorization | ||
| - | CometServer().onAuthSuccess(function(){ | + | cometApi.onAuthSuccess(function(){ |
| console.log("Connection and authorization were successful") | console.log("Connection and authorization were successful") | ||
| }) | }) | ||
| // Adding the callback function for notification about unsuccessful authorization | // Adding the callback function for notification about unsuccessful authorization | ||
| - | CometServer().onAuthFalill(function(){ | + | cometApi.onAuthFalill(function(){ |
| console.log("Connection was successful, but no authorization found") | console.log("Connection was successful, but no authorization found") | ||
| }) | }) | ||
| Line 175: | Line 176: | ||
| 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. | 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. | ||
| - | Also you can call the function “isAuthorized” to determine authorization status. | + | You can also call the function “isAuthorized” to determine authorization status. |
| - | <code JavaScript>CometServer().isAuthorized()</code> | + | <code JavaScript>cometApi.isAuthorized()</code> |
| The function “isAuthorized” may return 3 different values: | The function “isAuthorized” may return 3 different values: | ||
| * false – authorization is not complete; | * false – authorization is not complete; | ||
| - | * true - authorization is complete; | + | * true – authorization is complete; |
| * undefined – the status in undefined – this answer returns even before an attempt to connect to comet server. | * undefined – the status in undefined – this answer returns even before an attempt to connect to comet server. | ||
| Line 186: | Line 187: | ||
| 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. | 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>CometServer().isMaster()</code> | + | <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. | 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. | ||
| Line 207: | Line 208: | ||
| * [[en:comet:dev_id|What is and why do we need "A public developer token" and "Secret developer key"]] | * [[en:comet:dev_id|What is and why do we need "A public developer token" and "Secret developer key"]] | ||
| - | |||
| - | |||
| - | |||