Collab Chat | FastComments Docs

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

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

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

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

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

Първи стъпки

Бърз старт

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

Инсталиране

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

Зареждане на скрипта Collab Chat

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>

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

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

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

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat</title>
</head>
<body>
    <!-- Контейнер за вашето съдържание -->
    <div id="article-content" style="min-height: 500px;">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <!-- Заредете скрипта Collab Chat -->
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <!-- Инициализирайте Collab Chat -->
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

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.

Примери

Основен пример

Най-простият начин да използвате Collab Chat е да насочите към един контейнер със съдържание. Този пример показва как да активирате текстови анотации в статия:

Основен пример за Collab Chat

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat</title>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

Пример с персонализирано URL ID (за страница от книга, статия и т.н.)

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

Collab Chat с персонализирано URL ID

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    FastCommentsCollabChat(document.getElementById('article-content'), {
        tenantId: 'demo',
        urlId: 'book-one-page-2'
    });
</script>

Това е полезно, ако структурата на вашите URL адреси се промени, но искате да запазите същите разговори, или ако искате да споделяте едни и същи анотации на разговорите в няколко страници.

Пример с тъмен режим

Ако вашият сайт има тъмен фон, активирайте поддръжка за тъмен режим, за да гарантирате, че чат интерфейсът изглежда правилно:

Collab Chat с тъмен режим

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat - Dark Mode</title>
    <style>
        body {
            background-color: #1a1a1a !important;
            color: #e0e0e0 !important;
            font-family: system-ui, -apple-system, sans-serif;
            padding: 20px;
            margin: 0;
        }
        #article-content {
            max-width: 800px;
            margin: 0 auto;
            background-color: #2d2d2d;
            padding: 20px;
            border-radius: 8px;
        }
        h1 {
            color: #ffffff !important;
        }
        p {
            color: #e0e0e0 !important;
            line-height: 1.6;
        }
        .fastcomments-collab-chat-top-bar {
            background-color: #2d2d2d !important;
            color: #e0e0e0 !important;
            border-bottom: 1px solid #444 !important;
        }
    </style>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo',
            hasDarkBackground: true
        });
    </script>
</body>
</html>

Пример с деактивиран горен бар

По подразбиране Collab Chat показва горен бар с брой потребители и брой дискусии. Можете да го деактивирате:

Collab Chat с деактивиран горен бар

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat - No Top Bar</title>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo',
            topBarTarget: null
        });
    </script>
</body>
</html>

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

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

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

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    FastCommentsCollabChat(document.getElementById('article-content'), {
        tenantId: 'demo',
        commentCountUpdated: function(count) {
            console.log('Total comments:', count);
            document.getElementById('comment-badge').textContent = count;
        }
    });
</script>

Пример с няколко секции

Можете да инициализирате Collab Chat в няколко отделни секции на вашата страница. Всяка секция ще има свои собствени независими анотации:

Collab Chat в няколко секции

Copy

<div id="intro-section">
    <h2>Introduction</h2>
    <p>Content for the introduction...</p>
</div>
<div id="main-section">
    <h2>Main Content</h2>
    <p>Content for the main article...</p>
</div>
<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    // Инициализиране на секцията за въведение
    FastCommentsCollabChat(document.getElementById('intro-section'), {
        tenantId: 'demo',
        urlId: 'my-article-intro'
    });
    // Инициализиране на основната секция
    FastCommentsCollabChat(document.getElementById('main-section'), {
        tenantId: 'demo',
        urlId: 'my-article-main'
    });
</script>

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

Можете да инициализирате Collab Chat за всяка страница, ако желаете, и да имате отделни нишки за всяка страница, просто подайте на параметъра urlId стойност като book-one-page1. Тази конфигурация работи и за нормалния коментарен уиджет.

Опции за конфигурация

Преглед

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

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

tenantId

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

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo'
});

Опции, специфични за Collab Chat

urlId

