FastComments.com

Menu Icon

Taal 🇳🇱 Nederlands
🇺🇸 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

Aan de slag

Aan de slag
Voorbeelden
Live commentaar toevoegen aan online boeken

Configuratie

Configuratie-opties
Gedrag bij tekstselectie

Aanpassing

Aanpassing

Geavanceerd

Live-synchronisatie
API-referentie

Voeg inline live-opmerkingen toe aan documenten, boeken, enz.

FastComments Collab Chat stelt gebruikers in staat om tekstinhoud op uw website te markeren en te annoteren, en creëert daarmee gespreksdraden die gekoppeld zijn aan specifieke tekstselecties. Gebruikers kunnen woorden, zinnen of hele alinea's selecteren om direct binnen uw inhoud samenwerkingsgesprekken te starten.

Deze functie is perfect voor redactionele feedback, samenleesomgevingen, educatieve platforms, documentbeoordeling en elke situatie waarin u contextuele discussies wilt verankeren aan specifieke tekst.

Let op dat deze docs specifiek zijn voor de Collab Chat functionaliteit. U kunt opmerkingen toevoegen aan content met veel pagina's, zoals Books, met thread-per-page, zonder gebruik te maken van collab chat. FastComments also does not charge per-page or per-thread. Collab Chat is specifiek wanneer u gebruikers wilt toestaan tekst te selecteren en te reageren op het gemarkeerde tekstgedeelte.

U kunt een voorbeeld hier bekijken.

Aan de slag Internal Link

Snel aan de slag

Aan de slag met Collab Chat is eenvoudig. U heeft het FastComments Collab Chat-script nodig, een HTML-element dat de tekst bevat die u wilt annoteren, en een configuratieobject met uw Tenant ID.

Installatie

Voeg het Collab Chat-script aan uw pagina toe:

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

Basisimplementatie

Hier is een minimaal voorbeeld:

Basisimplementatie van 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 <!-- Uw inhoudcontainer -->
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 <!-- Laad het Collab Chat-script -->
16 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
17
18 <!-- Initialiseer Collab Chat -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

Vervang 'demo' door uw werkelijke FastComments Tenant ID als dat nog niet het geval is; deze vindt u in uw FastComments-dashboard.

Hoe het werkt

Zodra het is geïnitialiseerd, kunnen gebruikers willekeurige tekst binnen het doel-element selecteren. Na een korte vertraging (3,5 seconden op desktop) verschijnt er een prompt waarmee ze een discussie kunnen starten. Wanneer een discussie wordt aangemaakt, verschijnt er een visuele markering op de tekst. Andere gebruikers kunnen met de muis over de markering zweven of erop klikken om de discussie te bekijken en eraan deel te nemen. Alle discussies synchroniseren in realtime tussen alle bezoekers.

Live demo

U kunt Collab Chat in actie zien op onze live demo-pagina.

Volgende stappen

Nu u de basis werkend heeft, kunt u het uiterlijk en gedrag aanpassen in de gids Configuratieopties. Bekijk de gids Tekstselectiegedrag om te begrijpen hoe tekstselectie werkt. Lees over styling en ondersteuning voor donkere modus in de gids Aanpassing. Voor geavanceerde integraties, bekijk de API-referentie.

Frontend-bibliotheken

Alle FastComments-frontendbibliotheken (react, vue, angular, etc) hebben Collab Chat.

Voorbeelden Internal Link

Basisvoorbeeld

De eenvoudigste manier om Collab Chat te gebruiken is door je te richten op één inhoudscontainer. Dit voorbeeld toont hoe je tekstannotaties voor een artikel inschakelt:

Basisvoorbeeld van 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

Voorbeeld met aangepast URL-ID (per boekpagina, artikel, enz.)

Standaard gebruikt Collab Chat de URL van de pagina, gecombineerd met het elementpad en het tekstbereik, om gesprekken te identificeren. Je kunt een aangepaste urlId opgeven om meer controle te krijgen over hoe gesprekken gegroepeerd worden:

