FastComments.com

Menu Icon

Язык 🇷🇺 Русский
🇺🇸 English 🇧🇬 Български 🇨🇳 简体中文 🇹🇼 繁體中文 🇭🇷 Hrvatski 🇩🇰 Dansk 🇳🇱 Nederlands 🇫🇷 Français (France) 🇩🇪 Deutsch 🇬🇷 Ελληνικά 🇮🇱 עברית 🇮🇳 हिन्दी 🇮🇹 Italiano 🇯🇵 日本語 🇰🇷 한국어 🇵🇱 Polski 🇧🇷 Português (Brasil) 🇷🇺 Русский 🇷🇸 Srpski (Latinica) 🇷🇸 Српски 🇸🇮 Slovenščina 🇪🇸 Español 🇺🇦 Українська 🇹🇷 Türkçe

Начало работы

Начало работы
Примеры
Добавление живых комментариев в онлайн-книги

Конфигурация

Параметры конфигурации
Поведение выделения текста

Настройка

Настройка

Продвинутые

Живая синхронизация
Справочник API

Чат для совместной работы

Добавление встроенных живых комментариев в документы, книги и т. д.

FastComments Collab Chat позволяет пользователям выделять и аннотировать любой текстовый контент на вашем сайте, создавая древовидные обсуждения, привязанные к конкретным выделениям текста. Пользователи могут выбирать слова, предложения или целые абзацы, чтобы начинать совместные обсуждения непосредственно в вашем контенте.

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

Обратите внимание, что эти документы относятся конкретно к функциональности Collab Chat. Вы можете добавить возможность комментирования для контента с большим количеством страниц, например Books, с thread-per-page, без использования collab chat. FastComments также не взимает плату за страницу или за тред. Collab Chat — это именно тогда, когда вы хотите позволить пользователям выделять текст и комментировать выделенный фрагмент текста.

Вы можете увидеть пример здесь.

Начало работы Internal Link

Быстрый старт

Начать работу с Collab Chat просто. Вам понадобятся скрипт FastComments Collab Chat, HTML-элемент с текстом, который вы хотите аннотировать, и объект конфигурации с вашим Tenant ID.

Установка

Добавьте скрипт Collab Chat на вашу страницу:

Загрузка скрипта Collab Chat
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
3

Базовая реализация

Вот минимальный пример:

Базовая реализация Collab Chat
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat</title>
6</head>
7<body>
8 <!-- Ваш контейнер с контентом -->
9 <div id="article-content" style="min-height: 500px;">
10 <h1>My Article Title</h1>
11 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
12 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
13 </div>
14
15 <!-- Загрузите скрипт Collab Chat -->
16 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
17
18 <!-- Инициализируйте Collab Chat -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

Замените 'demo' на ваш реальный FastComments Tenant ID, если ещё не сделали этого. Его можно найти в вашей панели управления FastComments.

Как это работает

После инициализации пользователи могут выделять любой текст внутри целевого элемента. После небольшой задержки (3,5 секунды на десктопе) появляется подсказка, позволяющая начать обсуждение. Когда обсуждение создано, на тексте появляется визуальное выделение. Другие пользователи могут навести курсор на выделение или кликнуть по нему, чтобы просмотреть обсуждение и принять в нём участие. Все обсуждения синхронизируются в реальном времени у всех посетителей.

Живое демо

Вы можете увидеть Collab Chat в действии на нашей странице живого демо.

Следующие шаги

Теперь, когда основы работают, вы можете настроить внешний вид и поведение в руководстве по параметрам конфигурации (Configuration Options). Ознакомьтесь с руководством по поведению выделения текста (Text Selection Behavior), чтобы понять, как работает выделение текста. Узнайте о стилизации и поддержке тёмной темы в руководстве по кастомизации (Customization). Для продвинутых интеграций изучите справочник API (API Reference).

Фронтенд-библиотеки

Все фронтенд-библиотеки FastComments (react, vue, angular и т.д.) поддерживают Collab Chat.

Примеры Internal Link

Базовый пример

Самый простой способ использовать Collab Chat — нацелиться на один контейнер с содержимым. Этот пример показывает, как включить аннотации текста в статье:

