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

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

Note that these docs are specific to the Collab Chat functionality. Ви можете додати можливість коментування для контенту з великою кількістю сторінок, наприклад книг, з thread-per-page, without using collab chat. FastComments також не стягує плату за сторінку або за тред. Collab Chat призначений саме для випадків, коли ви хочете дозволити користувачам виділяти текст і коментувати підсвічений фрагмент тексту.

Ви можете побачити приклад тут.

Початок роботи Internal Link

Quick Start

Почати роботу з Collab Chat просто. Вам потрібен скрипт FastComments Collab Chat, HTML-елемент, який містить текст, що його потрібно анотувати, та об'єкт конфігурації з вашим Tenant ID.

Installation

Додайте скрипт Collab Chat на вашу сторінку:

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

Basic Implementation

Ось мінімальний приклад:

Базова реалізація 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 <!-- Initialize 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

Після ініціалізації користувачі можуть виділити будь-який текст у цільовому елементі. Після короткої затримки (3.5 секунди на десктопі) з'являється підказка, яка дозволяє почати обговорення. Коли створюється обговорення, на тексті з'являється візуальне підсвічування. Інші користувачі можуть навести курсор або натиснути на підсвічування, щоб переглянути та взяти участь в обговоренні. Усі обговорення синхронізуються в режимі реального часу між усіма відвідувачами.

Live Demo

Ви можете побачити Collab Chat в дії на нашій сторінці демонстрації.

Next Steps

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

Frontend Libraries

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

Overview

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

Required Configuration

tenantId

Ваш FastComments Tenant ID є обов'язковим. Ви можете знайти його у вашій панелі керування FastComments.

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

Collab Chat Specific Options

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

Inherited Configuration Options

Оскільки 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

Internal Configuration

Ці опції автоматично встановлюються 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.

Complete Example

Here's an example showing multiple configuration options together:

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

Успадковані параметри налаштування

Оскільки 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 у виробничому середовищі.

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