Collab Chat met aangepaste 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

Dit is handig als je URL-structuur verandert maar je dezelfde gesprekken wilt behouden, of als je dezelfde annotaties van gesprekken op meerdere pagina's wilt delen.

Voorbeeld met donkere modus

Als je site een donkere achtergrond heeft, schakel dan ondersteuning voor donkere modus in om ervoor te zorgen dat de chat-UI er correct uitziet:

Collab Chat met donkere modus
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

Voorbeeld met bovenbalk uitgeschakeld

Standaard toont Collab Chat een bovenbalk met het aantal gebruikers en het aantal discussies. Je kunt deze uitschakelen:

Collab Chat met bovenbalk uitgeschakeld
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

Voorbeeld met callback voor aantal reacties

Je kunt bijhouden wanneer opmerkingen worden toegevoegd of bijgewerkt met de callback commentCountUpdated:

Collab Chat met callback voor aantal reacties
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

Voorbeeld met meerdere secties

Je kunt Collab Chat initialiseren op meerdere aparte secties van je pagina. Elke sectie krijgt zijn eigen onafhankelijke annotaties:

Collab Chat op meerdere secties
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 // Initialize on intro section
15 FastCommentsCollabChat(document.getElementById('intro-section'), {
16 tenantId: 'demo',
17 urlId: 'my-article-intro'
18 });
19
20 // Initialize on main section
21 FastCommentsCollabChat(document.getElementById('main-section'), {
22 tenantId: 'demo',
23 urlId: 'my-article-main'
24 });
25</script>
26

Live commentaar toevoegen aan online boeken Internal Link

U kunt Collab Chat per pagina initialiseren indien gewenst, en per pagina afzonderlijke threads hebben; geef gewoon de urlId parameter een waarde zoals book-one-page1. Deze configuratie werkt ook voor de normale commentaarwidget.

Configuratie-opties Internal Link

Overzicht

FastComments Collab Chat breidt de standaard FastComments-commentaarwidget uit, dus het erft alle configuratieopties van de basiswidget en voegt enkele opties toe die specifiek zijn voor tekstannotaties.

Vereiste configuratie

tenantId

Uw FastComments Tenant ID is verplicht. U kunt dit vinden in uw FastComments dashboard.

Configuratievoorbeeld
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo'
4});
5

Collab Chat-specifieke opties

urlId

Standaard genereert Collab Chat een unieke identificatie voor elk gesprek op basis van de pagina-URL, het DOM-pad naar het element en het geselecteerde tekstdbereik. U kunt dit overschrijven met een aangepaste urlId.

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

Dit is handig wanneer uw URL-structuur kan veranderen maar u dezelfde gesprekken wilt behouden, of wanneer u annotaties over meerdere pagina's wilt delen.

topBarTarget

Regelt de weergave van de bovenste balk die het aantal gebruikers en discussies toont. Stel in op null om de bovenste balk volledig uit te schakelen, of geef een DOM-element op om deze op een specifieke locatie te renderen.

Configuratievoorbeeld
Copy Copy
1
2// Topbalk uitschakelen
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Topbalk weergeven op aangepaste locatie
9FastCommentsCollabChat(element, {
10 tenantId: 'demo',
11 topBarTarget: document.getElementById('custom-header')
12});
13

hasDarkBackground

Schakel donkere modus-styling in wanneer uw pagina een donkere achtergrond heeft. Deze detectie is automatisch, maar het kan wenselijk zijn om deze te overschrijven.

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

commentCountUpdated

Een callbackfunctie die wordt aangeroepen telkens wanneer het aantal opmerkingen verandert. Dit is handig voor het bijwerken van UI-elementen zoals badges of paginatitels.

Configuratievoorbeeld
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

Geërfde configuratie-opties

