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 также не взимает плату за per-page или per-thread. 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 dashboard.

How It Works

Once initialized, users can select any text within the target element. After a brief delay (3.5 seconds on desktop), a prompt appears allowing them to start a discussion. When a discussion is created, a visual highlight appears on the text. Other users can hover over or click the highlight to view and participate in the discussion. All discussions sync in real-time across all visitors.

Live Demo

You can see Collab Chat in action on our live demo page.

Next Steps

Now that you have the basics working, you can customize the appearance and behavior in the Configuration Options guide. Check out the Text Selection Behavior guide to understand how text selection works. Learn about styling and dark mode support in the Customization guide. For advanced integrations, explore the API Reference.

Frontend Libraries

All FastComments frontend libraries (react, vue, angular, etc) have 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 // Инициализация на основной секции
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' // Испанский
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, что означает плоскую структуру комментариев (без вложенных ответов). Вы можете изменить это, если хотите потоковые (threaded) обсуждения.

Пример конфигурации
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Разрешить 3 уровня вложенности
5});
6

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

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

The productId is automatically set to 3 for Collab Chat. The floating-chat extension is automatically loaded to provide the chat window functionality. The widget automatically detects mobile devices (screens under 768px wide) and adjusts the UI accordingly.

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

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

Пример конфигурации
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

For a complete list of all available configuration options inherited from the base widget, see the main FastComments configuration documentation.

Поведение при выделении текста 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 поддерживает десятки языков. Параметр locale влияет на весь текст интерфейса, включая подсказки, кнопки и текст-заполнитель.

Наследуемые параметры настройки

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

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

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

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

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

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

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

Обзор API

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

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

Базовый URL

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

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

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

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

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

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

Конечная точка

GET конечная точка
Copy Copy
1
2GET /comment-collab-chats/:tenantId?urlId=<urlId>
3

Параметры

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

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

Ответ

Ответ включает статус API, информацию о текущей сессии пользователя, если он аутентифицирован, массив разговоров с их ID, URL и текстовыми диапазонами, очищенный идентификатор URL, urlIdClean, флаг, указывающий, является ли текущий пользователь администратором сайта или модератором, и данные подключения 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 (параметр пути, обязательный) — это ваш Tenant ID FastComments.

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

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

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

pageTitle (string, required) — заголовок страницы.

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

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

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

broadcastId (string, required) — 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 (параметр пути, обязательный) — это ваш Tenant ID FastComments.

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. Мидлвар ограничения применяется на уровне арендатора, чтобы предотвратить злоупотребления при сохранении нормальных сценариев использования.

Ответы об ошибках

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

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