FastComments.com

Menu Icon

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

Rozpoczęcie pracy

Rozpoczęcie pracy
Przykłady
Dodawanie komentowania w czasie rzeczywistym do książek online

Konfiguracja

Opcje konfiguracji
Zachowanie zaznaczania tekstu

Dostosowywanie

Dostosowywanie

Zaawansowane

Synchronizacja w czasie rzeczywistym
Dokumentacja API

Dodaj wbudowane komentarze na żywo do dokumentów, książek itp.

FastComments Collab Chat umożliwia użytkownikom wyróżnianie i dodawanie adnotacji do dowolnej treści tekstowej na Twojej stronie, tworząc dyskusje w wątkach powiązane z konkretnymi fragmentami tekstu. Użytkownicy mogą zaznaczać pojedyncze słowa, zdania lub całe akapity, aby rozpocząć wspólne rozmowy bezpośrednio w treści.

Ta funkcja doskonale sprawdza się przy redakcyjnych uwagach, środowiskach do wspólnego czytania, platformach edukacyjnych, przeglądzie dokumentów oraz w każdej sytuacji, gdy chcesz mieć kontekstowe dyskusje osadzone przy konkretnym fragmencie tekstu.

Należy pamiętać, że ta dokumentacja dotyczy funkcjonalności Collab Chat. Możesz dodać komentowanie dla treści zawierających wiele stron, takich jak Books, z thread-per-page, bez używania collab chat. FastComments nie pobiera też opłat za stronę ani za wątek. Collab Chat dotyczy konkretnie sytuacji, gdy chcesz pozwolić użytkownikom zaznaczać tekst i komentować wyróżniony fragment tekstu.

Zobacz przykład tutaj.

Rozpoczęcie pracy Internal Link

Szybki start

Rozpoczęcie pracy z Collab Chat jest proste. Potrzebujesz skryptu FastComments Collab Chat, elementu HTML zawierającego tekst, który chcesz komentować, oraz obiektu konfiguracyjnego z Twoim Tenant ID.

Instalacja

Dodaj skrypt Collab Chat do swojej strony:

Ładowanie skryptu Collab Chat
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
3

Podstawowa implementacja

Oto minimalny przykład:

Podstawowa implementacja 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 <!-- Kontener zawartości -->
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 <!-- Załaduj skrypt Collab Chat -->
16 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
17
18 <!-- Zainicjalizuj Collab Chat -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

Zastąp 'demo' swoim rzeczywistym FastComments Tenant ID, jeśli jeszcze tego nie zrobiłeś — znajdziesz go w swoim panelu FastComments.

Jak to działa

Po zainicjowaniu użytkownicy mogą zaznaczać dowolny tekst wewnątrz docelowego elementu. Po krótkim opóźnieniu (3,5 sekundy na komputerach) pojawia się podpowiedź umożliwiająca rozpoczęcie dyskusji. Gdy dyskusja zostanie utworzona, na tekście pojawia się wizualne podświetlenie. Inni użytkownicy mogą najedzieć kursorem lub kliknąć podświetlenie, aby wyświetlić i uczestniczyć w dyskusji. Wszystkie dyskusje synchronizują się w czasie rzeczywistym między wszystkimi odwiedzającymi.

Demonstacja na żywo

Możesz zobaczyć Collab Chat w akcji na naszej stronie demonstracyjnej na żywo.

Kolejne kroki

Skoro masz już podstawy działające, możesz dostosować wygląd i zachowanie w przewodniku Opcje konfiguracji. Zapoznaj się z przewodnikiem Zachowanie zaznaczania tekstu, aby zrozumieć, jak działa zaznaczanie tekstu. Dowiedz się o stylowaniu i wsparciu trybu ciemnego w przewodniku Personalizacja. Dla zaawansowanych integracji zapoznaj się z Dokumentacją API.

Biblioteki frontendowe

Wszystkie biblioteki frontendowe FastComments (react, vue, angular, itp.) zawierają Collab Chat.

Przykłady Internal Link

Podstawowy przykład

Najprostszy sposób użycia Collab Chat to wskazanie jednego kontenera z treścią. Ten przykład pokazuje, jak włączyć adnotacje tekstu w artykule:

Podstawowy przykład 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

Przykład z niestandardowym identyfikatorem URL (na stronę książki, artykuł itp.)