Aangezien Collab Chat de standaardcommentaarwidget uitbreidt, kunt u elke configuratieoptie van de basis FastComments-widget gebruiken. Hier zijn enkele vaak gebruikte opties:

locale

Stel de taal in voor de widget-UI. FastComments ondersteunt tientallen talen.

Configuratievoorbeeld
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Spaans
5});
6

readonly

Maak alle conversaties alleen-lezen. Gebruikers kunnen bestaande annotaties bekijken maar geen nieuwe maken of reageren.

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

sso and simpleSSO

Integreer met uw authenticatiesysteem met Single Sign-On.

Configuratievoorbeeld
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 sso: {
5 // SSO-configuratie
6 }
7});
8

Zie de SSO-documentatie voor volledige details over authenticatieopties.

maxReplyDepth

Beheer hoe diep replies genest mogen zijn. Standaard stelt Collab Chat dit in op 0, wat betekent dat alle opmerkingen vlak zijn (geen geneste antwoorden). U kunt dit wijzigen als u draadgesprekken wilt.

Configuratievoorbeeld
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Sta 3 niveaus van geneste reacties toe
5});
6

Interne configuratie

Deze opties worden automatisch ingesteld door Collab Chat en mogen niet worden overschreven:

De productId wordt automatisch ingesteld op 3 voor Collab Chat. De extensie floating-chat wordt automatisch geladen om de chatvensterfunctionaliteit te bieden. De widget detecteert automatisch mobiele apparaten (schermen smaller dan 768px) en past de UI dienovereenkomstig aan.

Volledig voorbeeld

Hier is een voorbeeld waarin meerdere configuratieopties samen worden getoond:

Configuratievoorbeeld
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 // Uw SSO-configuratie
13 },
14 maxReplyDepth: 1
15});
16

Voor een volledige lijst van alle beschikbare configuratieopties die worden geërfd van de basiswidget, zie de hoofd FastComments-configuratiedocumentatie.

Gedrag bij tekstselectie Internal Link

Hoe tekstselectie werkt

Wanneer gebruikers tekst selecteren binnen de Collab Chat-container, legt de widget die selectie vast en stelt hen in staat een discussie te starten. De selectie kan zo klein zijn als één woord of zo groot als meerdere alinea's die verschillende elementen overspannen.

Selectievertraging

Op desktopapparaten is er een vertraging van 3,5 seconden tussen het moment dat een gebruiker tekst selecteert en het moment waarop de discussieprompt verschijnt. Dit voorkomt dat de UI knippert wanneer gebruikers gewoon tekst markeren om te kopiëren of te lezen. Op mobiele apparaten verschijnt de prompt onmiddellijk aangezien tekstselectie op aanraakschermen doelbewuster is.

Unieke conversatie-ID's

Elke conversatie krijgt een unieke urlId die de paginakoppeling, het DOM-elementpad en het geserialiseerde textrange combineert. Dit zorgt ervoor dat elke tekstselectie een afzonderlijke conversatie creëert die later weer teruggevonden kan worden.

Als u een aangepaste urlId in uw configuratie opgeeft, wordt deze gecombineerd met het elementpad en het textrange om de uiteindelijke identifier te maken.

Visuele markeringen

Wanneer er een discussie bestaat voor een bepaalde tekstselectie, krijgt die tekst een visuele markering. De markering wordt geïmplementeerd met behulp van achtergrondkleuren en verschijnt bij hover of wanneer het bijbehorende chatvenster geopend is.

Het markeersysteem werkt door de geselecteerde tekst te omhullen met een speciaal element dat gestyled kan worden. Deze aanpak zorgt ervoor dat markeringen nauwkeurig blijven, zelfs wanneer de onderliggende HTML-structuur complex is.

Positionering van het chatvenster

Wanneer een gebruiker op een markering klikt of een nieuwe annotatie maakt, verschijnt er een chatvenster in de buurt van de geselecteerde tekst. De widget berekent automatisch de beste positie voor dit venster op basis van de beschikbare viewportruimte.