По подразбиране Collab Chat генерира уникален идентификатор за всеки разговор въз основа на URL на страницата, DOM пътя до елемента и селектирания текстов диапазон. Можете да го презапишете с персонализиран urlId.

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    urlId: 'my-custom-page-id'
});

Това е полезно, когато структурата на вашите URL може да се промени, но искате да запазите същите разговори, или когато искате да споделяте анотации между множество страници.

topBarTarget

Контролира показването на горната лента, която показва брой потребители и брой дискусии. Задайте на null, за да деактивирате горната лента напълно, или подайте DOM елемент, в който да се рендира тя на конкретно място.

Пример за конфигурация

Copy

// Изключване на горната лента
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});
// Показване на горната лента в персонализирано място
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('custom-header')
});

hasDarkBackground

Активира стилизиране за тъмен режим, когато вашата страница има тъмен фон. Това откриване е автоматично, но може да искате да го презапишете.

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    hasDarkBackground: true
});

commentCountUpdated

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

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    commentCountUpdated: function(count) {
        console.log('Total comments:', count);
        document.getElementById('badge').textContent = count;
    }
});

Наследени опции за конфигурация

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

locale

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

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // Испански
});

readonly

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

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    readonly: true
});

sso and simpleSSO

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

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    sso: {
        // Конфигурация на SSO
    }
});

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

maxReplyDepth

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

Пример за конфигурация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    maxReplyDepth: 3  // Позволява 3 нива на вложеност
});

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

Тези опции се задават автоматично от 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

FastCommentsCollabChat(document.getElementById('article'), {
    tenantId: 'demo',
    urlId: 'my-article-v2',
    hasDarkBackground: false,
    locale: 'en',
    topBarTarget: document.getElementById('custom-header'),
    commentCountUpdated: function(count) {
        document.title = count > 0 ? `(${count}) My Article` : 'My Article';
    },
    sso: {
        // Вашата SSO конфигурация
    },
    maxReplyDepth: 1
});

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

Поведение при избор на текст

How Text Selection Works

When users select text within the Collab Chat container, the widget captures that selection and allows them to start a discussion. The selection can be as small as a single word or as large as multiple paragraphs spanning different elements.

Selection Delay

On desktop devices, there's a 3.5 second delay between when a user selects text and when the discussion prompt appears. This prevents the UI from flickering when users are simply highlighting text to copy or read. On mobile devices, the prompt appears immediately since text selection is more deliberate on touch screens.

Unique Conversation IDs

Each conversation gets a unique urlId that combines the page URL, the DOM element path, and the serialized text range. This ensures that each text selection creates a distinct conversation that can be found again later.

If you provide a custom urlId in your configuration, it will be combined with the element path and text range to create the final identifier.

Visual Highlights

When a discussion exists for a particular text selection, that text receives a visual highlight. The highlight is implemented using background colors and appears on hover or when the associated chat window is open.

The highlighting system works by wrapping the selected text in a special element that can be styled. This approach ensures that highlights remain accurate even when the underlying HTML structure is complex.

Chat Window Positioning

When a user clicks on a highlight or creates a new annotation, a chat window appears near the selected text. The widget automatically calculates the best position for this window based on available viewport space.

The positioning system uses CSS classes like to-right, to-left, to-top, and to-bottom to indicate which direction the chat window should extend from the highlight. On mobile devices (screens under 768px wide), the chat window always appears fullscreen for better usability.

Chat Window Dimensions

Chat windows are 410px wide on desktop with 20px spacing and a 16px visual arrow pointing to the highlighted text. These dimensions are fixed to ensure consistent behavior, but you can customize the appearance with CSS.

Cross-Element Selections

Users can select text that spans multiple HTML elements, such as highlighting from the middle of one paragraph through the start of another. The range serialization system handles this correctly and will highlight all the selected text even across element boundaries.

Browser Compatibility

The text selection system uses the standard window.getSelection() API which is supported in all modern browsers. For older versions of Internet Explorer, it falls back to document.selection for compatibility.

Selection Persistence