Domyślnie Collab Chat używa adresu URL strony w połączeniu ze ścieżką elementu i zakresem tekstu do identyfikacji rozmów. Możesz podać niestandardowy urlId, aby mieć większą kontrolę nad tym, jak rozmowy są grupowane:

Collab Chat z niestandardowym identyfikatorem URL
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

Jest to przydatne, jeśli struktura Twoich adresów URL się zmienia, ale chcesz zachować te same rozmowy, lub jeśli chcesz udostępniać te same adnotacje konwersacji na wielu stronach.

Przykład z trybem ciemnym

Jeśli Twoja strona ma ciemne tło, włącz obsługę trybu ciemnego, aby interfejs czatu wyglądał poprawnie:

Collab Chat z trybem ciemnym
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

Przykład z wyłączonym paskiem górnym

Domyślnie Collab Chat pokazuje pasek górny z liczbą użytkowników i liczbą dyskusji. Możesz go wyłączyć:

Collab Chat z wyłączonym paskiem górnym
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

Przykład z callbackiem aktualizacji liczby komentarzy

Możesz śledzić dodawanie lub aktualizację komentarzy, używając callbacku commentCountUpdated:

Collab Chat z callbackiem aktualizacji liczby komentarzy
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

Przykład z wieloma sekcjami

Możesz zainicjalizować Collab Chat w wielu oddzielnych sekcjach swojej strony. Każda sekcja będzie miała własne niezależne adnotacje:

Collab Chat na wielu sekcjach
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 // Zainicjalizuj sekcję wstępu
15 FastCommentsCollabChat(document.getElementById('intro-section'), {
16 tenantId: 'demo',
17 urlId: 'my-article-intro'
18 });
19
20 // Zainicjalizuj sekcję główną
21 FastCommentsCollabChat(document.getElementById('main-section'), {
22 tenantId: 'demo',
23 urlId: 'my-article-main'
24 });
25</script>
26

Dodawanie komentowania w czasie rzeczywistym do książek online Internal Link

Możesz zainicjalizować Collab Chat dla każdej strony, jeśli chcesz, i mieć osobne wątki dla każdej strony — wystarczy przekazać parametr urlId wartość taką jak book-one-page1. Ta konfiguracja działa również dla standardowego widżetu komentarzy.

Opcje konfiguracji Internal Link

Przegląd

FastComments Collab Chat rozszerza standardowy widżet komentarzy FastComments, dzięki czemu dziedziczy wszystkie opcje konfiguracyjne z podstawowego widżetu, jednocześnie dodając kilka specyficznych dla adnotacji tekstowych.

Wymagana konfiguracja

tenantId

Wymagane jest Twoje Tenant ID FastComments. Możesz je znaleźć w swoim panelu FastComments.

Przykład konfiguracji
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo'
4});
5

Opcje specyficzne dla Collab Chat

urlId

Domyślnie Collab Chat generuje unikalny identyfikator dla każdej konwersacji na podstawie URL strony, ścieżki DOM do elementu i wybranego zakresu tekstu. Możesz to nadpisać własnym urlId.

Przykład konfiguracji
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 urlId: 'my-custom-page-id'
5});
6

Jest to przydatne, gdy struktura URL może się zmieniać, ale chcesz zachować te same rozmowy, lub gdy chcesz udostępniać adnotacje na wielu stronach.

topBarTarget

Kontroluje wyświetlanie paska górnego, który pokazuje liczbę użytkowników i liczbę dyskusji. Ustaw na null, aby całkowicie wyłączyć pasek górny, lub podaj element DOM, aby renderować go w określonym miejscu.

Przykład konfiguracji
Copy Copy
1
2// Wyłącz pasek górny
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Renderuj pasek górny w niestandardowej lokalizacji
9FastCommentsCollabChat(element, {
10 tenantId: 'demo',
11 topBarTarget: document.getElementById('custom-header')
12});
13

hasDarkBackground

Włącz stylizację trybu ciemnego, gdy Twoja strona ma ciemne tło. To wykrywanie jest automatyczne, ale możesz chcieć je nadpisać.

Przykład konfiguracji
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 hasDarkBackground: true
5});
6

commentCountUpdated