Het positioneringssysteem gebruikt CSS-klassen zoals to-right, to-left, to-top, en to-bottom om aan te geven in welke richting het chatvenster vanaf de markering moet uitvouwen. Op mobiele apparaten (schermen smaller dan 768px) verschijnt het chatvenster altijd fullscreen voor betere bruikbaarheid.

Afmetingen van het chatvenster

Chatvensters zijn 410px breed op desktop met 20px tussenruimte en een visuele pijl van 16px die naar de gemarkeerde tekst wijst. Deze afmetingen zijn vast om consistent gedrag te garanderen, maar u kunt de uitstraling aanpassen met CSS.

Selecties over meerdere elementen

Gebruikers kunnen tekst selecteren die meerdere HTML-elementen overspant, zoals markeren vanaf het midden van de ene alinea tot het begin van een andere. Het range-serialisatiesysteem behandelt dit correct en zal alle geselecteerde tekst markeren, zelfs over elementgrenzen heen.

Browsercompatibiliteit

Het tekstselectiesysteem gebruikt de standaard window.getSelection() API die wordt ondersteund in alle moderne browsers. Voor oudere versies van Internet Explorer valt het terug op document.selection voor compatibiliteit.

Persistentie van selecties

Zodra er een conversatie is aangemaakt voor een tekstselectie, blijft die annotatie bestaan zelfs als de pagina wordt vernieuwd. Het geserialiseerde range en het DOM-pad stellen de widget in staat markeringen op precies dezelfde plaats te herstellen wanneer gebruikers terugkeren naar de pagina.

Dit werkt betrouwbaar zolang uw paginacontent stabiel blijft. Als u de tekstinhoud wijzigt of uw HTML herstructureert, kunnen bestaande annotaties mogelijk niet meer correct uitlijnen met de tekst. Om deze reden is het het beste om grote inhoudswijzigingen op pagina's met actieve annotaties te vermijden, of te overwegen annotaties te migreren wanneer inhoudswijzigingen noodzakelijk zijn.

Aanpassing Internal Link

Donkere modus-ondersteuning

Dynamische donkere modus

Als de donkere modus van uw site wordt geregeld door een .dark-klasse aan het body-element toe te voegen, respecteert de Collab Chat UI dit automatisch zonder herinitialisatie. De stijlen van de widget zijn zo ontworpen dat ze reageren op de aanwezigheid van deze klasse.

Voorbeeld CSS voor donkere modus
Copy Copy
1
2/* Uw CSS voor donkere modus */
3body.dark {
4 background: #1a1a1a;
5 color: #ffffff;
6}
7

Aangepaste styling met CSS

U kunt het uiterlijk van markeringen, chatvensters en andere elementen aanpassen met CSS. De widget voegt specifieke klassen toe die u in uw stylesheet kunt targeten.

Tekstmarkeringen gebruiken het FastComments-stijlsysteem voor commentbubbels, dus eventuele aanpassingen die u op de standaard commentaarwidget hebt toegepast, hebben ook invloed op Collab Chat.

Aanpassen van de bovenbalk

De bovenbalk toont het aantal gebruikers online en het aantal discussies. U kunt de positie aanpassen door een aangepast element op te geven als topBarTarget:

Aangepaste locatie voor bovenbalk
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: document.getElementById('my-custom-header')
5});
6

Of schakel het volledig uit door het op null te zetten:

Bovenbalk uitschakelen
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: null
5});
6

Mobiel gedrag

Op schermen die smaller zijn dan 768px schakelt Collab Chat automatisch over naar een mobiel geoptimaliseerde lay-out. Chatvensters verschijnen fullscreen in plaats van zwevend naast de tekst, en de selectievertraging wordt verwijderd voor directere interactie.