Базовый пример Collab Chat
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat</title>
6</head>
7<body>
8 <div id="article-content" style="min-height: 500px">
9 <h1>My Article Title</h1>
10 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
11 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
12 </div>
13
14 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
15 <script>
16 FastCommentsCollabChat(document.getElementById('article-content'), {
17 tenantId: 'demo'
18 });
19 </script>
20</body>
21</html>
22

Пример с пользовательским URL ID (для страницы книги, статьи и т.д.)

По умолчанию Collab Chat использует URL страницы в сочетании с путём к элементу и диапазоном текста для идентификации бесед. Вы можете указать собственный urlId, чтобы лучше контролировать, как группируются беседы:

Collab Chat с пользовательским URL ID
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
3<script>
4 FastCommentsCollabChat(document.getElementById('article-content'), {
5 tenantId: 'demo',
6 urlId: 'book-one-page-2'
7 });
8</script>
9

Это полезно, если структура ваших URL меняется, но вы хотите сохранить те же беседы, или если вы хотите разделять одни и те же аннотации бесед между несколькими страницами.

Пример с тёмным режимом

Если на вашем сайте тёмный фон, включите поддержку тёмного режима, чтобы интерфейс чата отображался корректно:

Collab Chat в тёмном режиме
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat - Dark Mode</title>
6 <style>
7 body {
8 background-color: #1a1a1a !important;
9 color: #e0e0e0 !important;
10 font-family: system-ui, -apple-system, sans-serif;
11 padding: 20px;
12 margin: 0;
13 }
14 #article-content {
15 max-width: 800px;
16 margin: 0 auto;
17 background-color: #2d2d2d;
18 padding: 20px;
19 border-radius: 8px;
20 }
21 h1 {
22 color: #ffffff !important;
23 }
24 p {
25 color: #e0e0e0 !important;
26 line-height: 1.6;
27 }
28 .fastcomments-collab-chat-top-bar {
29 background-color: #2d2d2d !important;
30 color: #e0e0e0 !important;
31 border-bottom: 1px solid #444 !important;
32 }
33 </style>
34</head>
35<body>
36 <div id="article-content" style="min-height: 500px">
37 <h1>My Article Title</h1>
38 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
39 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
40 </div>
41
42 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
43 <script>
44 FastCommentsCollabChat(document.getElementById('article-content'), {
45 tenantId: 'demo',
46 hasDarkBackground: true
47 });
48 </script>
49</body>
50</html>
51

Пример с отключённой верхней панелью

По умолчанию Collab Chat показывает верхнюю панель с количеством пользователей и количеством обсуждений. Вы можете её отключить:

Collab Chat с отключённой верхней панелью
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat - No Top Bar</title>
6</head>
7<body>
8 <div id="article-content" style="min-height: 500px">
9 <h1>My Article Title</h1>
10 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
11 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
12 </div>
13
14 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
15 <script>
16 FastCommentsCollabChat(document.getElementById('article-content'), {
17 tenantId: 'demo',
18 topBarTarget: null
19 });
20 </script>
21</body>
22</html>
23

Пример с обратным вызовом подсчёта комментариев

Вы можете отслеживать добавление или обновление комментариев с помощью обратного вызова commentCountUpdated:

Collab Chat с обратным вызовом обновления количества комментариев
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
3<script>
4 FastCommentsCollabChat(document.getElementById('article-content'), {
5 tenantId: 'demo',
6 commentCountUpdated: function(count) {
7 console.log('Total comments:', count);
8 document.getElementById('comment-badge').textContent = count;
9 }
10 });
11</script>
12

Пример с несколькими разделами

Вы можете инициализировать Collab Chat в нескольких отдельных разделах страницы. У каждого раздела будут свои независимые аннотации:

Collab Chat в нескольких разделах
Copy Copy
1
2<div id="intro-section">
3 <h2>Introduction</h2>
4 <p>Content for the introduction...</p>
5</div>
6
7<div id="main-section">
8 <h2>Main Content</h2>
9 <p>Content for the main article...</p>
10</div>
11
12<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
13<script>
14 // Инициализация для секции intro
15 FastCommentsCollabChat(document.getElementById('intro-section'), {
16 tenantId: 'demo',
17 urlId: 'my-article-intro'
18 });
19
20 // Инициализация для секции main
21 FastCommentsCollabChat(document.getElementById('main-section'), {
22 tenantId: 'demo',
23 urlId: 'my-article-main'
24 });
25</script>
26

