FastComments.com

Menu Icon

Язык 🇷🇺 Русский
🇺🇸 English 🇧🇬 Български 🇨🇳 简体中文 🇹🇼 繁體中文 🇭🇷 Hrvatski 🇩🇰 Dansk 🇳🇱 Nederlands 🇺🇸 English (US) 🇨🇦 Français (Canada) 🇫🇷 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 <!-- Load the Collab Chat script -->
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

Replace 'demo' with your actual FastComments Tenant ID if it's not already, which you can find in your панель управления FastComments.

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

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

Живая демонстрация

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

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

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

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

Все фронтенд-библиотеки 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

Требуется ваш FastComments Tenant ID. Вы можете найти его в вашей панели управления 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' // Испанский
5});
6

readonly

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

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

sso and simpleSSO

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

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

Смотрите документацию по SSO для полного описания параметров аутентификации.

maxReplyDepth

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

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Разрешить 3 уровня вложенности
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 // Ваша конфигурация SSO
13 },
14 maxReplyDepth: 1
15});
16

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

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

How Text Selection Works

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

Selection Delay

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

Unique Conversation IDs

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

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

Visual Highlights

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

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

Chat Window Positioning

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

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

Chat Window Dimensions

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

Cross-Element Selections

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

Browser Compatibility

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

Selection Persistence

После создания разговора для выделенного текста эта аннотация сохраняется даже после перезагрузки страницы. Сериализованный диапазон и путь 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 конечные точки для управления текстовыми разговорами программно. Эти конечные точки позволяют получать, создавать и удалять аннотации без использования виджета в браузере.

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

Base URL

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

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

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

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

Получить все разговоры

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

Endpoint

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

Создать разговор

Создайте новый текстовый разговор для выбранного фрагмента текста.

Endpoint

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

Параметры

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

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

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

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

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

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

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

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

broadcastId (string, обязательный) — 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

Удалить разговор

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

Endpoint

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

Ограничение скорости (Rate Limiting)

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

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

Все конечные точки возвращают стандартные коды состояния 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 в продакшене.

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