Dit gedrag is ingebouwd en vereist geen configuratie. De widget detecteert automatisch de schermgrootte en past zich dienovereenkomstig aan.

Uiterlijk van chatvensters

Chatvensters zijn op desktop 410px breed met een pijl van 16px die naar de gemarkeerde tekst wijst. De vensters positioneren zichzelf automatisch op basis van de beschikbare viewport-ruimte, waarbij positioneringsklassen zoals to-right, to-left, to-top en to-bottom worden gebruikt.

U kunt aangepaste CSS toevoegen om kleuren, lettertypen, afstand of andere visuele eigenschappen van deze vensters aan te passen. De chatvensters gebruiken dezelfde componentstructuur als de standaard FastComments-widget, dus ze erven eventuele globale aanpassingen die u hebt toegepast.

Lokalisatie

Collab Chat ondersteunt alle dezelfde lokalisatie-opties als de standaard FastComments-widget. Stel de optie locale in om UI-tekst in andere talen weer te geven:

Locale instellen
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Spaans
5});
6

FastComments ondersteunt tientallen talen. De locale-instelling beïnvloedt alle UI-tekst, inclusief prompts, knoppen en placeholder-tekst.

Geërfde aanpassingsopties

Aangezien Collab Chat het standaard commentaarwidget uitbreidt, erft het alle aanpassingsopties van het basiswidget. Dit omvat aangepaste CSS-klassen, aangepaste vertalingen, avatar-aanpassing, datumopmaak en nog veel meer.

Zie de hoofddocumentatie van FastComments voor een volledige lijst met beschikbare aanpassingsopties.

Werken met aangepaste lettertypen

Als uw site aangepaste lettertypen gebruikt, erft de Collab Chat UI die lettertypen van de CSS van uw pagina. U moet mogelijk een widget-aanpassingsregel maken en @import eventuele lettertypen in de aangepaste CSS in die regel als u wilt dat het zwevende chatvenster dezelfde lettertypen gebruikt.

Live-synchronisatie Internal Link

Realtime-updates

Collab Chat gebruikt WebSocket-verbindingen om alle gesprekken in realtime te synchroniseren tussen alle verbonden gebruikers. Wanneer iemand een nieuwe annotatie maakt, een opmerking toevoegt of een discussie verwijdert, zien alle andere gebruikers die dezelfde pagina bekijken de update onmiddellijk zonder te verversen.

Hoe WebSocket-synchronisatie werkt

Wanneer je Collab Chat initialiseert, maakt de widget een WebSocket-verbinding met de FastComments-servers. Deze verbinding blijft open gedurende de sessie van de gebruiker en luistert naar updates die betrekking hebben op de huidige pagina.

Het WebSocket-systeem gebruikt drie typen broadcast-berichten voor Collab Chat. Het new-text-chat-event wordt geactiveerd wanneer iemand een nieuwe annotatie op de pagina maakt. Het updated-text-chat-event wordt geactiveerd wanneer iemand een bestaand gesprek bijwerkt. Het deleted-text-chat-event wordt geactiveerd wanneer iemand een annotatie verwijdert.

Broadcast-ID-systeem

Om echo-effecten te voorkomen waarbij gebruikers hun eigen acties teruggezien krijgen, bevat elke update een unieke broadcastId. Wanneer een gebruiker een annotatie maakt of bijwerkt, genereert hun client een UUID voor die bewerking. Wanneer de WebSocket de update terug naar alle clients uitzendt, negeert de oorspronkelijke client de update omdat deze overeenkomt met zijn eigen broadcastId.

Dit zorgt voor een vloeiende interactie waarbij gebruikers hun wijzigingen onmiddellijk in de UI zien zonder te wachten op de retourronde via de server, terwijl alsnog wordt gegarandeerd dat alle andere gebruikers de update ontvangen.

Live gebruikersaantal