Добавление живых комментариев в онлайн-книги Internal Link

Вы можете инициализировать Collab Chat для каждой страницы при необходимости и иметь отдельные ветки для каждой страницы — просто передайте параметру urlId значение вроде book-one-page1. Эта конфигурация также работает для обычного виджета комментариев.

Параметры конфигурации Internal Link

Обзор

FastComments Collab Chat расширяет стандартный виджет комментариев FastComments, поэтому он наследует все параметры конфигурации базового виджета, добавляя несколько специфичных для текстовых аннотаций.

Обязательная конфигурация

tenantId

Требуется ваш Tenant ID FastComments. Его можно найти в вашей панели управления FastComments.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo'
4});
5

Специфичные для Collab Chat параметры

urlId

По умолчанию Collab Chat генерирует уникальный идентификатор для каждого разговора на основе URL страницы, DOM-пути к элементу и выбранного диапазона текста. Вы можете переопределить это с помощью пользовательского urlId.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 urlId: 'my-custom-page-id'
5});
6

Это полезно, когда структура ваших URL может измениться, но вы хотите сохранить те же разговоры, или когда вы хотите делиться аннотациями между несколькими страницами.

topBarTarget

Управляет отображением верхней панели, которая показывает количество пользователей и обсуждений. Установите значение null, чтобы полностью отключить верхнюю панель, или укажите DOM-элемент, чтобы отобразить её в определённом месте.

Пример конфигурации
Copy Copy
1
2// Отключить верхнюю панель
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Отобразить верхнюю панель в пользовательском месте
9FastCommentsCollabChat(element, {
10 tenantId: 'demo',
11 topBarTarget: document.getElementById('custom-header')
12});
13

hasDarkBackground

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

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 hasDarkBackground: true
5});
6

commentCountUpdated

Функция обратного вызова, которая срабатывает при каждом изменении количества комментариев. Это полезно для обновления элементов интерфейса, таких как значки или заголовки страниц.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 commentCountUpdated: function(count) {
5 console.log('Total comments:', count);
6 document.getElementById('badge').textContent = count;
7 }
8});
9

Унаследованные параметры конфигурации

Поскольку Collab Chat расширяет стандартный виджет комментариев, вы можете использовать любой параметр конфигурации базового виджета FastComments. Вот некоторые часто используемые параметры:

locale

Устанавливает язык интерфейса виджета. FastComments поддерживает десятки языков.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Spanish
5});
6

readonly

Делает все разговоры доступными только для чтения. Пользователи могут просматривать существующие аннотации, но не могут создавать новые или отвечать.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 readonly: true
5});
6

sso и simpleSSO

Интеграция с вашей системой аутентификации с использованием Single Sign-On.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 sso: {
5 // SSO configuration
6 }
7});
8

Подробную информацию о параметрах аутентификации см. в документации по SSO.

maxReplyDepth

Управляет глубиной вложенности ответов. По умолчанию Collab Chat устанавливает значение 0, что означает, что все комментарии плоские (без вложенных ответов). Вы можете изменить это, если хотите использовать ветвящиеся разговоры.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Allow 3 levels of nesting
5});
6

Внутренняя конфигурация

Эти параметры устанавливаются Collab Chat автоматически и не должны переопределяться:

Параметр productId автоматически устанавливается в 3 для Collab Chat. Расширение floating-chat автоматически загружается для обеспечения функциональности окна чата. Виджет автоматически определяет мобильные устройства (экраны шириной менее 768px) и соответствующим образом адаптирует интерфейс.

Полный пример

Вот пример, показывающий несколько параметров конфигурации вместе:

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(document.getElementById('article'), {
3 tenantId: 'demo',
4 urlId: 'my-article-v2',
5 hasDarkBackground: false,
6 locale: 'en',
7 topBarTarget: document.getElementById('custom-header'),
8 commentCountUpdated: function(count) {
9 document.title = count > 0 ? `(${count}) My Article` : 'My Article';
10 },
11 sso: {
12 // Your SSO config
13 },
14 maxReplyDepth: 1
15});
16

Полный список всех доступных параметров конфигурации, унаследованных от базового виджета, см. в основной документации по конфигурации FastComments.