Once a conversation is created for a text selection, that annotation persists even if the page is reloaded. The serialized range and DOM path allow the widget to restore highlights in the exact same location when users return to the page.

This works reliably as long as your page content remains stable. If you change the text content or restructure your HTML, existing annotations may no longer align correctly with the text. For this reason, it's best to avoid major content changes on pages with active annotations, or consider migrating annotations when content changes are necessary.

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

Поддръжка на тъмен режим

Динамичен тъмен режим

Ако тъмният режим на вашия сайт се контролира чрез добавяне на .dark клас към елемента body, потребителският интерфейс на Collab Chat ще го уважава автоматично, без да е необходима повторна инициализация. Стиловете на джаджата са проектирани да реагират на наличието на този клас.

Пример за CSS за тъмен режим

Copy

/* Вашият CSS за тъмен режим */
body.dark {
    background: #1a1a1a;
    color: #ffffff;
}

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

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

Маркировките на текста използват системата за стилове на балончетата за коментари на FastComments, така че всякакви персонализации, които сте приложили към стандартната джаджа за коментари, ще повлияят и на Collab Chat.

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

Горната лента показва броя на потребителите онлайн и броя на дискусиите. Можете да персонализирате нейното положение, като предоставите персонализиран елемент като topBarTarget:

Персонализирано местоположение на горната лента

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('my-custom-header')
});

Или я деактивирайте напълно като я зададете на null:

Деактивиране на горната лента

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});

Поведение на мобилни устройства

На екрани по-малки от 768px Collab Chat автоматично преминава към оформление, оптимизирано за мобилни устройства. Прозорците за чат се показват на цял екран вместо да плават до текста, а забавянето при селекция е премахнато за по-непосредствено взаимодействие.

Това поведение е вградено и не изисква конфигуриране. Джаджата автоматично открива размера на екрана и се настройва съответно.

Външен вид на прозореца за чат

Прозорците за чат са широки 410px на настолни устройства с 16px стрелка, насочваща към маркирания текст. Прозорците се позиционират автоматично въз основа на наличното пространство в изгледа, използвайки класове за позициониране като to-right, to-left, to-top и to-bottom.

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

Локализация

Collab Chat поддържа всички същите опции за локализация като стандартната джаджа на FastComments. Задайте опцията locale, за да показвате текстовете на потребителския интерфейс на различни езици:

Задаване на локализация

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // испански
});

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

Наследени опции за персонализиране

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

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

Работа с персонализирани шрифтове

Ако вашият сайт използва персонализирани шрифтове, потребителският интерфейс на Collab Chat ще наследи тези шрифтове от CSS-а на вашата страница. Може да се наложи да създадете правило за персонализиране на джаджата и да @import-нете всички шрифтове в персонализирания CSS в това правило, ако искате плаващият прозорец за чат да използва същите шрифтове.

Синхронизация в реално време

Актуализации в реално време

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

Преглед на API

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

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

Базов URL

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

Базов URL

Copy

https://fastcomments.com/comment-collab-chats

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

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

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

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

Крайна точка

GET Крайна точка

Copy

GET /comment-collab-chats/:tenantId?urlId=<urlId>

Параметри

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

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

Отговор

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

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

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

Copy

curl "https://fastcomments.com/comment-collab-chats/demo?urlId=my-article-page" \
  --cookie "your-session-cookie"

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

Пример за GET отговор

Copy

{
  "status": "success",
  "user": {
    "id": "user123",
    "username": "john_doe"
  },
  "conversations": [
    {
      "_id": "conv123",
      "urlId": "my-article-page:p:0:15,0:45{abc123}",
      "range": "0:15,0:45{abc123}"
    },
    {
      "_id": "conv456",
      "urlId": "my-article-page:h1:5:20,5:35{def456}",
      "range": "5:20,5:35{def456}"
    }
  ],
  "urlIdClean": "my-article-page",
  "isSiteAdmin": false,
  "tenantIdWS": "demo",
  "urlIdWS": "my-article-page",
  "userIdWS": "user123"
}

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

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