Funkcja zwrotna (callback), która jest wywoływana zawsze, gdy zmienia się liczba komentarzy. Przydatne do aktualizowania elementów UI, takich jak odznaki lub tytuły stron.

Przykład konfiguracji
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

Dziedziczone opcje konfiguracji

Ponieważ Collab Chat rozszerza standardowy widżet komentarzy, możesz użyć dowolnej opcji konfiguracyjnej z podstawowego widżetu FastComments. Oto kilka często używanych opcji:

locale

Ustaw język interfejsu widżetu. FastComments obsługuje dziesiątki języków.

Przykład konfiguracji
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // hiszpański
5});
6

readonly

Ustaw wszystkie konwersacje jako tylko do odczytu. Użytkownicy mogą przeglądać istniejące adnotacje, ale nie mogą tworzyć nowych ani odpowiadać.

Przykład konfiguracji
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 readonly: true
5});
6

sso and simpleSSO

Zintegruj z systemem uwierzytelniania za pomocą Single Sign-On.

Przykład konfiguracji
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 sso: {
5 // Konfiguracja SSO
6 }
7});
8

Zobacz dokumentację SSO, aby uzyskać pełne informacje o opcjach uwierzytelniania.

maxReplyDepth

Kontroluj, jak głęboko mogą sięgać odpowiedzi. Domyślnie Collab Chat ustawia to na 0, co oznacza, że wszystkie komentarze są płaskie (bez zagnieżdżonych odpowiedzi). Możesz to zmienić, jeśli chcesz rozmów w formie wątków.

Przykład konfiguracji
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Pozwól na 3 poziomy zagnieżdżenia
5});
6

Konfiguracja wewnętrzna

Te opcje są ustawiane automatycznie przez Collab Chat i nie powinny być nadpisywane:

Wartość productId jest automatycznie ustawiana na 3 dla Collab Chat. Rozszerzenie floating-chat jest automatycznie ładowane, aby zapewnić funkcjonalność okna czatu. Widżet automatycznie wykrywa urządzenia mobilne (ekrany poniżej 768px szerokości) i odpowiednio dostosowuje UI.

Pełny przykład

Poniżej przykład pokazujący kilka opcji konfiguracyjnych razem:

Przykład konfiguracji
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 // Twoja konfiguracja SSO
13 },
14 maxReplyDepth: 1
15});
16

Pełną listę wszystkich dostępnych opcji konfiguracyjnych dziedziczonych z podstawowego widżetu znajdziesz w głównej dokumentacji konfiguracji FastComments.

Zachowanie zaznaczania tekstu Internal Link

Jak działa zaznaczanie tekstu

Gdy użytkownicy zaznaczają tekst w kontenerze Collab Chat, widget przechwytuje to zaznaczenie i umożliwia rozpoczęcie dyskusji. Zaznaczenie może obejmować pojedyncze słowo lub kilka akapitów rozciągających się przez różne elementy.

Opóźnienie wyświetlania

Na komputerach stacjonarnych występuje opóźnienie 3,5 sekundy między momentem zaznaczenia tekstu a pojawieniem się wezwania do dyskusji. Zapobiega to migotaniu interfejsu, gdy użytkownicy jedynie zaznaczają tekst, aby go skopiować lub przeczytać. Na urządzeniach mobilnych wezwanie pojawia się natychmiast, ponieważ zaznaczanie tekstu na ekranach dotykowych jest zwykle bardziej zamierzone.

Unikalne identyfikatory konwersacji

Każda konwersacja otrzymuje unikalny urlId, który łączy URL strony, ścieżkę elementu DOM oraz zserializowany zakres tekstu. Zapewnia to, że każde zaznaczenie tekstu tworzy odrębną konwersację, którą można później ponownie odnaleźć.

Jeśli w konfiguracji podasz niestandardowy urlId, zostanie on połączony ze ścieżką elementu i zakresem tekstu, aby utworzyć końcowy identyfikator.

Wyróżnienia wizualne

Gdy dla konkretnego zaznaczenia tekstu istnieje dyskusja, tekst ten otrzymuje wyróżnienie wizualne. Wyróżnienie jest realizowane przy użyciu kolorów tła i pojawia się przy najechaniu kursorem lub gdy powiązane okno czatu jest otwarte.