Поведение выделения текста Internal Link

Как работает выделение текста

Когда пользователи выделяют текст внутри контейнера Collab Chat, виджет захватывает это выделение и позволяет начать обсуждение. Выделение может быть размером с одно слово или охватывать несколько абзацев в разных элементах.

Задержка выделения

На настольных устройствах есть задержка в 3,5 секунды между моментом выделения текста пользователем и появлением приглашения к обсуждению. Это предотвращает мерцание интерфейса, когда пользователи просто выделяют текст для копирования или чтения. На мобильных устройствах приглашение появляется сразу, так как выделение текста на сенсорных экранах более обдуманное.

Уникальные идентификаторы обсуждений

Каждое обсуждение получает уникальный urlId, который объединяет URL страницы, путь к элементу DOM и сериализованный диапазон текста. Это гарантирует, что каждое выделение текста создаёт отдельное обсуждение, которое можно найти позже.

Если вы укажете собственный urlId в конфигурации, он будет объединён с путём к элементу и текстовым диапазоном для создания итогового идентификатора.

Визуальные выделения

Когда для определённого выделения текста существует обсуждение, этот текст получает визуальное выделение. Выделение реализуется с помощью цветов фона и отображается при наведении курсора или когда открыто связанное окно чата.

Система выделения работает путём обёртывания выделенного текста в специальный элемент, который можно стилизовать. Такой подход гарантирует, что выделения остаются точными даже при сложной HTML-структуре.

Позиционирование окна чата

Когда пользователь нажимает на выделение или создаёт новую аннотацию, окно чата появляется рядом с выделенным текстом. Виджет автоматически рассчитывает наилучшее положение для этого окна на основе доступного пространства области просмотра.

Система позиционирования использует CSS-классы, такие как to-right, to-left, to-top и to-bottom, чтобы указать, в каком направлении окно чата должно расширяться от выделения. На мобильных устройствах (экраны шириной менее 768px) окно чата всегда отображается на весь экран для удобства использования.

Размеры окна чата

Окна чата имеют ширину 410px на настольных устройствах с отступом 20px и визуальной стрелкой 16px, указывающей на выделенный текст. Эти размеры фиксированы для обеспечения согласованного поведения, но вы можете настроить внешний вид с помощью CSS.

Выделения между элементами

Пользователи могут выделять текст, охватывающий несколько HTML-элементов, например, выделяя от середины одного абзаца до начала другого. Система сериализации диапазонов корректно обрабатывает такие случаи и выделяет весь выбранный текст даже через границы элементов.

Совместимость с браузерами

Система выделения текста использует стандартный API window.getSelection(), который поддерживается во всех современных браузерах. Для старых версий Internet Explorer используется резервный механизм document.selection для совместимости.

Сохранение выделений

После создания обсуждения для выделенного текста аннотация сохраняется даже при перезагрузке страницы. Сериализованный диапазон и путь DOM позволяют виджету восстановить выделения точно в том же месте, когда пользователи возвращаются на страницу.

Это работает надёжно, пока содержимое вашей страницы остаётся стабильным. Если вы измените текстовое содержимое или реструктурируете HTML, существующие аннотации могут больше не соответствовать тексту. По этой причине лучше избегать серьёзных изменений контента на страницах с активными аннотациями или рассмотреть возможность миграции аннотаций, когда изменения контента необходимы.

Настройка Internal Link

Поддержка тёмного режима

Динамический тёмный режим

Если тёмный режим на вашем сайте управляется добавлением класса .dark к элементу body, интерфейс Collab Chat будет автоматически учитывать это без необходимости повторной инициализации. Стили виджета разработаны так, чтобы реагировать на наличие этого класса.

Пример CSS для тёмного режима
Copy Copy
1
2/* Ваш CSS для тёмного режима */
3body.dark {
4 background: #1a1a1a;
5 color: #ffffff;
6}
7

Пользовательская стилизация с помощью CSS

Вы можете настраивать внешний вид подсветок, окон чата и других элементов с помощью CSS. Виджет добавляет специальные классы, которые вы можете таргетировать в своей таблице стилей.

Подсветки текста используют систему оформления пузырьков комментариев FastComments, поэтому любые изменения, которые вы применили к стандартному виджету комментариев, также повлияют на Collab Chat.

