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 <!-- 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' с вашия действителен FastComments Tenant ID, ако вече не сте го направили. Можете да го намерите в FastComments таблото за управление.

Как работи

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

Демонстрация на живо

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

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

Сега, когато основите работят, можете да персонализирате външния вид и поведението в ръководството Configuration Options. Прегледайте ръководството Text Selection Behavior, за да разберете как работи избирането на текст. Научете повече за стилизирането и поддръжката на тъмен режим в ръководството Customization. За разширени интеграции разгледайте API Reference.

Frontend библиотеки

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

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

Пример за конфигурация
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 поддържа десетки езици. Настройката на 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 в продукция.

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