JavaScript API

Соединение с сервером

Функция start принимает настройки соединения и открывает соединение. Здесь opt – это объект с опциями подключения.

cometApi.start({dev_id:15, user_id:1, user_key:"userHash", node:"app.comet-server.ru"})
  • dev_id обязательный параметр это публичный ключ разработчика.
  • user_id не обязательный параметр, это идентификатор пользователя нужен для авторизации пользователя на комет сервере
  • user_key не обязательный параметр, это хеш авторизации пользователя нужен для авторизации пользователя на комет сервере
  • node - если вы разворачиваете CppComet на своём сервере, то надо указать адрес вашего сервера ( Если комет сервер работает не на 80 порту то обязательно надо указать порт например так node:«app.comet-server.ru:8087» )

Для переподключения к серверу используйте функцию restart

cometApi.restart({dev_id:15, user_id:1, user_key:"userHash"})

При переподключении вы можете переопределить параметры подключения или оставить их прежними.

Подписка на получение сообщений из канала

Функция subscription добавляет подписки на каналы, события в каналах и отчёты о доставке сообщений в каналы. Для подписки на сообщения в канале:

cometApi.subscription("имя_канала", function(data){ console.log(data) } )
  • Первый аргумент - имя канала должно быть короче 32 символов и должно состоять из символов A-Za-z0-9 и символа минус и знака подчёркивания.
  • Второй аргумент - callback функция, которая будет вызвана при получении сообщения из этого канала.

Обратите внимание, что телом сообщения может быть json строка. Если это так, то она автоматически будет преобразована в объект.

cometApi.subscription( "pipe_name.event_name", function(e){ console.log(["event", e])})

Подписка на канал «Имя_канала»

cometApi.subscription("Имя_канала", function(e){ console.log(e)})

Подписка на канал событие «имя_события» в канале «Имя_канала»

cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})

Подписка на отчёт о доставке в канал «Имя_канала»

cometApi.subscription("#Имя_канала", function(e){ console.log(e)})

Подписка на все входящие сообщения из всех каналов на которые подписан этот клиент

cometApi.subscription(function(e){ console.log(e)})

Пример с online demo как принять сообщение из канала в JavaScript?

Отписка от получения сообщений из канала

Функция subscription возвращает строку subscription_id, которая нам может понадобится, если мы захотим отписать функцию от получения сообщений.

var subscriptionId = cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})

Для отписки от получения сообщений вызовите

cometApi.unsubscription(subscriptionId)

Зарезервированные имена каналов

Основная статья зарезервированные имена каналов

Не рекомендуется использовать в своих проектах имена каналов вида «bin_*», «big_*», «push_*», «comet_*», «self_*», «trust_*» и «sys_*» эти имена возможно будут использованы для дальнейшего расширения функционала. И будут иметь какие-нибудь необычные свойства по сравнению с другими именами каналов.

Так же есть каналы с особыми свойствами, о всех них ниже по тексту.

  • msg - Для доставки личных сообщений в соответствии с данными авторизации
  • user_status_* - для автоматического уведомления JS api о статусе пользователей
  • web_* - Каналы в которые можно отправлять сообщения как из CometQL так и из JS api
  • track_* - для автоматического уведомления JS api о том что кто то подписался или отписался от этого канала

Подписка на получение личных сообщений ( канал msg )

Подписка на сообщения от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя)

cometApi.subscription("msg", function(e){ console.log(e)})

Подписка на сообщения с именем события «имя_события» от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя)

cometApi.subscription("msg.имя_события", function(e){ console.log(e)})
Более подробно про механизм авторизации на комет сервере и про личные сообщения смотрите в статье Авторизация пользователей на комет сервере

Подписка на изменение статуса пользователя ( каналы user_status_* )

Есть возможность из JS подписаться на уведомления о том, когда определённый пользователь авторизуется на комет сервере или на оборот отключится от него.

Когда пользователь на комет сервере авторизуется, то комет сервер автоматически отправляет сигнал в канал user_status_{идентификатор пользователя} с именем события online. А когда авторизованный пользователь уходит в offline то комет сервер тоже генерирует событие.

    // Подписываемся на уведомление о том, что пользователь с id=12 online
    cometApi.subscription("user_status_12.online", function(event)
    {
         console.log("Пользователь с id=12 online")
    })
 
    // Подписываемся на уведомление о том, что пользователь с id=12 offline
    cometApi.subscription("user_status_12.offline", function(event)
    {
         console.log("Пользователь с id=12 offline")
    })