Настройка верхней панели

Верхняя панель показывает количество пользователей онлайн и количество обсуждений. Вы можете настроить её позицию, предоставив пользовательский элемент в качестве topBarTarget:

Пользовательское расположение верхней панели
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: document.getElementById('my-custom-header')
5});
6

Или полностью отключить, установив null:

Отключить верхнюю панель
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: null
5});
6

Поведение на мобильных устройствах

На экранах шириной меньше 768px Collab Chat автоматически переключается на оптимизированную для мобильных устройств раскладку. Окна чата появляются на весь экран вместо плавающих рядом с текстом, а задержка при выделении убирается для более мгновенного взаимодействия.

Это поведение встроено и не требует никакой конфигурации. Виджет автоматически определяет размер экрана и соответствующим образом подстраивается.

Внешний вид окна чата

Окна чата имеют ширину 410px на десктопах с указателем-стрелкой 16px, указывающим на выделенный текст. Окна автоматически позиционируются в зависимости от доступного пространства в окне просмотра, используя классы позиционирования, такие как to-right, to-left, to-top и to-bottom.

Вы можете добавить пользовательский CSS, чтобы настроить цвета, шрифты, отступы или другие визуальные свойства этих окон. Окна чата используют ту же структуру компонентов, что и стандартный виджет FastComments, поэтому они наследуют любые глобальные настройки, которые вы применили.

Локализация

Collab Chat поддерживает все те же параметры локализации, что и стандартный виджет FastComments. Установите опцию locale, чтобы отображать текст интерфейса на разных языках:

Установить локаль
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Испанский
5});
6

FastComments поддерживает десятки языков. Настройка локали влияет на весь текст интерфейса, включая подсказки, кнопки и текст-плейсхолдеры.

Унаследованные параметры настройки

Поскольку Collab Chat расширяет стандартный виджет комментариев, он наследует все параметры настройки базового виджета. Это включает пользовательские CSS-классы, пользовательские переводы, настройку аватаров, форматирование дат и многое другое.

См. основную документацию по настройке FastComments для полного списка доступных параметров настройки.

Работа с пользовательскими шрифтами

Если на вашем сайте используются пользовательские шрифты, интерфейс Collab Chat унаследует эти шрифты из CSS вашей страницы. Возможно, вам придётся создать правило кастомизации виджета и @import все шрифты в пользовательском CSS в этом правиле, если вы хотите, чтобы плавающее окно чата использовало те же шрифты.

Живая синхронизация Internal Link

Обновления в реальном времени

Collab Chat использует WebSocket-соединения для синхронизации всех разговоров в реальном времени между всеми подключёнными пользователями. Когда кто-то создаёт новую аннотацию, добавляет комментарий или удаляет обсуждение, все остальные пользователи, просматривающие ту же страницу, видят обновление мгновенно без перезагрузки.

Как работает синхронизация WebSocket

Когда вы инициализируете Collab Chat, виджет устанавливает WebSocket-соединение с серверами FastComments. Это соединение остаётся открытым на протяжении сессии пользователя и слушает обновления, связанные с текущей страницей.

Система WebSocket использует три типа широковещательных сообщений для Collab Chat. Событие new-text-chat срабатывает, когда кто-то создаёт новую аннотацию на странице. Событие updated-text-chat срабатывает, когда кто-то обновляет существующую беседу. Событие deleted-text-chat срабатывает, когда кто-то удаляет аннотацию.

Система Broadcast ID

Чтобы предотвратить эффект эха, когда пользователи видят свои собственные действия, транслируемые обратно им, каждое обновление включает уникальный broadcastId. Когда пользователь создаёт или обновляет аннотацию, его клиент генерирует UUID для этой операции. Когда WebSocket транслирует обновление обратно всем клиентам, исходный клиент игнорирует обновление, потому что оно совпадает с его собственным broadcastId.

Это обеспечивает плавное взаимодействие: пользователи видят свои изменения сразу в интерфейсе без ожидания кругового прохода через сервер, при этом все остальные пользователи получают обновление.

Количество пользователей в реальном времени