System wyróżnień działa poprzez opakowanie zaznaczonego tekstu w specjalny element, który można wystylizować. Takie podejście zapewnia, że wyróżnienia pozostają dokładne nawet wtedy, gdy struktura HTML jest skomplikowana.

Pozycjonowanie okna czatu

Gdy użytkownik kliknie wyróżnienie lub utworzy nowe adnotacje, w pobliżu zaznaczonego tekstu pojawia się okno czatu. Widget automatycznie oblicza najlepszą pozycję tego okna na podstawie dostępnej przestrzeni w widoku.

System pozycjonowania używa klas CSS takich jak to-right, to-left, to-top i to-bottom, aby wskazać, w którym kierunku okno czatu powinno się rozciągać od wyróżnienia. Na urządzeniach mobilnych (ekrany o szerokości poniżej 768px) okno czatu zawsze pojawia się w trybie pełnoekranowym dla lepszej użyteczności.

Wymiary okna czatu

Okna czatu mają szerokość 410px na komputerach stacjonarnych, z odstępem 20px i 16px wizualną strzałką wskazującą na wyróżniony tekst. Te wymiary są stałe, aby zapewnić spójne zachowanie, ale wygląd można dostosować za pomocą CSS.

Zaznaczenia obejmujące wiele elementów

Użytkownicy mogą zaznaczać tekst rozciągający się przez wiele elementów HTML, na przykład od środka jednego akapitu do początku innego. System serializacji zakresu obsługuje to poprawnie i wyróżni cały zaznaczony tekst nawet na granicach elementów.

Kompatybilność z przeglądarkami

System zaznaczania tekstu używa standardowego API window.getSelection(), które jest obsługiwane we wszystkich nowoczesnych przeglądarkach. Dla starszych wersji Internet Explorera stosowany jest fallback do document.selection w celu zachowania kompatybilności.

Trwałość zaznaczeń

Po utworzeniu konwersacji dla zaznaczenia tekstu, ta adnotacja pozostaje nawet po odświeżeniu strony. Zserializowany zakres i ścieżka DOM pozwalają widgetowi przywrócić wyróżnienia w dokładnie tym samym miejscu, gdy użytkownicy wrócą na stronę.

Działa to niezawodnie, o ile zawartość strony pozostaje stabilna. Jeśli zmienisz treść tekstu lub przebudujesz strukturę HTML, istniejące adnotacje mogą przestać prawidłowo odpowiadać tekstowi. Z tego powodu najlepiej unikać większych zmian zawartości na stronach z aktywnymi adnotacjami lub rozważyć migrację adnotacji, gdy zmiany treści są niezbędne.

Dostosowywanie Internal Link

Obsługa trybu ciemnego

Dynamiczny tryb ciemny

Jeśli tryb ciemny na Twojej stronie jest kontrolowany przez dodanie klasy .dark do elementu body, interfejs Collab Chat automatycznie go uwzględni bez konieczności ponownej inicjalizacji. Style widżetu są zaprojektowane tak, aby reagować na obecność tej klasy.

Przykład CSS dla trybu ciemnego
Copy Copy
1
2/* Twój CSS dla trybu ciemnego */
3body.dark {
4 background: #1a1a1a;
5 color: #ffffff;
6}
7

Niestandardowe style za pomocą CSS

Możesz dostosować wygląd wyróżnień, okien czatu i innych elementów za pomocą CSS. Widżet dodaje określone klasy, które możesz adresować w swoim arkuszu stylów.

Wyróżnienia tekstu korzystają z systemu stylów dymków komentarzy FastComments, więc wszelkie modyfikacje zastosowane do standardowego widżetu komentarzy będą również wpływać na Collab Chat.

Dostosowywanie górnego paska

Górny pasek pokazuje liczbę użytkowników online oraz liczbę dyskusji. Możesz dostosować jego położenie, podając niestandardowy element jako topBarTarget:

Niestandardowa lokalizacja górnego paska
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: document.getElementById('my-custom-header')
5});
6

Lub całkowicie go wyłączyć ustawiając wartość na null:

Wyłącz górny pasek
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: null
5});
6

Zachowanie na urządzeniach mobilnych

Na ekranach o szerokości poniżej 768px, Collab Chat automatycznie przełącza się na układ zoptymalizowany pod urządzenia mobilne. Okna czatu pojawiają się w trybie pełnoekranowym zamiast pływać obok tekstu, a opóźnienie zaznaczania jest usunięte dla bardziej natychmiastowej interakcji.

