FastComments.com

Menu Icon

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

Първи стъпки

Първи стъпки
Примери
Добавяне на коментиране в реално време към онлайн книги

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

Опции за конфигурация
Поведение при избор на текст

Персонализиране

Персонализиране

Разширени

Синхронизация в реално време
Справочник на API

Съвместен чат

Добавяне на вградени живи коментари към документи, книги и др.

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

Тази функция е перфектна за редакторски обратни връзки, среди за съвместно четене, образователни платформи, преглед на документи и всякакъв сценарий, в който искате контекстуални дискусии, закрепени към конкретен текст.

Обърнете внимание, че тази документация е специфична за функционалността Collab Chat. Можете да добавите коментари за съдържание с много страници, като книги, с thread-per-page, without using collab chat. FastComments също не таксува на страница или на нишка. Collab Chat е специфично, когато искате да позволите на потребителите да селектират текст и да коментират маркираната част от текста.

Можете да видите an example here.

Първи стъпки Internal Link

Бърз старт

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

Инсталиране

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

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

Основна имплементация

Ето минимален пример:

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

Replace 'demo' with your actual FastComments Tenant ID if it's not already, which you can find in your FastComments dashboard.

Как работи

След като е инициализиран, потребителите могат да изберат произволен текст в целевия елемент. След кратко забавяне (3.5 секунди на десктоп), се появява подсказка, позволяваща им да започнат дискусия. Когато се създаде дискусия, върху текста се появява визуално открояване. Други потребители могат да задържат курсора върху или да кликнат върху открояването, за да видят и участват в дискусията. Всички дискусии се синхронизират в реално време за всички посетители.

Демо на живо

Можете да видите Collab Chat в действие на нашата страница с демо на живо.

Следващи стъпки

Сега когато основите работят, можете да персонализирате външния вид и поведението в ръководството за опции на конфигурацията. Вижте ръководството за поведението при избор на текст, за да разберете как работи селекцията на текст. Научете за стилизиране и поддръжка на тъмен режим в ръководството за персонализиране. За напреднали интеграции разгледайте API справката.

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

Всички фронтенд библиотеки на FastComments (react, vue, angular, etc) поддържат 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 използва адреса на страницата в комбинация с пътя до елемента и обхвата от текст, за да идентифицира разговорите. Можете да зададете персонализиран 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

Пример с callback за брой коментари

Можете да проследявате кога коментарите се добавят или актуализират, използвайки callback-а commentCountUpdated:

Collab Chat с callback за брой коментари
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 // Инициализиране на секцията за въведение
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 разширява стандартния widget за коментари FastComments, така че наследява всички опции за конфигурация от базовия widget, като добавя няколко специфични за текстови анотации.

Задължителна конфигурация

tenantId

Вашият FastComments Tenant ID е задължителен. Можете да го намерите в FastComments dashboard.

Пример за конфигурация
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 разширява стандартния widget за коментари, можете да използвате всяка опция за конфигурация от базовия FastComments widget. Ето някои често използвани опции:

locale

Задайте езика за UI на widget-а. FastComments поддържа десетки езици.

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

readonly

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

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

sso and simpleSSO

Интегрирайте със собствената си система за удостоверяване, използвайки Single Sign-On.

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

Вижте документацията за SSO за пълни детайли относно опциите за удостоверяване.

maxReplyDepth

Контролира колко нива дълбоко могат да бъдат отговорите. По подразбиране Collab Chat задава това на 0, което означава, че всички коментари са плоски (без вложени отговори). Можете да го промените, ако искате нишково водени разговори.

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

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

Тези опции се задават автоматично от Collab Chat и не би трябвало да бъдат презаписвани:

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

Как работи избора на текст

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

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

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

Ако потребителят има една и съща страница отворена в няколко раздела на браузъра, актуализациите в един раздел се появяват незабавно в останалите раздели. Това работи чрез същия механизъм за синхронизация с WebSocket и не изисква допълнителна конфигурация.

Сигурност

WebSocket съобщенията се предават по защитени връзки (WSS) и включват проверка на наемателя, за да се гарантира, че потребителите получават само актуализации за разговори, които имат право да виждат. Сървърът валидира всички операции преди да ги излъчи, с цел предотвратяване на неоторизиран достъп или манипулация.

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

Преглед на API

Collab Chat предоставя три REST API крайни точки за програмиране управлението на текстови разговори. Тези крайни точки ви позволяват да извличате, създавате и изтривате анотации без използване на браузърния widget.

Това са публични крайни точки, които удостоверяват потребителите чрез браузърни бисквитки. Те не използват API ключове. Потребителите трябва да са влезли в FastComments в своя браузър, за да имат достъп до тези крайни точки.

Базов URL

Всички крайни точки на API за Collab Chat са на:

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

Удостоверяване

Тези крайни точки удостоверяват потребителите чрез браузърни бисквитки. Те не използват API ключове. Потребителите трябва да са влезли в FastComments в своя браузър, за да имат достъп до тези крайни точки.

Получаване на всички разговори

Вземете всички текстови разговори за конкретна страница.

Крайна точка

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

Параметри

tenantId (параметър в пътя, задължителен) е вашият FastComments Tenant ID.

urlId (параметър на заявката, задължителен) е идентификаторът на страницата, за която искате да получите разговорите.

Отговор

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

Примерна заявка

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

Примерен отговор

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

Създаване на разговор

Създайте нов текстов разговор за конкретен избран текст.

Крайна точка

POST Крайна точка
Copy Copy
1
2POST /comment-collab-chats/:tenantId
3

Параметри

tenantId (параметър в пътя, задължителен) е вашият FastComments Tenant ID.

Тялото на заявката трябва да е JSON и да включва следните задължителни полета.

urlId (string, задължително) е базовият идентификатор на страницата.

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

pageTitle (string, задължително) е заглавието на страницата.

selector (string, задължително) е DOM пътят към елемента, съдържащ избрания текст.

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

createdFromCommentId (string, задължително) е ID-то на коментара, който е инициирал този чат.

broadcastId (string, задължително) е UUID за синхронизация в реално време с цел предотвратяване на ехо ефекти.

Отговор

Отговорът включва статуса на API и ID-то на новосъздадения разговор.

Примерна заявка

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

Примерен отговор

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

Изтриване на разговор

Изтрийте съществуващ текстов разговор. Тази крайна точка изисква права на администратор или модератор на сайта, или разговорът трябва да е бил създаден от удостоверения потребител.

Крайна точка

DELETE Крайна точка
Copy Copy
1
2DELETE /comment-collab-chats/:tenantId/:chatId
3

Параметри

tenantId (параметър в пътя, задължителен) е вашият FastComments Tenant ID.

chatId (параметър в пътя, задължителен) е ID-то на разговора, който ще бъде изтрит.

broadcastId (тяло на заявката, задължително) е UUID за синхронизация в реално време.

Примерна заявка

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

Примерен отговор

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

Ограничения за честота на заявки

Тези крайни точки подлежат на стандартните ограничения за честота на 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 в продукция.

Допринеси към това ръководство