Крайна точка

POST Крайна точка

Copy

POST /comment-collab-chats/:tenantId

Параметри

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

curl -X POST "https://fastcomments.com/comment-collab-chats/demo" \
  --cookie "your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "urlId": "my-article-page",
    "urlIdWithRange": "my-article-page:p:0:15,0:45{abc123}",
    "pageTitle": "My Article Title",
    "selector": "div#article > p:nth-child(2)",
    "range": "0:15,0:45{abc123}",
    "createdFromCommentId": "comment789",
    "broadcastId": "550e8400-e29b-41d4-a716-446655440000"
  }'

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

Пример за POST отговор

Copy

{
  "status": "success",
  "createdChatId": "conv789"
}

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

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

Крайна точка

DELETE Крайна точка

Copy

DELETE /comment-collab-chats/:tenantId/:chatId

Параметри

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

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

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

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

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

Copy

curl -X DELETE "https://fastcomments.com/comment-collab-chats/demo/conv789" \
  --cookie "your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcastId": "550e8400-e29b-41d4-a716-446655440001"
  }'

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

Пример за DELETE отговор

Copy

{
  "status": "success"
}

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

Тези крайни точки подлежат на стандартните ограничения за честота на API на FastComments. Middleware за ограничение на честотата се прилага на ниво наемател (tenant) за предотвратяване на злоупотреби, като същевременно позволява нормални модели на използване.

Отговори при грешка

Всички крайни точки връщат стандартни HTTP статус кодове. Отговор 400 означава невалидни параметри на заявката. Отговор 401 означава неуспешно удостоверяване. Отговор 403 указва недостатъчни права. Отговор 404 означава, че разговорът не е намерен. Отговор 429 показва превишен лимит на заявките.

Отговорите при грешка включват JSON тяло с подробности:

Пример за отговор при грешка

Copy

{
  "status": "error",
  "message": "Conversation not found"
}

Проследяване на използването

Създаването на разговори увеличава вашата метрика за използване conversationCreateCount. Цялата WebSocket синхронизационна активност увеличава pubSubMessageCount и pubSubBandwidth. Можете да следите тези метрики в таблото за управление на FastComments под анализа на използването.

Имате въпроси?

Това е всичко за FastComments Collab Chat! Ако имате въпроси, нужда от помощ с имплементацията или предложения за функции, моля уведомете ни по-долу или се свържете с нашия екип за поддръжка.

За реални примери вижте Govscent.org, който използва Collab Chat в продукция.

Език 🇧🇬 Български

Първи стъпки

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

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

Разширени

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

Първи стъпки

Бърз старт

Инсталиране

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

Как работи

Демо на живо

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

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

Примери

Основен пример

Пример с персонализирано URL ID (за страница от книга, статия и т.н.)

Пример с тъмен режим

Пример с деактивиран горен бар

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

Пример с няколко секции

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

Опции за конфигурация

Преглед

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

tenantId

Опции, специфични за Collab Chat

urlId

topBarTarget

hasDarkBackground

commentCountUpdated

Наследени опции за конфигурация

locale

readonly

sso and simpleSSO

maxReplyDepth

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

Пълен пример

Поведение при избор на текст

How Text Selection Works

Selection Delay

Unique Conversation IDs

Visual Highlights

Chat Window Positioning

Chat Window Dimensions

Cross-Element Selections

Browser Compatibility

Selection Persistence

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

Поддръжка на тъмен режим

Динамичен тъмен режим

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

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

Поведение на мобилни устройства

Външен вид на прозореца за чат

Локализация

Наследени опции за персонализиране

Работа с персонализирани шрифтове

Синхронизация в реално време

Актуализации в реално време

Как работи синхронизацията чрез WebSocket

Система за Broadcast ID

Брой активни потребители

Устойчивост на връзката

Съображения относно пропускателната способност

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

Сигурност

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

Преглед на API

Базов URL

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

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

Крайна точка

Параметри

Отговор

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

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

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

Крайна точка

Параметри