De bovenste balk toont het aantal gebruikers dat momenteel de pagina bekijkt. Dit aantal wordt in realtime bijgewerkt wanneer gebruikers toetreden en vertrekken. Het gebruikersaantal wordt geleverd via dezelfde WebSocket-verbinding en neemt automatisch toe/af op basis van verbindings- en ontkoppelingsgebeurtenissen.

Verbindingsherstel

Als de WebSocket-verbinding wegvalt door netwerkproblemen of serveronderhoud, probeert de widget automatisch opnieuw verbinding te maken. Tijdens de periode van opnieuw verbinden kunnen gebruikers nog steeds met bestaande annotaties werken, maar ze zien geen realtime-updates van andere gebruikers totdat de verbinding is hersteld.

Zodra de verbinding opnieuw tot stand is gebracht, synchroniseert de widget opnieuw om ervoor te zorgen dat er geen updates zijn gemist. Dit gebeurt transparant zonder dat de gebruiker iets hoeft te doen.

Bandbreedte-overwegingen

WebSocket-berichten zijn lichtgewicht en bevatten alleen de essentiële informatie die nodig is om de staat te synchroniseren. Het aanmaken van een nieuwe annotatie gebruikt doorgaans minder dan 1KB aan bandbreedte. Het systeem bevat ook intelligente batching om de frequentie van berichten te verminderen tijdens periodes met veel activiteit.

Je gebruiksstatistieken in het FastComments-dashboard volgen pubSubMessageCount en pubSubBandwidth zodat je de realtime-synchronisatie-activiteit over je sites kunt monitoren.

Synchronisatie tussen tabbladen

Als een gebruiker dezelfde pagina in meerdere browsertabbladen geopend heeft, verschijnen updates in het ene tabblad direct in de andere tabbladen. Dit werkt via hetzelfde WebSocket-synchronisatiemechanisme en vereist geen extra configuratie.

Beveiliging

WebSocket-berichten worden verzonden over beveiligde verbindingen (WSS) en bevatten tenant-validatie om ervoor te zorgen dat gebruikers alleen updates ontvangen voor gesprekken waarvoor ze geautoriseerd zijn. De server valideert alle bewerkingen voordat deze naar voren worden uitgezonden om ongeautoriseerde toegang of manipulatie te voorkomen.

API-referentie Internal Link

API-overzicht

Collab Chat biedt drie REST-API-eindpunten voor het programmatisch beheren van tekstgesprekken. Met deze eindpunten kunt u annotaties ophalen, maken en verwijderen zonder de browser-widget te gebruiken.

Dit zijn openbare eindpunten die gebruikers authenticeren via browsercookies. Ze gebruiken geen API-sleutels. Gebruikers moeten in hun browser zijn ingelogd bij FastComments om toegang te krijgen tot deze eindpunten.

Basis-URL

Alle Collab Chat API-eindpunten bevinden zich onder:

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

Authenticatie

Deze eindpunten authenticeren gebruikers via browsercookies. Ze gebruiken geen API-sleutels. Gebruikers moeten in hun browser zijn ingelogd bij FastComments om toegang te krijgen tot deze eindpunten.

Alle gesprekken ophalen

Haal alle tekstgesprekken op voor een specifieke pagina.

Eindpunt

GET-eindpunt
Copy Copy
1
2GET /comment-collab-chats/:tenantId?urlId=<urlId>
3

Parameters

tenantId (padparameter, vereist) is uw FastComments Tenant-ID.

urlId (queryparameter, vereist) is de pagina-identificator waarvan u de gesprekken wilt ophalen.

Respons

De respons bevat de API-status, informatie over de huidige gebruikerssessie als er is geauthenticeerd, een array met gesprekken inclusief hun ID's, URL's en teksbereiken, een opgeschoonde URL-identificator, een vlag die aangeeft of de huidige gebruiker sitebeheerder of moderator is, en WebSocket-verbindinggegevens voor live-synchronisatie waaronder tenantIdWS, urlIdWS en userIdWS.

