Различия
Здесь показаны различия между двумя версиями данной страницы.
Предыдущая версия справа и слева Предыдущая версия Следующая версия | Предыдущая версия Следующая версия Следующая версия справа и слева | ||
comet:javascript_api [2017/07/16 16:35] levhav |
comet:javascript_api [2018/02/24 11:57] anastation468 [Определение мастер вкладки] |
||
---|---|---|---|
Строка 1: | Строка 1: | ||
- | <rst>RU::002-API::001-JavaScript API::001-JavaScript API</rst> | + | <rst>RU::002-API::001-JavaScript API</rst> |
+ | <rst>Header:JavaScript API</rst> | ||
====== JavaScript API ====== | ====== JavaScript API ====== | ||
Строка 9: | Строка 10: | ||
- | Функция start принимает настройки соединения и открывает соединение. Здесь opt это объект с опциями подключения. | + | Функция start принимает настройки соединения и открывает соединение. Здесь opt – это объект с опциями подключения. |
- | <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 обязательный параметр это [[comet:dev_id|публичный ключ разработчика]]. | * dev_id обязательный параметр это [[comet:dev_id|публичный ключ разработчика]]. | ||
* user_id не обязательный параметр, это идентификатор пользователя нужен для [[comet:authentication|авторизации пользователя]] на комет сервере | * user_id не обязательный параметр, это идентификатор пользователя нужен для [[comet:authentication|авторизации пользователя]] на комет сервере | ||
Строка 17: | Строка 18: | ||
Для переподключения к серверу используйте функцию restart | Для переподключения к серверу используйте функцию restart | ||
- | <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> |
При переподключении вы можете переопределить параметры подключения или оставить их прежними. | При переподключении вы можете переопределить параметры подключения или оставить их прежними. | ||
====== Подписка на получение сообщений из канала ====== | ====== Подписка на получение сообщений из канала ====== | ||
Строка 23: | Строка 24: | ||
Функция subscription добавляет подписки на каналы, события в каналах и отчёты о доставке сообщений в каналы. | Функция subscription добавляет подписки на каналы, события в каналах и отчёты о доставке сообщений в каналы. | ||
Для подписки на сообщения в канале: | Для подписки на сообщения в канале: | ||
- | <code JavaScript>CometServer().subscription("имя_канала", function(data){ console.log(data) } )</code> | + | <code JavaScript>cometApi.subscription("имя_канала", function(data){ console.log(data) } )</code> |
* Первый аргумент - имя канала должно быть короче 32 символов и должно состоять из символов A-Za-z0-9 и символа минус и знака подчёркивания. | * Первый аргумент - имя канала должно быть короче 32 символов и должно состоять из символов A-Za-z0-9 и символа минус и знака подчёркивания. | ||
- | * Второй аргумент - callback функция которая будет вызвана при получении сообщения из этого канала. | + | * Второй аргумент - callback функция, которая будет вызвана при получении сообщения из этого канала. |
- | Обратите внимание что телом сообщения может быть json строка. Если это так то она автоматически будет преобразована в объект. | + | Обратите внимание, что телом сообщения может быть json строка. Если это так, то она автоматически будет преобразована в объект. |
- | <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> |
Подписка на канал "Имя_канала" | Подписка на канал "Имя_канала" | ||
- | <code JavaScript>CometServer().subscription("Имя_канала", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("Имя_канала", function(e){ console.log(e)})</code> |
Подписка на канал событие "имя_события" в канале "Имя_канала" | Подписка на канал событие "имя_события" в канале "Имя_канала" | ||
- | <code JavaScript>CometServer().subscription("Имя_канала.имя_события", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})</code> |
Подписка на отчёт о доставке в канал "Имя_канала" | Подписка на отчёт о доставке в канал "Имя_канала" | ||
- | <code JavaScript>CometServer().subscription("#Имя_канала", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("#Имя_канала", function(e){ console.log(e)})</code> |
Подписка на все входящие сообщения из всех каналов на которые подписан этот клиент | Подписка на все входящие сообщения из всех каналов на которые подписан этот клиент | ||
- | <code JavaScript>CometServer().subscription(function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription(function(e){ console.log(e)})</code> |
Пример с online demo [[comet:faq:js-api-subscription|как принять сообщение из канала в JavaScript?]] | Пример с online demo [[comet:faq:js-api-subscription|как принять сообщение из канала в JavaScript?]] | ||
Строка 42: | Строка 43: | ||
====== Отписка от получения сообщений из канала ====== | ====== Отписка от получения сообщений из канала ====== | ||
- | Функция subscription возвращает строку subscription_id которая нам может понадобится если мы захотим отписать функцию от получения сообщений. | + | Функция subscription возвращает строку subscription_id, которая нам может понадобится, если мы захотим отписать функцию от получения сообщений. |
- | <code JavaScript>var subscriptionId = CometServer().subscription("Имя_канала.имя_события", function(e){ console.log(e)})</code> | + | <code JavaScript>var subscriptionId = cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})</code> |
Для отписки от получения сообщений вызовите | Для отписки от получения сообщений вызовите | ||
- | <code JavaScript>CometServer().unsubscription(subscriptionId)</code> | + | <code JavaScript>cometApi.unsubscription(subscriptionId)</code> |
====== Зарезервированные имена каналов ====== | ====== Зарезервированные имена каналов ====== | ||
Основная статья [[comet:javascript_api:pipe-types|зарезервированные имена каналов]] | Основная статья [[comet:javascript_api:pipe-types|зарезервированные имена каналов]] | ||
- | <note warning>Не рекомендуется использовать в своих проектах имена каналов вида "bin_*", "big_*", "push_*", "comet_*", "self_*", "trust_*" и "sys_*" эти имена возможно будут использованы для дальнейшего расширения функционала. И будут иметь какие ни будь не обычные свойства по сравнению с другими именами каналов.</note> | + | <note warning>Не рекомендуется использовать в своих проектах имена каналов вида "bin_*", "big_*", "push_*", "comet_*", "self_*", "trust_*" и "sys_*" эти имена возможно будут использованы для дальнейшего расширения функционала. И будут иметь какие-нибудь необычные свойства по сравнению с другими именами каналов.</note> |
Строка 61: | Строка 62: | ||
====== Подписка на получение личных сообщений ( канал msg )====== | ====== Подписка на получение личных сообщений ( канал msg )====== | ||
Подписка на сообщения от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя) | Подписка на сообщения от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя) | ||
- | <code JavaScript>CometServer().subscription("msg", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("msg", function(e){ console.log(e)})</code> |
Подписка на сообщения с именем события "имя_события" от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя) | Подписка на сообщения с именем события "имя_события" от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя) | ||
- | <code JavaScript>CometServer().subscription("msg.имя_события", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("msg.имя_события", function(e){ console.log(e)})</code> |
<note tip>Более подробно про механизм авторизации на комет сервере и про личные сообщения смотрите в статье [[comet:authentication|Авторизация пользователей на комет сервере]]</note> | <note tip>Более подробно про механизм авторизации на комет сервере и про личные сообщения смотрите в статье [[comet:authentication|Авторизация пользователей на комет сервере]]</note> | ||
Строка 69: | Строка 70: | ||
====== Подписка на изменение статуса пользователя ( каналы user_status_* )====== | ====== Подписка на изменение статуса пользователя ( каналы user_status_* )====== | ||
- | Есть возможность из JS подписаться на уведомления о том когда определённый пользователь авторизуется на комет сервере или на оборот отключится от него. | + | Есть возможность из JS подписаться на уведомления о том, когда определённый пользователь авторизуется на комет сервере или на оборот отключится от него. |
- | Когда пользователь на комет сервере авторизуется то комет сервер автоматически отправляет сигнал в канал user_status_{идентификатор пользователя} с именем события online. А когда авторизованный пользователь уходит в offline то комет сервер тоже генерирует событие. | + | Когда пользователь на комет сервере авторизуется, то комет сервер автоматически отправляет сигнал в канал user_status_{идентификатор пользователя} с именем события online. А когда авторизованный пользователь уходит в offline то комет сервер тоже генерирует событие. |
<code JavaScript> | <code JavaScript> | ||
- | // Подписываемся на уведомление о том что пользователь с id=12 online | + | // Подписываемся на уведомление о том, что пользователь с id=12 online |
- | CometServer().subscription("user_status_12.online", function(event) | + | cometApi.subscription("user_status_12.online", function(event) |
{ | { | ||
console.log("Пользователь с id=12 online") | console.log("Пользователь с id=12 online") | ||
}) | }) | ||
- | // Подписываемся на уведомление о том что пользователь с id=12 offline | + | // Подписываемся на уведомление о том, что пользователь с id=12 offline |
- | CometServer().subscription("user_status_12.offline", function(event) | + | cometApi.subscription("user_status_12.offline", function(event) |
{ | { | ||
console.log("Пользователь с id=12 offline") | console.log("Пользователь с id=12 offline") | ||
Строка 90: | Строка 91: | ||
====== Список пользователей онлайн ( каналы track_* )====== | ====== Список пользователей онлайн ( каналы track_* )====== | ||
- | Каналы с именем вида track_* автоматически генерируют события subscription и unsubscription внутри себя каждый раз как кто то подписывается или отписывается от этого канала | + | Каналы с именем вида track_* автоматически генерируют события subscription и unsubscription внутри себя каждый раз как кто-то подписывается или отписывается от этого канала |
<code JavaScript> | <code JavaScript> | ||
- | CometServer().subscription("track_online.subscription", function(msg) | + | cometApi.subscription("track_online.subscription", function(msg) |
{ | { | ||
// Обработка события что кто то зашёл на сайт и подписался на канал track_online | // Обработка события что кто то зашёл на сайт и подписался на канал track_online | ||
}); | }); | ||
- | CometServer().subscription("track_online.unsubscription", function(msg) | + | cometApi.subscription("track_online.unsubscription", function(msg) |
{ | { | ||
- | // Обработка события что кто то покинул сайт и/или отписался от канала track_online | + | // Обработка события что кто-то покинул сайт и/или отписался от канала track_online |
}); | }); | ||
</code> | </code> | ||
Строка 114: | Строка 115: | ||
<note important>Отправлять сообщения в канал из JavaScript можно только если имя канала начинается с web_ в то время как для CometQL такого ограничения нет.</note> | <note important>Отправлять сообщения в канал из JavaScript можно только если имя канала начинается с web_ в то время как для CometQL такого ограничения нет.</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> |
- | Для того чтобы получить отчёт о доставке сообщения в канал "Имя_канала" используйте subscription | + | Для того, чтобы получить отчёт о доставке сообщения в канал "Имя_канала" используйте subscription |
- | <code JavaScript>CometServer().subscription("#Имя_канала", function(e){ console.log(e)})</code> | + | <code JavaScript>cometApi.subscription("#Имя_канала", function(e){ console.log(e)})</code> |
- | Так как комет сервер поддерживает авторизацию пользователей, он сам добавляет id пользователя к сообщению таким образом что пользователь отправивший сообщение не может отправить чужой id. Для отключения этой возможности надо добавить символ "@" перед именем канала в который отправляется сообщение. В таком случаи доставленное сообщение будет выглядеть так как будто его отправил не авторизованный пользователь. | + | Так как комет сервер поддерживает авторизацию пользователей, он сам добавляет id пользователя к сообщению таким образом что пользователь отправивший сообщение не может отправить чужой id. Для отключения этой возможности надо добавить символ "@" перед именем канала, в который отправляется сообщение. В таком случае, доставленное сообщение будет выглядеть так, как будто его отправил не авторизованный пользователь. |
- | <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> |
Пример чата на основе отправки сообщений из JavaScript Api прямо в комет сервер | Пример чата на основе отправки сообщений из JavaScript Api прямо в комет сервер | ||
Строка 145: | Строка 146: | ||
<note tip>Логирование проходящих сообщений можно включить запросом CometQL к [[comet:cometql#таблица_pipes_settings|таблице pipes_settings]].</note> | <note tip>Логирование проходящих сообщений можно включить запросом CometQL к [[comet:cometql#таблица_pipes_settings|таблице pipes_settings]].</note> | ||
- | Если функция логирования включена то вызов метода get_pipe_log инициирует отправку всех сообщений из истории в канале на клиент. | + | Если функция логирования включена, то вызов метода get_pipe_log инициирует отправку всех сообщений из истории в канале на клиент. |
- | <code JavaScript>CometServer().get_pipe_log("web_pipe_name")</code> | + | <code JavaScript>cometApi.get_pipe_log("web_pipe_name")</code> |
Сообщения пришедшие из истории канала будут иметь свойство history=true | Сообщения пришедшие из истории канала будут иметь свойство history=true | ||
Строка 153: | Строка 154: | ||
Функция count_users_in_pipe даёт возможность узнать количество подписчиков в канале. | Функция count_users_in_pipe даёт возможность узнать количество подписчиков в канале. | ||
- | У функции count_users_in_pipe первый аргумент это имя канала а вторым аргументом передаётся callback функция в которую будет передан ответ. | + | У функции count_users_in_pipe первый аргумент это имя канала, а вторым аргументом передаётся callback функция, в которую будет передан ответ. |
<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) | ||
Строка 161: | Строка 162: | ||
</code> | </code> | ||
- | Но в отличии от [[comet:cometql|CometQL]] запроса эта функция может показывать количество подписчиков только в тех каналах у которых имя начинается с web_ к примеру для канала web_chat_pipe она сработает а для канала chat_pipe не сработает. Это ограничение введено для того что бы была возможность создать такой канал в котором количество подписчиков не сможет узнать кто попало через js api | + | Но в отличии от [[comet:cometql|CometQL]] запроса эта функция может показывать количество подписчиков только в тех каналах, у которых имя начинается с web_ к примеру для канала web_chat_pipe она сработает, а для канала chat_pipe не сработает. Это ограничение введено для того, чтобы была возможность создать такой канал, в котором количество подписчиков не сможет узнать кто-попало через js api |
======= Определение статуса авторизации на комет сервере ======= | ======= Определение статуса авторизации на комет сервере ======= | ||
Строка 172: | Строка 173: | ||
<code JavaScript> | <code JavaScript> | ||
// Добавление callBack функции на уведомление об успешной авторизации | // Добавление callBack функции на уведомление об успешной авторизации | ||
- | CometServer().onAuthSuccess(function(){ | + | cometApi.onAuthSuccess(function(){ |
console.log("Подключились и авторизовались успешно") | console.log("Подключились и авторизовались успешно") | ||
}) | }) | ||
// Добавление callBack функции на уведомление об не успешной авторизации | // Добавление callBack функции на уведомление об не успешной авторизации | ||
- | CometServer().onAuthFalill(function(){ | + | cometApi.onAuthFalill(function(){ |
console.log("Подключились успешно но не авторизовались") | console.log("Подключились успешно но не авторизовались") | ||
}) | }) | ||
Строка 184: | Строка 185: | ||
Так же в любой момент времени можно вызвать функцию isAuthorized для определения статуса авторизации. | Так же в любой момент времени можно вызвать функцию isAuthorized для определения статуса авторизации. | ||
- | <code JavaScript>CometServer().isAuthorized()</code> | + | <code JavaScript>cometApi.isAuthorized()</code> |
Функция isAuthorized может вернуть 3 разных значения | Функция isAuthorized может вернуть 3 разных значения | ||
* false - авторизация не пройдена | * false - авторизация не пройдена | ||
Строка 192: | Строка 193: | ||
======= Определение мастер вкладки ======= | ======= Определение мастер вкладки ======= | ||
- | В JavaScript API есть функция которая из нескольких открытых вкладок назначает одну вкладку "главной" она называется мастер вкладкой, а все остальные вкладки определяются как salve вкладки. Функция isMaster возвращает true если выполняется в контексте мастер вкладки и false если выполняется в контексте salave вкладки. | + | В JavaScript API есть функция, которая из нескольких открытых вкладок назначает одну вкладку "главной" она называется мастер вкладкой, а все остальные вкладки определяются как salve вкладки. Функция isMaster возвращает true, если выполняется в контексте мастер вкладки и false если выполняется в контексте salave вкладки. |
- | <code JavaScript>CometServer().isMaster()</code> | + | <code JavaScript>cometApi.isMaster()</code> |
- | Определение какая вкладка является мастер вкладкой, а какая slave может быть полезно если вам надо сделать определённое действие только на одной вкладке а не во всех. | + | Определение, какая вкладка является мастер вкладкой, а какая slave может быть полезно если вам надо сделать определённое действие только на одной вкладке, а не во всех. |
- | Например у вас чат открыт на 3 страницах и при каждом входящем сообщении воспроизводится звуковое уведомление. В таком примере будет правильно если только одна вкладка будет воспроизводить звук а не все 3. | + | Например, у вас чат открыт на 3 страницах и при каждом входящем сообщении воспроизводится звуковое уведомление. В таком примере будет правильно если только одна вкладка будет воспроизводить звук а не все 3. |
Больше подробностей про взаимодействие между вкладками смотрите в статье [[https://habrahabr.ru/company/comet-server/blog/250719/|обмен сообщениями между вкладками браузера]]. | Больше подробностей про взаимодействие между вкладками смотрите в статье [[https://habrahabr.ru/company/comet-server/blog/250719/|обмен сообщениями между вкладками браузера]]. | ||
- | |||
- | |||
- | |||