Список пользователей онлайн ( каналы track_* )

Каналы с именем вида track_* автоматически генерируют события subscription и unsubscription внутри себя каждый раз как кто-то подписывается или отписывается от этого канала

cometApi.subscription("track_online.subscription", function(msg)
{
    // Обработка события что кто то зашёл на сайт и подписался на канал track_online
});	
cometApi.subscription("track_online.unsubscription", function(msg)
{
    // Обработка события что кто-то покинул сайт и/или отписался от канала track_online
});	

Этот вид каналов создан специально для облегчения создания динамически обновляемых списков пользователей онлайн. Основная статья список пользователей онлайн

Отправка сообщений в канал из JS (каналы web_*)

Функция web_pipe_send позволяет из JavaScript отправлять сообщения в канал минуя ваш сервер, то есть напрямую обращаясь к comet серверу. Это позволяет пересылать сообщения между клиентами вообще не загружая ваш сервер. Так же благодаря обращению на прямую к comet серверу время доставки сообщения от клиента к клиенту минимально.

Отправлять сообщения в канал из JavaScript можно только если имя канала начинается с web_ в то время как для CometQL такого ограничения нет.
cometApi.web_pipe_send("web_pipe_name", "event_name", "message")

Для того, чтобы получить отчёт о доставке сообщения в канал «Имя_канала» используйте subscription

cometApi.subscription("#Имя_канала", function(e){ console.log(e)})

Так как комет сервер поддерживает авторизацию пользователей, он сам добавляет id пользователя к сообщению таким образом что пользователь отправивший сообщение не может отправить чужой id. Для отключения этой возможности надо добавить символ «@» перед именем канала, в который отправляется сообщение. В таком случае, доставленное сообщение будет выглядеть так, как будто его отправил не авторизованный пользователь.

cometApi.web_pipe_send("@web_pipe_name", "event_name", "message")

Пример чата на основе отправки сообщений из JavaScript Api прямо в комет сервер

Формат входящих сообщений

 data: {}                   // Сообщение пользователя
 server_info:
    event: "undefined"      // Имя события
    history: false          // Если true то это данные загружаемые из истории канала а не пришедшие сейчас
    marker: undefined       // Специальный идентификатор, определён только когда history равно true 
    pipe: "web_chat_pipe"   // Имя канала которому адресовано сообщение
    user_id: 0              // Id отправителя, если 0 то не задан. Будет добавляется автоматически если человек отправивший сообщение в канал авторизован на комет сервере.

Поле server_info.user_id в приходящем сообщении заполняется чем то кроме нуля только если сообщение отправлено в канал из JavaScript API и при этом отправитель прошёл авторизацию на комет сервере. Оно содержит user_id отправителя.

Получение последних сообщений из канала

В комет сервере есть возможность для некоторых каналов включить механизм запоминания последних N сообщений через них.

Логирование проходящих сообщений можно включить запросом CometQL к таблице pipes_settings.

Если функция логирования включена, то вызов метода get_pipe_log инициирует отправку всех сообщений из истории в канале на клиент.

cometApi.get_pipe_log("web_pipe_name")

Сообщения пришедшие из истории канала будут иметь свойство history=true

Получение количества подписчиков в канале

Функция count_users_in_pipe даёт возможность узнать количество подписчиков в канале.

У функции count_users_in_pipe первый аргумент это имя канала, а вторым аргументом передаётся callback функция, в которую будет передан ответ.

cometApi.count_users_in_pipe("web_chat_pipe", function(res)
{
    console.log("count_users_in_pipe", res, res.data.user_in_pipe)
})

Но в отличии от CometQL запроса эта функция может показывать количество подписчиков только в тех каналах, у которых имя начинается с web_ к примеру для канала web_chat_pipe она сработает, а для канала chat_pipe не сработает. Это ограничение введено для того, чтобы была возможность создать такой канал, в котором количество подписчиков не сможет узнать кто-попало через js api

Определение статуса авторизации на комет сервере

Основная статья авторизация на комет сервере

У комет сервера есть возможность авторизации пользователей. Авторизация может быть полезна для того что бы была возможность определить кто именно отправил сообщение в канал или для адресной отправки сообщений пользователям.

Из JavaScript api вы можете отслеживать изменение статуса авторизации на комет сервере.