To zachowanie jest wbudowane i nie wymaga konfiguracji. Widżet automatycznie wykrywa rozmiar ekranu i dostosowuje się odpowiednio.

Wygląd okna czatu

Okna czatu mają szerokość 410px na desktopie z 16px strzałką wskazującą na wyróżniony tekst. Okna pozycjonują się automatycznie w zależności od dostępnej przestrzeni widoku, używając klas pozycjonujących takich jak to-right, to-left, to-top i to-bottom.

Możesz dodać niestandardowy CSS, aby dostosować kolory, czcionki, odstępy lub inne właściwości wizualne tych okien. Okna czatu używają tej samej struktury komponentów co standardowy widżet FastComments, więc dziedziczą wszelkie globalne dostosowania, które zastosowałeś.

Lokalizacja

Collab Chat obsługuje te same opcje lokalizacji co standardowy widżet FastComments. Ustaw opcję locale, aby wyświetlić tekst interfejsu w różnych językach:

Ustaw lokalizację
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Hiszpański
5});
6

FastComments obsługuje dziesiątki języków. Ustawienie locale wpływa na cały tekst interfejsu użytkownika, w tym monity, przyciski i teksty zastępcze.

Dziedziczone opcje dostosowywania

Ponieważ Collab Chat rozszerza standardowy widżet komentarzy, dziedziczy wszystkie opcje dostosowywania z podstawowego widżetu. Obejmuje to niestandardowe klasy CSS, niestandardowe tłumaczenia, dostosowanie avatarów, formatowanie dat i wiele innych.

Zobacz główną dokumentację dotyczącą dostosowywania FastComments, aby uzyskać pełną listę dostępnych opcji dostosowywania.

Praca z niestandardowymi czcionkami

Jeśli Twoja strona używa niestandardowych czcionek, interfejs Collab Chat odziedziczy te czcionki z CSS Twojej strony. Może być konieczne utworzenie reguły dostosowywania widżetu i użycie @import dowolnych czcionek w niestandardowym CSS w tej regule, jeśli chcesz aby pływające okno czatu korzystało z tych samych czcionek.

Synchronizacja w czasie rzeczywistym Internal Link

Aktualizacje w czasie rzeczywistym

Collab Chat używa połączeń WebSocket do synchronizacji wszystkich rozmów w czasie rzeczywistym między wszystkimi połączonymi użytkownikami. Gdy ktoś tworzy nową adnotację, dodaje komentarz lub usuwa dyskusję, wszyscy inni użytkownicy oglądający tę samą stronę widzą aktualizację natychmiast bez odświeżania.

Jak działa synchronizacja przez WebSocket

Po zainicjowaniu Collab Chat widget nawiązuje połączenie WebSocket z serwerami FastComments. Połączenie to pozostaje otwarte przez czas trwania sesji użytkownika i nasłuchuje aktualizacji związanych z bieżącą stroną.

System WebSocket używa trzech typów komunikatów rozsyłanych (broadcast) dla Collab Chat. Zdarzenie new-text-chat uruchamia się, gdy ktoś tworzy nową adnotację na stronie. Zdarzenie updated-text-chat uruchamia się, gdy ktoś aktualizuje istniejącą konwersację. Zdarzenie deleted-text-chat uruchamia się, gdy ktoś usuwa adnotację.

System Broadcast ID

Aby zapobiec efektowi echa, w którym użytkownicy widzą swoje własne działania przesyłane z powrotem, każda aktualizacja zawiera unikalny broadcastId. Gdy użytkownik tworzy lub aktualizuje adnotację, jego klient generuje UUID dla tej operacji. Gdy WebSocket rozsyła aktualizację z powrotem do wszystkich klientów, klient źródłowy ignoruje ją, ponieważ zgadza się z jego własnym broadcastId.

Zapewnia to płynne działanie: użytkownicy widzą swoje zmiany natychmiast w interfejsie bez oczekiwania na pełen obieg przez serwer, a jednocześnie wszyscy pozostali użytkownicy otrzymują aktualizację.

Liczba użytkowników na żywo

