Различия

Здесь показаны различия между двумя версиями данной страницы.

Ссылка на это сравнение

Предыдущая версия справа и слева Предыдущая версия
Следующая версия
Предыдущая версия
comet:javascript_api [2017/07/26 10:20]
levhav
comet:javascript_api [2019/12/18 01:58] (текущий)
Строка 1: Строка 1:
 <​rst>​RU::​002-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/​|обмен сообщениями между вкладками браузера]].
- 
- 
- 
  
  
Строка 211: Строка 209:
 <script src="//​comet-server.ru/​CometServerApi.js"​ type="​text/​javascript"></​script>​ <script src="//​comet-server.ru/​CometServerApi.js"​ type="​text/​javascript"></​script>​
 </​code>​ </​code>​
-Такой подход допустим только для тестов и в период разработки. Но не для постоянного использования. Так как по адресу [[http://​comet-server.ru/​CometServerApi.js]] расположена последняя на данный момент версия JavaScript Api и через некоторое время когда выйдет следующая версия JavaScript Api может случится так что она не будет иметь полную обратную совместимость с той версией которую использовали вы в период разработки. И ваше приложение может из за этого начать работать не верно или просто сломается.+Такой подход допустим только для тестов и в период разработки. Но не для постоянного использования. Так как по адресу [[http://​comet-server.ru/​CometServerApi.js]] расположена последняя на данный момент версия JavaScript Api и через некоторое время когда выйдет следующая версия JavaScript Api может случится такчто она не будет иметь полную обратную совместимость с той версиейкоторую использовали вы в период разработки. И ваше приложение может из-за этого начать работать не верно или просто сломается.
  
-Для предотвращения такой ситуации надо просто 1 раз скачать файл CometServerApi.js на свой сервер и потом использовать именно его до тех пор пока вам не понадобится обновить CometServerApi.js+Для предотвращения такой ситуации надо просто 1 раз скачать файл CometServerApi.js на свой сервер и потом использовать именно его до тех порпока вам не понадобится обновить CometServerApi.js
  
 ====== Дополнительная информация ====== ====== Дополнительная информация ======