Voorbeeld GET-aanvraag

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

Voorbeeldrespons

GET-antwoordvoorbeeld
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

Gesprek aanmaken

Maak een nieuw tekstgesprek aan voor een specifieke tekstselectie.

Eindpunt

POST-eindpunt
Copy Copy
1
2POST /comment-collab-chats/:tenantId
3

Parameters

tenantId (padparameter, vereist) is uw FastComments Tenant-ID.

De requestbody moet JSON zijn en de volgende verplichte velden bevatten.

urlId (string, vereist) is de basis-pagina-identificator.

urlIdWithRange (string, vereist) is de URL gecombineerd met het tekstbereik, bijvoorbeeld my-page:p:0:15,0:45{abc123}.

pageTitle (string, vereist) is de titel van de pagina.

selector (string, vereist) is het DOM-pad naar het element dat de geselecteerde tekst bevat.

range (string, vereist) is het geserialiseerde tekstbereik in het formaat startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (string, vereist) is de ID van de opmerking die deze chat heeft gestart.

broadcastId (string, vereist) is een UUID voor live-synchronisatie om echo-effecten te voorkomen.

Respons

De respons bevat de API-status en de ID van het nieuw aangemaakte gesprek.

Voorbeeld POST-aanvraag

POST-aanvraagvoorbeeld
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

Voorbeeldrespons

POST-antwoordvoorbeeld
Copy Copy
1
2{
3 "status": "success",
4 "createdChatId": "conv789"
5}
6

Gesprek verwijderen

Verwijder een bestaand tekstgesprek. Dit eindpunt vereist beheerder- of moderatorrechten, of het gesprek moet zijn aangemaakt door de geauthenticeerde gebruiker.

Eindpunt

DELETE-eindpunt
Copy Copy
1
2DELETE /comment-collab-chats/:tenantId/:chatId
3

Parameters

tenantId (padparameter, vereist) is uw FastComments Tenant-ID.

chatId (padparameter, vereist) is de ID van het gesprek dat u wilt verwijderen.

broadcastId (requestbody, vereist) is een UUID voor live-synchronisatie.

Voorbeeld DELETE-aanvraag

DELETE-aanvraagvoorbeeld
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

Voorbeeldrespons

DELETE-antwoordvoorbeeld
Copy Copy
1
2{
3 "status": "success"
4}
5

Verzoeklimieten

Deze eindpunten vallen onder de standaard FastComments API-verzoeklimieten. De rate-limit middleware wordt per tenant toegepast om misbruik te voorkomen en normale gebruikspatronen toe te staan.

Foutreacties

Alle eindpunten geven standaard HTTP-statuscodes terug. Een 400-respons duidt op ongeldige requestparameters. Een 401-respons betekent dat de authenticatie is mislukt. Een 403-respons geeft aan dat de permissies onvoldoende zijn. Een 404-respons betekent dat het gesprek niet is gevonden. Een 429-respons geeft aan dat de verzoeklimiet is overschreden.

Foutreacties bevatten een JSON-body met details:

Foutantwoordvoorbeeld
Copy Copy
1
2{
3 "status": "error",
4 "message": "Conversation not found"
5}
6

Gebruikstracering

Het aanmaken van gesprekken verhoogt uw gebruiksmetric conversationCreateCount. Alle WebSocket-synchronisatie-activiteit verhoogt pubSubMessageCount en pubSubBandwidth. U kunt deze metrics volgen in uw FastComments-dashboard onder gebruiksanalyses.

Nog vragen?

Dat is alles voor FastComments Collab Chat! Als u vragen heeft, hulp nodig heeft bij de implementatie, of suggesties voor functies heeft, laat het ons dan hieronder weten of neem contact op met ons ondersteuningsteam.

Voor live voorbeelden, bekijk Govscent.org waarin Collab Chat in productie wordt gebruikt.

Bijdragen aan deze gids