Различия
Здесь показаны различия между двумя версиями данной страницы.
|
comet:javascript_api [2018/02/24 11:57] anastation468 [Определение мастер вкладки] |
comet:javascript_api [2019/12/18 01:58] |
||
|---|---|---|---|
| Строка 1: | Строка 1: | ||
| - | <rst>RU::002-API::001-JavaScript API</rst> | ||
| - | <rst>Header:JavaScript API</rst> | ||
| - | |||
| - | ====== JavaScript API ====== | ||
| - | |||
| - | * [[http://comet-server.com/CometServerApi.js|Скачать CometServerApi.js]] | ||
| - | * [[https://github.com/Levhav/CometServerApi.js|GitHab репозиторий с CometServerApi.js]] | ||
| - | |||
| - | ====== Соединение с сервером ====== | ||
| - | |||
| - | |||
| - | Функция start принимает настройки соединения и открывает соединение. Здесь opt – это объект с опциями подключения. | ||
| - | <code JavaScript>cometApi.start({dev_id:15, user_id:1, user_key:"userHash", node:"app.comet-server.ru"})</code> | ||
| - | * dev_id обязательный параметр это [[comet:dev_id|публичный ключ разработчика]]. | ||
| - | * user_id не обязательный параметр, это идентификатор пользователя нужен для [[comet:authentication|авторизации пользователя]] на комет сервере | ||
| - | * user_key не обязательный параметр, это хеш авторизации пользователя нужен для [[comet:authentication|авторизации пользователя]] на комет сервере | ||
| - | * node - если вы разворачиваете [[https://github.com/CppComet/comet-server|CppComet]] на своём сервере, то надо указать адрес вашего сервера ( Если комет сервер работает не на 80 порту то обязательно надо указать порт например так node:"app.comet-server.ru:8087" ) | ||
| - | |||
| - | Для переподключения к серверу используйте функцию restart | ||
| - | <code JavaScript>cometApi.restart({dev_id:15, user_id:1, user_key:"userHash"})</code> | ||
| - | При переподключении вы можете переопределить параметры подключения или оставить их прежними. | ||
| - | ====== Подписка на получение сообщений из канала ====== | ||
| - | |||
| - | Функция subscription добавляет подписки на каналы, события в каналах и отчёты о доставке сообщений в каналы. | ||
| - | Для подписки на сообщения в канале: | ||
| - | <code JavaScript>cometApi.subscription("имя_канала", function(data){ console.log(data) } )</code> | ||
| - | * Первый аргумент - имя канала должно быть короче 32 символов и должно состоять из символов A-Za-z0-9 и символа минус и знака подчёркивания. | ||
| - | * Второй аргумент - callback функция, которая будет вызвана при получении сообщения из этого канала. | ||
| - | |||
| - | Обратите внимание, что телом сообщения может быть json строка. Если это так, то она автоматически будет преобразована в объект. | ||
| - | <code JavaScript>cometApi.subscription( "pipe_name.event_name", function(e){ console.log(["event", e])})</code> | ||
| - | Подписка на канал "Имя_канала" | ||
| - | <code JavaScript>cometApi.subscription("Имя_канала", function(e){ console.log(e)})</code> | ||
| - | Подписка на канал событие "имя_события" в канале "Имя_канала" | ||
| - | <code JavaScript>cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})</code> | ||
| - | Подписка на отчёт о доставке в канал "Имя_канала" | ||
| - | <code JavaScript>cometApi.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?]] | ||
| - | |||
| - | ====== Отписка от получения сообщений из канала ====== | ||
| - | |||
| - | Функция subscription возвращает строку subscription_id, которая нам может понадобится, если мы захотим отписать функцию от получения сообщений. | ||
| - | <code JavaScript>var subscriptionId = cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})</code> | ||
| - | |||
| - | Для отписки от получения сообщений вызовите | ||
| - | <code JavaScript>cometApi.unsubscription(subscriptionId)</code> | ||
| - | |||
| - | ====== Зарезервированные имена каналов ====== | ||
| - | |||
| - | Основная статья [[comet:javascript_api:pipe-types|зарезервированные имена каналов]] | ||
| - | <note warning>Не рекомендуется использовать в своих проектах имена каналов вида "bin_*", "big_*", "push_*", "comet_*", "self_*", "trust_*" и "sys_*" эти имена возможно будут использованы для дальнейшего расширения функционала. И будут иметь какие-нибудь необычные свойства по сравнению с другими именами каналов.</note> | ||
| - | |||
| - | |||
| - | Так же есть каналы с особыми свойствами, о всех них ниже по тексту. | ||
| - | * msg - Для доставки личных сообщений в соответствии с данными авторизации | ||
| - | * user_status_* - для автоматического уведомления JS api о статусе пользователей | ||
| - | * web_* - Каналы в которые можно отправлять сообщения как из CometQL так и из JS api | ||
| - | * track_* - для автоматического уведомления JS api о том что кто то подписался или отписался от этого канала | ||
| - | ====== Подписка на получение личных сообщений ( канал msg )====== | ||
| - | Подписка на сообщения от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя) | ||
| - | <code JavaScript>cometApi.subscription("msg", function(e){ console.log(e)})</code> | ||
| - | Подписка на сообщения с именем события "имя_события" от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя) | ||
| - | <code JavaScript>cometApi.subscription("msg.имя_события", function(e){ console.log(e)})</code> | ||
| - | |||
| - | <note tip>Более подробно про механизм авторизации на комет сервере и про личные сообщения смотрите в статье [[comet:authentication|Авторизация пользователей на комет сервере]]</note> | ||
| - | |||
| - | ====== Подписка на изменение статуса пользователя ( каналы user_status_* )====== | ||
| - | |||
| - | Есть возможность из JS подписаться на уведомления о том, когда определённый пользователь авторизуется на комет сервере или на оборот отключится от него. | ||
| - | |||
| - | Когда пользователь на комет сервере авторизуется, то комет сервер автоматически отправляет сигнал в канал user_status_{идентификатор пользователя} с именем события online. А когда авторизованный пользователь уходит в offline то комет сервер тоже генерирует событие. | ||
| - | |||
| - | <code JavaScript> | ||
| - | // Подписываемся на уведомление о том, что пользователь с 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") | ||
| - | }) | ||
| - | </code> | ||
| - | |||
| - | |||
| - | ====== Список пользователей онлайн ( каналы track_* )====== | ||
| - | |||
| - | Каналы с именем вида track_* автоматически генерируют события subscription и unsubscription внутри себя каждый раз как кто-то подписывается или отписывается от этого канала | ||
| - | |||
| - | <code JavaScript> | ||
| - | cometApi.subscription("track_online.subscription", function(msg) | ||
| - | { | ||
| - | // Обработка события что кто то зашёл на сайт и подписался на канал track_online | ||
| - | }); | ||
| - | cometApi.subscription("track_online.unsubscription", function(msg) | ||
| - | { | ||
| - | // Обработка события что кто-то покинул сайт и/или отписался от канала track_online | ||
| - | }); | ||
| - | </code> | ||
| - | |||
| - | Этот вид каналов создан специально для облегчения создания динамически обновляемых списков пользователей онлайн. | ||
| - | Основная статья [[comet:faq:realtime-users-list|список пользователей онлайн]] | ||
| - | |||
| - | ====== Отправка сообщений в канал из JS (каналы web_*) ====== | ||
| - | |||
| - | Функция web_pipe_send позволяет из JavaScript отправлять сообщения в канал минуя ваш сервер, то есть напрямую обращаясь к comet серверу. | ||
| - | Это позволяет пересылать сообщения между клиентами вообще не загружая ваш сервер. | ||
| - | Так же благодаря обращению на прямую к comet серверу время доставки сообщения от клиента к клиенту минимально. | ||
| - | |||
| - | <note important>Отправлять сообщения в канал из JavaScript можно только если имя канала начинается с web_ в то время как для CometQL такого ограничения нет.</note> | ||
| - | |||
| - | <code JavaScript>cometApi.web_pipe_send("web_pipe_name", "event_name", "message")</code> | ||
| - | |||
| - | Для того, чтобы получить отчёт о доставке сообщения в канал "Имя_канала" используйте subscription | ||
| - | <code JavaScript>cometApi.subscription("#Имя_канала", function(e){ console.log(e)})</code> | ||
| - | |||
| - | Так как комет сервер поддерживает авторизацию пользователей, он сам добавляет id пользователя к сообщению таким образом что пользователь отправивший сообщение не может отправить чужой id. Для отключения этой возможности надо добавить символ "@" перед именем канала, в который отправляется сообщение. В таком случае, доставленное сообщение будет выглядеть так, как будто его отправил не авторизованный пользователь. | ||
| - | <code JavaScript>cometApi.web_pipe_send("@web_pipe_name", "event_name", "message")</code> | ||
| - | |||
| - | Пример чата на основе отправки сообщений из JavaScript Api прямо в комет сервер | ||
| - | <html> | ||
| - | <script async src="//jsfiddle.net/07noamea/3/embed/"></script> | ||
| - | </html> | ||
| - | |||
| - | ======= Формат входящих сообщений ======= | ||
| - | <code> | ||
| - | data: {} // Сообщение пользователя | ||
| - | server_info: | ||
| - | event: "undefined" // Имя события | ||
| - | history: false // Если true то это данные загружаемые из истории канала а не пришедшие сейчас | ||
| - | marker: undefined // Специальный идентификатор, определён только когда history равно true | ||
| - | pipe: "web_chat_pipe" // Имя канала которому адресовано сообщение | ||
| - | user_id: 0 // Id отправителя, если 0 то не задан. Будет добавляется автоматически если человек отправивший сообщение в канал авторизован на комет сервере. | ||
| - | </code> | ||
| - | |||
| - | Поле server_info.user_id в приходящем сообщении заполняется чем то кроме нуля только если сообщение отправлено в канал из JavaScript API и при этом отправитель прошёл авторизацию на комет сервере. | ||
| - | Оно содержит user_id отправителя. | ||
| - | |||
| - | ======= Получение последних сообщений из канала ======= | ||
| - | В комет сервере есть возможность для некоторых каналов включить механизм запоминания последних N сообщений через них. | ||
| - | <note tip>Логирование проходящих сообщений можно включить запросом CometQL к [[comet:cometql#таблица_pipes_settings|таблице pipes_settings]].</note> | ||
| - | |||
| - | Если функция логирования включена, то вызов метода get_pipe_log инициирует отправку всех сообщений из истории в канале на клиент. | ||
| - | <code JavaScript>cometApi.get_pipe_log("web_pipe_name")</code> | ||
| - | Сообщения пришедшие из истории канала будут иметь свойство history=true | ||
| - | |||
| - | ======= Получение количества подписчиков в канале ======= | ||
| - | |||
| - | Функция count_users_in_pipe даёт возможность узнать количество подписчиков в канале. | ||
| - | |||
| - | У функции count_users_in_pipe первый аргумент это имя канала, а вторым аргументом передаётся callback функция, в которую будет передан ответ. | ||
| - | <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> | ||
| - | |||
| - | Но в отличии от [[comet:cometql|CometQL]] запроса эта функция может показывать количество подписчиков только в тех каналах, у которых имя начинается с web_ к примеру для канала web_chat_pipe она сработает, а для канала chat_pipe не сработает. Это ограничение введено для того, чтобы была возможность создать такой канал, в котором количество подписчиков не сможет узнать кто-попало через js api | ||
| - | |||
| - | ======= Определение статуса авторизации на комет сервере ======= | ||
| - | |||
| - | Основная статья [[comet:authentication|авторизация на комет сервере]] | ||
| - | |||
| - | У комет сервера есть возможность [[comet:authentication|авторизации пользователей]]. Авторизация может быть полезна для того что бы была возможность определить кто именно отправил сообщение в канал или для адресной отправки сообщений пользователям. | ||
| - | |||
| - | Из JavaScript api вы можете отслеживать изменение статуса авторизации на комет сервере. | ||
| - | <code JavaScript> | ||
| - | // Добавление callBack функции на уведомление об успешной авторизации | ||
| - | cometApi.onAuthSuccess(function(){ | ||
| - | console.log("Подключились и авторизовались успешно") | ||
| - | }) | ||
| - | |||
| - | // Добавление callBack функции на уведомление об не успешной авторизации | ||
| - | cometApi.onAuthFalill(function(){ | ||
| - | console.log("Подключились успешно но не авторизовались") | ||
| - | }) | ||
| - | </code> | ||
| - | Эти функции будут вызваны в момент смены статуса авторизации. То есть как минимум один раз при подключении к комет серверу и при каждой смене статуса если в момент работы скрипта авторизация пропадёт или на оборот произойдёт. | ||
| - | |||
| - | Так же в любой момент времени можно вызвать функцию isAuthorized для определения статуса авторизации. | ||
| - | <code JavaScript>cometApi.isAuthorized()</code> | ||
| - | Функция isAuthorized может вернуть 3 разных значения | ||
| - | * false - авторизация не пройдена | ||
| - | * true - авторизация пройдена | ||
| - | * undefined - статус ещё не определён, этот ответ возвращается ещё до попытки подключения к комет серверу | ||
| - | |||
| - | ======= Определение мастер вкладки ======= | ||
| - | |||
| - | В JavaScript API есть функция, которая из нескольких открытых вкладок назначает одну вкладку "главной" она называется мастер вкладкой, а все остальные вкладки определяются как salve вкладки. Функция isMaster возвращает true, если выполняется в контексте мастер вкладки и false если выполняется в контексте salave вкладки. | ||
| - | |||
| - | <code JavaScript>cometApi.isMaster()</code> | ||
| - | |||
| - | Определение, какая вкладка является мастер вкладкой, а какая slave может быть полезно если вам надо сделать определённое действие только на одной вкладке, а не во всех. | ||
| - | Например, у вас чат открыт на 3 страницах и при каждом входящем сообщении воспроизводится звуковое уведомление. В таком примере будет правильно если только одна вкладка будет воспроизводить звук а не все 3. | ||
| - | |||
| - | Больше подробностей про взаимодействие между вкладками смотрите в статье [[https://habrahabr.ru/company/comet-server/blog/250719/|обмен сообщениями между вкладками браузера]]. | ||
| - | |||
| - | |||
| - | ======= Примечание ======= | ||
| - | |||
| - | В ряде примеров файл CometServerApi.js вставляется следующим образом: | ||
| - | <code html> | ||
| - | <script src="//comet-server.ru/CometServerApi.js" type="text/javascript"></script> | ||
| - | </code> | ||
| - | Такой подход допустим только для тестов и в период разработки. Но не для постоянного использования. Так как по адресу [[http://comet-server.ru/CometServerApi.js]] расположена последняя на данный момент версия JavaScript Api и через некоторое время когда выйдет следующая версия JavaScript Api может случится так что она не будет иметь полную обратную совместимость с той версией которую использовали вы в период разработки. И ваше приложение может из за этого начать работать не верно или просто сломается. | ||
| - | |||
| - | Для предотвращения такой ситуации надо просто 1 раз скачать файл CometServerApi.js на свой сервер и потом использовать именно его до тех пор пока вам не понадобится обновить CometServerApi.js | ||
| - | |||
| - | ====== Дополнительная информация ====== | ||
| - | |||
| - | * [[comet:javascript_api:pipe-types|Зарезервированные имена каналов]] | ||
| - | * [[comet:cometql|CometQL API]] | ||
| - | * [[comet:testhosting|Почему скрипт работает на локальной машине и не работает на хостинге? ]] | ||
| - | * [[comet:faq:public_key|Что такое и зачем нужен "Публичный идентификатор разработчика" и "Секретный ключ разработчика"?]] | ||
| - | * [[comet:faq:send-message-to-pipe|Как отправить сообщение в произвольный канал и как его потом получить на другой странице?]] | ||
| - | * [[comet:faq:realtime-users-list|Как реализовать механизм отслеживания вхождения пользователей на сайт. То есть список посетителей обновляющийся на "лету"?]] | ||
| - | * [[comet:faq:access-to-channels-for-outsiders|Может ли кто то посторонний получать сообщение из каналов]] | ||