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 дозволяє користувачам виділяти та додавати анотації до будь-якого текстового вмісту на вашому вебсайті, створюючи ниткові обговорення, прив'язані до конкретних виділень тексту. Користувачі можуть виділяти слова, речення або цілі абзаци, щоб розпочати спільні розмови безпосередньо в контенті.

Ця функція ідеально підходить для редакційного зворотного зв'язку, середовищ спільного читання, освітніх платформ, перегляду документів та будь-якого сценарію, де потрібні контекстні обговорення, прив'язані до конкретного тексту.

Note that these docs are specific to the Collab Chat functionality. Ви можете додати можливість коментування для контенту з великою кількістю сторінок, наприклад книг, з thread-per-page, without using 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 <!-- Your content container -->
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 <!-- Initialize Collab Chat -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

Замініть 'demo' на ваш фактичний Tenant ID FastComments, якщо ви ще цього не зробили. Його можна знайти у вашій панелі керування 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 with Custom 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// Disable top bar
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Render top bar in custom location
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 кінцеві точки для програмного керування текстовими розмовами. Ці кінцеві точки дозволяють отримувати, створювати та видаляти анотації без використання віджета в браузері.

Це публічні кінцеві точки, які автентифікують користувачів через 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 (path parameter, required) — це ваш FastComments Tenant ID.

urlId (query parameter, required) — це ідентифікатор сторінки, для якої потрібно отримати розмови.

Відповідь

У відповіді міститься статус API, інформація про поточну сесію користувача, якщо автентифіковано, масив розмов з їх ідентифікаторами, 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 (path parameter, required) — це ваш FastComments Tenant ID.

Тіло запиту має бути в 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) — це ідентифікатор коментаря, який ініціював цю розмову.

broadcastId (string, required) — це UUID для синхронізації в реальному часі, щоб запобігти ефектам ехо.

Відповідь

У відповіді міститься статус API та ідентифікатор щойно створеної розмови.

Приклад запиту

Приклад 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 (path parameter, required) — це ваш FastComments Tenant ID.

chatId (path parameter, required) — це ідентифікатор розмови, яку потрібно видалити.

broadcastId (request body, required) — це 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

Обмеження швидкості

Ці кінцеві точки підпадають під стандартне обмеження швидкості API FastComments. 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 у виробничому середовищі.

Зробити внесок у цей посібник