Górny pasek pokazuje liczbę użytkowników aktualnie przeglądających stronę. Ta liczba aktualizuje się w czasie rzeczywistym, gdy użytkownicy dołączają i opuszczają stronę. Liczba użytkowników jest dostarczana przez to samo połączenie WebSocket i zwiększa/zmniejsza się automatycznie w oparciu o zdarzenia połączenia i rozłączenia.

Odporność połączenia

Jeśli połączenie WebSocket zostanie przerwane z powodu problemów z siecią lub konserwacji serwera, widget automatycznie próbuje ponownie nawiązać połączenie. W czasie ponownego łączenia użytkownicy nadal mogą wchodzić w interakcje z istniejącymi adnotacjami, jednak nie będą widzieć aktualizacji w czasie rzeczywistym od innych użytkowników, dopóki połączenie nie zostanie przywrócone.

Po ponownym nawiązaniu połączenia widget ponownie synchronizuje stan, aby upewnić się, że nie przegapiono żadnych aktualizacji. Dzieje się to w przejrzysty sposób, bez konieczności ingerencji użytkownika.

Uwagi dotyczące przepustowości

Komunikaty WebSocket są lekkie i zawierają tylko niezbędne informacje potrzebne do synchronizacji stanu. Utworzenie nowej adnotacji zazwyczaj zużywa mniej niż 1KB przepustowości. System zawiera również inteligentne grupowanie komunikatów (batching), aby zmniejszyć częstotliwość wiadomości w okresach dużej aktywności.

Twoje metryki użycia w panelu FastComments śledzą pubSubMessageCount i pubSubBandwidth, dzięki czemu możesz monitorować aktywność synchronizacji w czasie rzeczywistym na swoich witrynach.

Synchronizacja między zakładkami

Jeśli użytkownik ma tę samą stronę otwartą w wielu kartach przeglądarki, aktualizacje w jednej karcie pojawiają się natychmiast w pozostałych kartach. Działa to przez ten sam mechanizm synchronizacji WebSocket i nie wymaga dodatkowej konfiguracji.

Bezpieczeństwo

Komunikaty WebSocket są przesyłane przez bezpieczne połączenia (WSS) i zawierają walidację najemcy (tenant validation), aby zapewnić, że użytkownicy otrzymują tylko aktualizacje do konwersacji, do których mają uprawnienia. Serwer weryfikuje wszystkie operacje przed ich rozesłaniem, aby zapobiec nieautoryzowanemu dostępowi lub manipulacji.

Dokumentacja API Internal Link

Przegląd API

Collab Chat udostępnia trzy punkty końcowe REST API do programowego zarządzania rozmowami tekstowymi. Te punkty końcowe pozwalają pobierać, tworzyć i usuwać adnotacje bez użycia widżetu w przeglądarce.

Są to publiczne punkty końcowe, które uwierzytelniają użytkowników za pomocą ciasteczek przeglądarki. Nie używają kluczy API. Użytkownicy muszą być zalogowani do FastComments w swojej przeglądarce, aby uzyskać dostęp do tych punktów końcowych.

URL bazowy

Wszystkie punkty końcowe API Collab Chat znajdują się pod:

URL bazowy
Copy Copy
1
2https://fastcomments.com/comment-collab-chats
3

Uwierzytelnianie

Te punkty końcowe uwierzytelniają użytkowników za pomocą ciasteczek przeglądarki. Nie używają kluczy API. Użytkownicy muszą być zalogowani do FastComments w swojej przeglądarce, aby uzyskać dostęp do tych punktów końcowych.

Pobierz wszystkie konwersacje

Pobierz wszystkie rozmowy tekstowe dla określonej strony.

Punkt końcowy

Punkt końcowy GET
Copy Copy
1
2GET /comment-collab-chats/:tenantId?urlId=<urlId>
3

Parametry

tenantId (parametr ścieżki, wymagany) to Twój FastComments Tenant ID.

urlId (parametr zapytania, wymagany) to identyfikator strony, dla której chcesz pobrać konwersacje.

Odpowiedź

Odpowiedź zawiera status API, informacje o bieżącej sesji użytkownika (jeśli uwierzytelniony), tablicę konwersacji z ich identyfikatorami, URL-ami i zakresami tekstu, oczyszczony identyfikator URL, flagę wskazującą, czy bieżący użytkownik jest administratorem strony lub moderatorem, oraz dane połączenia WebSocket do synchronizacji na żywo, w tym tenantIdWS, urlIdWS i userIdWS.