// Добавление callBack функции на уведомление об успешной авторизации
cometApi.onAuthSuccess(function(){
    console.log("Подключились и авторизовались успешно")
})
 
// Добавление callBack функции на уведомление об не успешной авторизации
cometApi.onAuthFalill(function(){
    console.log("Подключились успешно но не авторизовались")
})

Эти функции будут вызваны в момент смены статуса авторизации. То есть как минимум один раз при подключении к комет серверу и при каждой смене статуса если в момент работы скрипта авторизация пропадёт или на оборот произойдёт.

Так же в любой момент времени можно вызвать функцию isAuthorized для определения статуса авторизации.

cometApi.isAuthorized()

Функция isAuthorized может вернуть 3 разных значения

  • false - авторизация не пройдена
  • true - авторизация пройдена
  • undefined - статус ещё не определён, этот ответ возвращается ещё до попытки подключения к комет серверу

Определение мастер вкладки

В JavaScript API есть функция, которая из нескольких открытых вкладок назначает одну вкладку «главной» она называется мастер вкладкой, а все остальные вкладки определяются как salve вкладки. Функция isMaster возвращает true, если выполняется в контексте мастер вкладки и false если выполняется в контексте salave вкладки.

cometApi.isMaster()

Определение, какая вкладка является мастер вкладкой, а какая slave может быть полезно если вам надо сделать определённое действие только на одной вкладке, а не во всех. Например, у вас чат открыт на 3 страницах и при каждом входящем сообщении воспроизводится звуковое уведомление. В таком примере будет правильно если только одна вкладка будет воспроизводить звук а не все 3.

Больше подробностей про взаимодействие между вкладками смотрите в статье обмен сообщениями между вкладками браузера.

Примечание

В ряде примеров файл CometServerApi.js вставляется следующим образом:

<script src="//comet-server.ru/CometServerApi.js" type="text/javascript"></script>

Такой подход допустим только для тестов и в период разработки. Но не для постоянного использования. Так как по адресу http://comet-server.ru/CometServerApi.js расположена последняя на данный момент версия JavaScript Api и через некоторое время когда выйдет следующая версия JavaScript Api может случится так, что она не будет иметь полную обратную совместимость с той версией, которую использовали вы в период разработки. И ваше приложение может из-за этого начать работать не верно или просто сломается.

Для предотвращения такой ситуации надо просто 1 раз скачать файл CometServerApi.js на свой сервер и потом использовать именно его до тех пор, пока вам не понадобится обновить CometServerApi.js

Дополнительная информация

Обсуждение

Никита, 2015/09/28 16:13

Как получить кол-во человек в канале?

Trapenok Victor, 2015/10/16 16:03

В новой версии JS API есть функция count_users_in_pipe

CometServer().count_users_in_pipe("web_chat_pipe", function(res)
{
    console.log("count_users_in_pipe", res, res.data.user_in_pipe)
})

PS: Добавил в документацию информацию по этой функции.

Владимир Пономарь, 2015/10/14 23:09

Есть ли возможность отправлять личные сообщения авторизованным пользователям?

Trapenok Victor, 2015/10/16 16:03

Да такая возможность есть. Вот описание этого момента:

Подписка на сообщения от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя)

CometServer().subscription("msg", function(e){ console.log(e)})

Подписка на сообщения с именем события «имя_события» от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя)

CometServer().subscription("msg.имя_события", function(e){ console.log(e)})
Роман, 2016/05/24 23:58

Здравствуйте. А можно как то отписаться от всех каналов сразу? CometServer().unsubscription() не помогло.

Trapenok Victor, 2016/05/30 09:02

Добрый день. Теперь вызов CometServer().unsubscription() отписывает вас от всех каналов сразу.

Fedot Soldier, 2019/01/03 00:46

Функция для получения пользователей онлайн:

cometApi.count_users_in_pipe(«web_chat_pipe», function(res) {

  console.log("count_users_in_pipe", res, res.data.user_in_pipe)

})

В данном случае res - это список, состоящий из двух элементов - «user_in_pipe» и числа - этого кол-ва пользователей. Поэтому обращаться нужно ко второму элементу списка, а не словаря по ключу «user_in_pipe». Значит обращаться нужно так: console.log(«count_users_in_pipe», res, res.data[1]);

Ваш комментарий. Вики-синтаксис разрешён:
W O᠎ B W S