В верхней панели отображается количество пользователей, которые в данный момент просматривают страницу. Это число обновляется в реальном времени по мере присоединения и выхода пользователей. Количество пользователей передаётся через то же WebSocket-соединение и автоматически увеличивается/уменьшается на основе событий подключения и отключения.

Устойчивость соединения

Если WebSocket-соединение прерывается из‑за проблем с сетью или обслуживания сервера, виджет автоматически пытается переподключиться. В период переподключения пользователи всё ещё могут взаимодействовать с существующими аннотациями, но они не будут видеть обновления в реальном времени от других пользователей до восстановления соединения.

После восстановления соединения виджет повторно синхронизируется, чтобы убедиться, что никакие обновления не были пропущены. Это происходит прозрачно и не требует действий со стороны пользователя.

Требования к пропускной способности

Сообщения WebSocket лёгкие и содержат только необходимую информацию для синхронизации состояния. Создание новой аннотации обычно использует меньше 1KB трафика. Система также включает интеллектуальную пакетную отправку, чтобы уменьшить частоту сообщений в периоды высокой активности.

Ваши метрики использования на панели управления FastComments отслеживают pubSubMessageCount и pubSubBandwidth, чтобы вы могли контролировать активность синхронизации в реальном времени на ваших сайтах.

Синхронизация между вкладками

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

Безопасность

Сообщения WebSocket передаются по защищённым соединениям (WSS) и включают проверку арендатора, чтобы пользователи получали только те обновления, на просмотр которых они авторизованы. Сервер проверяет все операции перед их трансляцией, чтобы предотвратить несанкционированный доступ или манипуляции.

Справочник API Internal Link

Обзор API

Collab Chat предоставляет три REST API-эндпоинта для программного управления текстовыми беседами. Эти эндпоинты позволяют получать, создавать и удалять аннотации без использования браузерного виджета.

Это публичные эндпоинты, которые аутентифицируют пользователей через cookies браузера. Они не используют API-ключи. Пользователи должны быть авторизованы в FastComments в своём браузере для доступа к этим эндпоинтам.

Базовый URL

Все эндпоинты API Collab Chat находятся по адресу:

Базовый URL
Copy Copy
1
2https://fastcomments.com/comment-collab-chats
3

Аутентификация

Эти эндпоинты аутентифицируют пользователей через cookies браузера. Они не используют API-ключи. Пользователи должны быть авторизованы в FastComments в своём браузере для доступа к этим эндпоинтам.

Получение всех бесед

Получить все текстовые беседы для конкретной страницы.

Эндпоинт

GET Эндпоинт
Copy Copy
1
2GET /comment-collab-chats/:tenantId?urlId=<urlId>
3

Параметры

tenantId (параметр пути, обязательный) — это ваш FastComments Tenant ID.

urlId (параметр запроса, обязательный) — это идентификатор страницы, для которой вы хотите получить беседы.

Ответ

Ответ включает статус API, информацию о текущей сессии пользователя, если он аутентифицирован, массив бесед с их ID, URL и текстовыми диапазонами, очищенный идентификатор URL, флаг, указывающий, является ли текущий пользователь администратором сайта или модератором, а также детали WebSocket-соединения для синхронизации в реальном времени, включая tenantIdWS, urlIdWS и userIdWS.

Пример запроса

Пример GET-запроса
Copy Copy
1
2curl "https://fastcomments.com/comment-collab-chats/demo?urlId=my-article-page" \
3 --cookie "your-session-cookie"
4

Пример ответа

Пример GET-ответа
Copy Copy
1
2{
3 "status": "success",
4 "user": {
5 "id": "user123",
6 "username": "john_doe"
7 },
8 "conversations": [
9 {
10 "_id": "conv123",
11 "urlId": "my-article-page:p:0:15,0:45{abc123}",
12 "range": "0:15,0:45{abc123}"
13 },
14 {
15 "_id": "conv456",
16 "urlId": "my-article-page:h1:5:20,5:35{def456}",
17 "range": "5:20,5:35{def456}"
18 }
19 ],
20 "urlIdClean": "my-article-page",
21 "isSiteAdmin": false,
22 "tenantIdWS": "demo",
23 "urlIdWS": "my-article-page",
24 "userIdWS": "user123"
25}
26

Создание беседы

Создать новую текстовую беседу для конкретного выделенного текста.

Эндпоинт