Przykład żądania

Przykład żądania GET
Copy Copy
1
2curl "https://fastcomments.com/comment-collab-chats/demo?urlId=my-article-page" \
3 --cookie "your-session-cookie"
4

Przykład odpowiedzi

Przykład odpowiedzi 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

Utwórz konwersację

Utwórz nową konwersację tekstową dla określonego zaznaczenia tekstu.

Punkt końcowy

Punkt końcowy POST
Copy Copy
1
2POST /comment-collab-chats/:tenantId
3

Parametry

tenantId (parametr ścieżki, wymagany) to Twój FastComments Tenant ID.

Ciało żądania musi być w formacie JSON i zawierać następujące wymagane pola.

urlId (string, wymagany) to podstawowy identyfikator strony.

urlIdWithRange (string, wymagany) to URL połączony z zakresem tekstu, na przykład my-page:p:0:15,0:45{abc123}.

pageTitle (string, wymagany) to tytuł strony.

selector (string, wymagany) to ścieżka DOM do elementu zawierającego zaznaczony tekst.

range (string, wymagany) to zserializowany zakres tekstu w formacie startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (string, wymagany) to ID komentarza, który zainicjował tę rozmowę.

broadcastId (string, wymagany) to UUID do synchronizacji na żywo, zapobiegający efektom echa.

Odpowiedź

Odpowiedź zawiera status API oraz identyfikator nowo utworzonej konwersacji.

Przykład żądania

Przykład żądania 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

Przykład odpowiedzi

Przykład odpowiedzi POST
Copy Copy
1
2{
3 "status": "success",
4 "createdChatId": "conv789"
5}
6

Usuń konwersację

Usuń istniejącą konwersację tekstową. Ten punkt końcowy wymaga uprawnień administratora lub moderatora, albo konwersacja musi być utworzona przez uwierzytelnionego użytkownika.

Punkt końcowy

Punkt końcowy DELETE
Copy Copy
1
2DELETE /comment-collab-chats/:tenantId/:chatId
3

Parametry

tenantId (parametr ścieżki, wymagany) to Twój FastComments Tenant ID.

chatId (parametr ścieżki, wymagany) to ID konwersacji do usunięcia.

broadcastId (ciało żądania, wymagany) to UUID do synchronizacji na żywo.

Przykład żądania

Przykład żądania 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

Przykład odpowiedzi

Przykład odpowiedzi DELETE
Copy Copy
1
2{
3 "status": "success"
4}
5

Ograniczanie liczby żądań

Te punkty końcowe podlegają standardowym ograniczeniom liczby żądań API FastComments. Middleware limitujący żądania działa na poziomie najemcy (tenant), aby zapobiegać nadużyciom przy jednoczesnym umożliwieniu normalnych wzorców użycia.

Odpowiedzi z błędami

Wszystkie punkty końcowe zwracają standardowe kody statusu HTTP. Odpowiedź 400 oznacza nieprawidłowe parametry żądania. Odpowiedź 401 oznacza niepowodzenie uwierzytelnienia. Odpowiedź 403 wskazuje na niewystarczające uprawnienia. Odpowiedź 404 oznacza, że konwersacja nie została znaleziona. Odpowiedź 429 oznacza przekroczenie limitu żądań.

Odpowiedzi z błędami zawierają ciało JSON z szczegółami:

Przykład odpowiedzi z błędem
Copy Copy
1
2{
3 "status": "error",
4 "message": "Conversation not found"
5}
6

Śledzenie użycia

Tworzenie konwersacji zwiększa Twój miernik wykorzystania conversationCreateCount. Cała aktywność synchronizacji przez WebSocket zwiększa pubSubMessageCount i pubSubBandwidth. Możesz monitorować te metryki w panelu FastComments w sekcji analityki użycia.

Masz pytania?

To wszystko na temat FastComments Collab Chat! Jeśli masz pytania, potrzebujesz pomocy przy implementacji lub masz sugestie dotyczące funkcji, daj nam znać poniżej lub skontaktuj się z naszym zespołem wsparcia.

Aby zobaczyć przykłady na żywo, sprawdź Govscent.org, który wykorzystuje Collab Chat w środowisku produkcyjnym.

Współtwórz ten przewodnik