POST Эндпоинт
Copy Copy
1
2POST /comment-collab-chats/:tenantId
3

Параметры

tenantId (параметр пути, обязательный) — это ваш FastComments Tenant ID.

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

urlId (строка, обязательный) — это базовый идентификатор страницы.

urlIdWithRange (строка, обязательный) — это URL, объединённый с текстовым диапазоном, например my-page:p:0:15,0:45{abc123}.

pageTitle (строка, обязательный) — это заголовок страницы.

selector (строка, обязательный) — это DOM-путь к элементу, содержащему выделенный текст.

range (строка, обязательный) — это сериализованный текстовый диапазон в формате startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (строка, обязательный) — это ID комментария, который инициировал эту беседу.

broadcastId (строка, обязательный) — это UUID для синхронизации в реальном времени, предотвращающий эффект эха.

Ответ

Ответ включает статус API и ID новой созданной беседы.

Пример запроса

Пример POST-запроса
Copy Copy
1
2curl -X POST "https://fastcomments.com/comment-collab-chats/demo" \
3 --cookie "your-session-cookie" \
4 -H "Content-Type: application/json" \
5 -d '{
6 "urlId": "my-article-page",
7 "urlIdWithRange": "my-article-page:p:0:15,0:45{abc123}",
8 "pageTitle": "My Article Title",
9 "selector": "div#article > p:nth-child(2)",
10 "range": "0:15,0:45{abc123}",
11 "createdFromCommentId": "comment789",
12 "broadcastId": "550e8400-e29b-41d4-a716-446655440000"
13 }'
14

Пример ответа

Пример POST-ответа
Copy Copy
1
2{
3 "status": "success",
4 "createdChatId": "conv789"
5}
6

Удаление беседы

Удалить существующую текстовую беседу. Этот эндпоинт требует прав администратора или модератора, либо беседа должна быть создана аутентифицированным пользователем.

Эндпоинт

DELETE Эндпоинт
Copy Copy
1
2DELETE /comment-collab-chats/:tenantId/:chatId
3

Параметры

tenantId (параметр пути, обязательный) — это ваш FastComments Tenant ID.

chatId (параметр пути, обязательный) — это ID беседы, которую нужно удалить.

broadcastId (тело запроса, обязательный) — это UUID для синхронизации в реальном времени.

Пример запроса

Пример DELETE-запроса
Copy Copy
1
2curl -X DELETE "https://fastcomments.com/comment-collab-chats/demo/conv789" \
3 --cookie "your-session-cookie" \
4 -H "Content-Type: application/json" \
5 -d '{
6 "broadcastId": "550e8400-e29b-41d4-a716-446655440001"
7 }'
8

Пример ответа

Пример DELETE-ответа
Copy Copy
1
2{
3 "status": "success"
4}
5

Ограничение частоты запросов

Эти эндпоинты подчиняются стандартным ограничениям частоты запросов FastComments API. Middleware ограничения частоты применяется для каждого тенанта, чтобы предотвратить злоупотребления, при этом допуская нормальные сценарии использования.

Ответы с ошибками

Все эндпоинты возвращают стандартные HTTP-коды состояния. Ответ 400 указывает на недопустимые параметры запроса. Ответ 401 означает, что аутентификация не пройдена. Ответ 403 указывает на недостаточные права. Ответ 404 означает, что беседа не найдена. Ответ 429 указывает на превышение лимита частоты запросов.

Ответы с ошибками включают JSON-тело с деталями:

Пример ответа с ошибкой
Copy Copy
1
2{
3 "status": "error",
4 "message": "Conversation not found"
5}
6

Учёт использования

Создание бесед увеличивает вашу метрику использования conversationCreateCount. Вся активность синхронизации через WebSocket увеличивает pubSubMessageCount и pubSubBandwidth. Вы можете отслеживать эти метрики в панели управления FastComments в разделе аналитики использования.

Есть вопросы?

На этом всё по FastComments Collab Chat! Если у вас есть вопросы, нужна помощь с реализацией или есть предложения по функционалу, пожалуйста, сообщите нам ниже или свяжитесь с нашей службой поддержки.

Для примеров вживую посмотрите Govscent.org, на котором используется Collab Chat в продакшене.

Внести вклад в это руководство