FastComments.com

Menu Icon

Lingua 🇮🇹 Italiano
🇺🇸 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

Primi passi

Primi passi
Esempi
Aggiungere commenti in tempo reale ai libri online

Configurazione

Opzioni di configurazione
Comportamento della selezione del testo

Personalizzazione

Personalizzazione

Avanzate

Sincronizzazione in tempo reale
Riferimento API

Aggiungi commenti live inline a documenti, libri, ecc

FastComments Collab Chat consente agli utenti di evidenziare e annotare qualsiasi contenuto testuale sul tuo sito web, creando discussioni thread collegate a selezioni di testo specifiche. Gli utenti possono selezionare parole, frasi o interi paragrafi per avviare conversazioni collaborative direttamente all'interno del tuo contenuto.

Questa funzionalità è perfetta per feedback editoriali, ambienti di lettura collaborativa, piattaforme educative, revisione di documenti e qualsiasi scenario in cui desideri discussioni contestuali ancorate a parti specifiche del testo.

Nota che questa documentazione è specifica per la funzionalità Collab Chat. Puoi aggiungere commenti per contenuti con molte pagine, come Books, con thread-per-page, without using collab chat. FastComments non addebita inoltre per pagina o per thread. Collab Chat è specificamente pensato quando vuoi permettere agli utenti di selezionare il testo e commentare la sezione evidenziata.

Puoi vedere un esempio qui.

Primi passi Internal Link

Avvio rapido

Iniziare con Collab Chat è semplice. Ti serve lo script FastComments Collab Chat, un elemento HTML contenente il testo che vuoi annotare e un oggetto di configurazione con il tuo Tenant ID.

Installazione

Aggiungi lo script Collab Chat alla tua pagina:

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

Implementazione di base

Ecco un esempio minimo:

Implementazione di base di 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 <!-- Contenitore del contenuto -->
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 <!-- Carica lo script Collab Chat -->
16 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
17
18 <!-- Inizializza Collab Chat -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

Sostituisci 'demo' con il tuo effettivo Tenant ID FastComments se non lo hai già, che puoi trovare nel tuo dashboard di FastComments.

Come funziona

Una volta inizializzato, gli utenti possono selezionare qualsiasi testo all'interno dell'elemento target. Dopo un breve ritardo (3,5 secondi su desktop), appare un prompt che permette di avviare una discussione. Quando viene creata una discussione, appare un'evidenziazione visiva sul testo. Altri utenti possono posizionare il cursore sopra o cliccare sull'evidenziazione per visualizzare e partecipare alla discussione. Tutte le discussioni si sincronizzano in tempo reale tra tutti i visitatori.

Demo dal vivo

Puoi vedere Collab Chat in azione nella nostra pagina demo dal vivo.

Prossimi passi

Ora che hai le basi funzionanti, puoi personalizzare l'aspetto e il comportamento nella guida alle opzioni di configurazione. Consulta la guida sul comportamento della selezione del testo per capire come funziona la selezione del testo. Scopri gli stili e il supporto per la modalità scura nella guida alla personalizzazione. Per integrazioni avanzate, esplora il Riferimento API.

Librerie frontend

Tutte le librerie frontend di FastComments (react, vue, angular, ecc.) includono Collab Chat.

Esempi Internal Link

Esempio base

Il modo più semplice per usare Collab Chat è mirare a un singolo contenitore di contenuti. Questo esempio mostra come abilitare le annotazioni di testo su un articolo:

Esempio base di 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

Esempio con ID URL personalizzato (per pagina di un libro, articolo, ecc.)

Per impostazione predefinita, Collab Chat usa l'URL della pagina combinato con il percorso dell'elemento e l'intervallo di testo per identificare le conversazioni. Puoi fornire un urlId personalizzato per avere maggiore controllo su come vengono raggruppate le conversazioni:

Collab Chat con ID URL personalizzato
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

Questo è utile se la struttura dei tuoi URL cambia ma vuoi mantenere le stesse conversazioni, o se vuoi condividere le stesse annotazioni delle conversazioni su più pagine.

Esempio con modalità scura

Se il tuo sito ha uno sfondo scuro, abilita il supporto per la modalità scura per assicurarti che l'interfaccia di chat appaia correttamente:

Collab Chat con modalità scura
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

Esempio con barra superiore disabilitata

Per impostazione predefinita, Collab Chat mostra una barra superiore con il conteggio degli utenti e il conteggio delle discussioni. Puoi disabilitarla:

Collab Chat con barra superiore disabilitata
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

Esempio con callback per il conteggio dei commenti

Puoi monitorare quando i commenti vengono aggiunti o aggiornati usando il callback commentCountUpdated:

Collab Chat con callback per il conteggio dei commenti
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

Esempio con più sezioni

Puoi inizializzare Collab Chat su più sezioni separate della tua pagina. Ogni sezione avrà le proprie annotazioni indipendenti:

Collab Chat su più sezioni
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 // Inizializza la sezione introduttiva
15 FastCommentsCollabChat(document.getElementById('intro-section'), {
16 tenantId: 'demo',
17 urlId: 'my-article-intro'
18 });
19
20 // Inizializza la sezione principale
21 FastCommentsCollabChat(document.getElementById('main-section'), {
22 tenantId: 'demo',
23 urlId: 'my-article-main'
24 });
25</script>
26

Aggiungere commenti in tempo reale ai libri online Internal Link

Puoi inizializzare Collab Chat per pagina se desideri e avere thread separati per pagina, basta passare al parametro urlId un valore come book-one-page1. Questa configurazione funziona anche per il widget normale dei commenti.

Opzioni di configurazione Internal Link

Panoramica

FastComments Collab Chat estende il widget di commenti standard di FastComments, ereditando tutte le opzioni di configurazione del widget base e aggiungendo alcune specifiche per le annotazioni di testo.

Configurazione richiesta

tenantId

È richiesto il tuo Tenant ID di FastComments. Puoi trovarlo nella tua dashboard FastComments.

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

Opzioni specifiche di Collab Chat

urlId

Di default, Collab Chat genera un identificatore univoco per ogni conversazione basato sull'URL della pagina, sul percorso DOM dell'elemento e sull'intervallo di testo selezionato. Puoi sovrascriverlo con un urlId personalizzato.

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

Questo è utile quando la struttura del tuo URL potrebbe cambiare ma vuoi mantenere le stesse conversazioni, o quando vuoi condividere le annotazioni tra più pagine.

topBarTarget

Controlla la visualizzazione della barra superiore che mostra il conteggio utenti e il conteggio delle discussioni. Impostalo su null per disabilitare completamente la barra superiore, oppure fornisci un elemento DOM per renderizzarla in una posizione specifica.

Esempio di configurazione
Copy Copy
1
2// Disabilita la barra superiore
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Mostra la barra superiore in una posizione personalizzata
9FastCommentsCollabChat(element, {
10 tenantId: 'demo',
11 topBarTarget: document.getElementById('custom-header')
12});
13

hasDarkBackground

Abilita lo stile in modalità scura quando la tua pagina ha uno sfondo scuro. Questa rilevazione è automatica, ma potrebbe essere desiderabile sovrascriverla.

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

commentCountUpdated

Una funzione di callback che viene eseguita ogni volta che il conteggio dei commenti cambia. È utile per aggiornare elementi dell'interfaccia utente come badge o il titolo della pagina.

Esempio di configurazione
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

Opzioni di configurazione ereditate

Poiché Collab Chat estende il widget di commenti standard, puoi usare qualsiasi opzione di configurazione del widget base di FastComments. Ecco alcune opzioni comunemente usate:

locale

Imposta la lingua per l'interfaccia del widget. FastComments supporta decine di lingue.

Esempio di configurazione
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Spagnolo
5});
6

readonly

Rendi tutte le conversazioni in sola lettura. Gli utenti possono visualizzare le annotazioni esistenti ma non possono crearne di nuove o rispondere.

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

sso and simpleSSO

Integra con il tuo sistema di autenticazione usando il Single Sign-On.

Esempio di configurazione
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 sso: {
5 // Configurazione SSO
6 }
7});
8

Consulta la documentazione SSO per i dettagli completi sulle opzioni di autenticazione.

maxReplyDepth

Controlla quanti livelli di profondità possono avere le risposte. Di default, Collab Chat imposta questo valore a 0, il che significa che tutti i commenti sono piatti (nessuna risposta annidata). Puoi modificarlo se desideri conversazioni threadate.

Esempio di configurazione
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Consenti 3 livelli di annidamento
5});
6

Configurazione interna

Queste opzioni sono impostate automaticamente da Collab Chat e non dovrebbero essere sovrascritte:

Il productId è impostato automaticamente su 3 per Collab Chat. L'estensione floating-chat viene caricata automaticamente per fornire la funzionalità della finestra di chat. Il widget rileva automaticamente i dispositivi mobili (schermi con larghezza inferiore a 768px) e adatta l'interfaccia di conseguenza.

Esempio completo

Ecco un esempio che mostra più opzioni di configurazione insieme:

Esempio di configurazione
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 // La tua configurazione SSO
13 },
14 maxReplyDepth: 1
15});
16

Per un elenco completo di tutte le opzioni di configurazione disponibili ereditate dal widget base, consulta la documentazione principale di configurazione di FastComments.

Comportamento della selezione del testo Internal Link

Come funziona la selezione del testo

Quando gli utenti selezionano del testo all'interno del contenitore Collab Chat, il widget cattura quella selezione e permette loro di avviare una discussione. La selezione può essere tanto piccola quanto una singola parola o tanto estesa quanto più paragrafi che attraversano elementi diversi.

Ritardo nella selezione

Su dispositivi desktop, c'è un ritardo di 3,5 secondi tra il momento in cui un utente seleziona del testo e il momento in cui appare l'invito alla discussione. Questo evita che l'interfaccia utente si sfarfalli quando gli utenti stanno semplicemente evidenziando del testo per copiarlo o leggerlo. Su dispositivi mobili, l'invito appare immediatamente poiché la selezione del testo è più deliberata sui touchscreen.

ID conversazione unici

Ogni conversazione ottiene un urlId unico che combina l'URL della pagina, il percorso dell'elemento DOM e l'intervallo di testo serializzato. Questo assicura che ogni selezione di testo crei una conversazione distinta che può essere ritrovata in seguito.

Se fornisci un urlId personalizzato nella tua configurazione, verrà combinato con il percorso dell'elemento e l'intervallo di testo per creare l'identificatore finale.

Evidenziazioni visive

Quando esiste una discussione per una particolare selezione di testo, quel testo riceve un'evidenziazione visiva. L'evidenziazione è implementata usando colori di sfondo e compare al passaggio del mouse o quando la finestra di chat associata è aperta.

Il sistema di evidenziazione funziona avvolgendo il testo selezionato in un elemento speciale che può essere stilizzato. Questo approccio assicura che le evidenziazioni rimangano accurate anche quando la struttura HTML sottostante è complessa.

Posizionamento della finestra di chat

Quando un utente clicca su un'evidenziazione o crea una nuova annotazione, una finestra di chat appare vicino al testo selezionato. Il widget calcola automaticamente la posizione migliore per questa finestra in base allo spazio disponibile nella viewport.

Il sistema di posizionamento usa classi CSS come to-right, to-left, to-top e to-bottom per indicare in quale direzione la finestra di chat dovrebbe estendersi dall'evidenziazione. Su dispositivi mobili (schermi con larghezza inferiore a 768px), la finestra di chat appare sempre a schermo intero per una migliore usabilità.

Dimensioni della finestra di chat

Le finestre di chat hanno larghezza di 410px su desktop con uno spazio di 20px e una freccia visiva di 16px che punta al testo evidenziato. Queste dimensioni sono fisse per garantire un comportamento coerente, ma è possibile personalizzare l'aspetto tramite CSS.

Selezioni attraverso gli elementi

Gli utenti possono selezionare del testo che attraversa più elementi HTML, ad esempio evidenziando dal mezzo di un paragrafo fino all'inizio di un altro. Il sistema di serializzazione dell'intervallo gestisce correttamente questi casi e evidenzierà tutto il testo selezionato anche attraverso i confini degli elementi.

Compatibilità del browser

Il sistema di selezione del testo utilizza l'API standard window.getSelection() che è supportata in tutti i browser moderni. Per le versioni più vecchie di Internet Explorer, ricorre a document.selection per compatibilità.

Persistenza della selezione

Una volta che una conversazione è stata creata per una selezione di testo, quell'annotazione persiste anche se la pagina viene ricaricata. L'intervallo serializzato e il percorso DOM permettono al widget di ripristinare le evidenziazioni esattamente nello stesso punto quando gli utenti ritornano sulla pagina.

Questo funziona in modo affidabile finché il contenuto della tua pagina rimane stabile. Se modifichi il contenuto testuale o ristrutturi l'HTML, le annotazioni esistenti potrebbero non allinearsi più correttamente con il testo. Per questo motivo, è meglio evitare cambiamenti importanti del contenuto sulle pagine con annotazioni attive, o considerare la migrazione delle annotazioni quando i cambiamenti di contenuto sono necessari.

Personalizzazione Internal Link

Supporto della Modalità Scura

Modalità scura dinamica

Se la modalità scura del tuo sito è controllata aggiungendo una classe .dark all'elemento body, l'interfaccia di Collab Chat la rispetterà automaticamente senza richiedere una reinizializzazione. Gli stili del widget sono progettati per rispondere alla presenza di questa classe.

Esempio CSS per la modalità scura
Copy Copy
1
2/* Il tuo CSS per la modalità scura */
3body.dark {
4 background: #1a1a1a;
5 color: #ffffff;
6}
7

Stilizzazione personalizzata con CSS

Puoi personalizzare l'aspetto degli evidenziamenti, delle finestre di chat e di altri elementi usando il CSS. Il widget aggiunge classi specifiche che puoi mirare nel tuo stylesheet.

Gli evidenziamenti di testo utilizzano il sistema di styling dei commenti a fumetto di FastComments, quindi qualsiasi personalizzazione applicata al widget di commenti standard influenzerà anche Collab Chat.

Personalizzazione della barra superiore

La barra superiore mostra il numero di utenti online e il numero di discussioni. Puoi personalizzarne la posizione fornendo un elemento personalizzato come topBarTarget:

Posizione personalizzata della barra superiore
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: document.getElementById('my-custom-header')
5});
6

Oppure disabilitarla completamente impostandola su null:

Disabilitare la barra superiore
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: null
5});
6

Comportamento mobile

Su schermi con larghezza inferiore a 768px, Collab Chat passa automaticamente a un layout ottimizzato per mobile. Le finestre di chat appaiono a schermo intero invece di fluttuare accanto al testo e il ritardo di selezione viene rimosso per un'interazione più immediata.

Questo comportamento è integrato e non richiede alcuna configurazione. Il widget rileva automaticamente la dimensione dello schermo e si adatta di conseguenza.

Aspetto della finestra di chat

Le finestre di chat sono larghe 410px su desktop con una freccia di 16px che punta al testo evidenziato. Le finestre si posizionano automaticamente in base allo spazio disponibile nella viewport, usando classi di posizionamento come to-right, to-left, to-top e to-bottom.

Puoi aggiungere CSS personalizzato per regolare colori, font, spaziatura o altre proprietà visive di queste finestre. Le finestre di chat utilizzano la stessa struttura dei componenti del widget FastComments standard, quindi ereditano qualsiasi personalizzazione globale che hai applicato.

Localizzazione

Collab Chat supporta le stesse opzioni di localizzazione del widget FastComments standard. Imposta l'opzione locale per visualizzare il testo dell'interfaccia in lingue diverse:

Impostare la localizzazione
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Spagnolo
5});
6

FastComments supporta dozzine di lingue. L'impostazione del locale influisce su tutto il testo dell'interfaccia, inclusi prompt, pulsanti e testi dei placeholder.

Opzioni di personalizzazione ereditate

Poiché Collab Chat estende il widget di commenti standard, eredita tutte le opzioni di personalizzazione dal widget base. Questo include classi CSS personalizzate, traduzioni personalizzate, personalizzazione degli avatar, formattazione delle date e molto altro.

Consulta la documentazione principale di personalizzazione di FastComments per l'elenco completo delle opzioni di personalizzazione disponibili.

Lavorare con font personalizzati

Se il tuo sito utilizza font personalizzati, l'interfaccia di Collab Chat erediterà quei font dal CSS della tua pagina. Potrebbe essere necessario creare una regola di personalizzazione del widget e @import qualsiasi font nel CSS personalizzato in quella regola se vuoi che la finestra di chat fluttuante utilizzi gli stessi font.

Sincronizzazione in tempo reale Internal Link

Real-Time Updates

Collab Chat utilizza connessioni WebSocket per sincronizzare tutte le conversazioni in tempo reale tra tutti gli utenti connessi. Quando qualcuno crea una nuova annotazione, aggiunge un commento o elimina una discussione, tutti gli altri utenti che visualizzano la stessa pagina vedono l'aggiornamento immediatamente senza dover aggiornare la pagina.

How WebSocket Sync Works

Quando si inizializza Collab Chat, il widget stabilisce una connessione WebSocket con i server FastComments. Questa connessione rimane aperta per tutta la durata della sessione dell'utente e ascolta gli aggiornamenti relativi alla pagina corrente.

Il sistema WebSocket utilizza tre tipi di messaggi broadcast per Collab Chat. L'evento new-text-chat viene attivato quando qualcuno crea una nuova annotazione sulla pagina. L'evento updated-text-chat viene attivato quando qualcuno aggiorna una conversazione esistente. L'evento deleted-text-chat viene attivato quando qualcuno elimina un'annotazione.

Broadcast ID System

Per evitare effetti di eco in cui gli utenti vedono le proprie azioni trasmesse nuovamente, ogni aggiornamento include un broadcastId univoco. Quando un utente crea o aggiorna un'annotazione, il suo client genera un UUID per quell'operazione. Quando il WebSocket trasmette l'aggiornamento a tutti i client, il client di origine ignora l'aggiornamento perché corrisponde al proprio broadcastId.

Questo garantisce un'interazione fluida in cui gli utenti vedono immediatamente le proprie modifiche nell'interfaccia senza dover attendere il giro di andata e ritorno attraverso il server, pur assicurando che tutti gli altri utenti ricevano l'aggiornamento.

Live User Count

La barra superiore mostra il numero di utenti che stanno attualmente visualizzando la pagina. Questo conteggio si aggiorna in tempo reale man mano che gli utenti entrano e escono. Il conteggio degli utenti è fornito tramite la stessa connessione WebSocket e aumenta/diminuisce automaticamente in base agli eventi di connessione e disconnessione.

Connection Resilience

Se la connessione WebSocket si interrompe a causa di problemi di rete o manutenzione del server, il widget tenta automaticamente di riconnettersi. Durante il periodo di riconnessione, gli utenti possono ancora interagire con le annotazioni esistenti, ma non vedranno aggiornamenti in tempo reale dagli altri utenti fino a quando la connessione non sarà ristabilita.

Una volta riconnesso, il widget si risincronizza per assicurarsi che non siano stati persi aggiornamenti. Questo avviene in modo trasparente senza richiedere interventi da parte dell'utente.

Bandwidth Considerations

I messaggi WebSocket sono leggeri e contengono solo le informazioni essenziali necessarie per sincronizzare lo stato. La creazione di una nuova annotazione utilizza tipicamente meno di 1KB di larghezza di banda. Il sistema include anche un batching intelligente per ridurre la frequenza dei messaggi durante i periodi di alta attività.

Le tue metriche d'uso nella dashboard FastComments tracciano pubSubMessageCount e pubSubBandwidth in modo da poter monitorare l'attività di sincronizzazione in tempo reale sui tuoi siti.

Cross-Tab Synchronization

Se un utente ha la stessa pagina aperta in più schede del browser, gli aggiornamenti in una scheda appaiono immediatamente nelle altre schede. Questo funziona tramite lo stesso meccanismo di sincronizzazione WebSocket e non richiede alcuna configurazione aggiuntiva.

Security

I messaggi WebSocket vengono trasmessi su connessioni sicure (WSS) e includono la validazione del tenant per assicurare che gli utenti ricevano solo gli aggiornamenti delle conversazioni che sono autorizzati a visualizzare. Il server valida tutte le operazioni prima di trasmetterle per prevenire accessi o manipolazioni non autorizzate.

Riferimento API Internal Link

Panoramica API

Collab Chat fornisce tre endpoint REST API per gestire conversazioni testuali programmaticamente. Questi endpoint consentono di recuperare, creare ed eliminare annotazioni senza utilizzare il widget del browser.

Si tratta di endpoint pubblici che autenticano gli utenti tramite cookie del browser. Non utilizzano chiavi API. Gli utenti devono essere autenticati in FastComments nel loro browser per accedere a questi endpoint.

URL base

Tutti gli endpoint API di Collab Chat sono sotto:

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

Autenticazione

Questi endpoint autenticano gli utenti tramite cookie del browser. Non utilizzano chiavi API. Gli utenti devono essere autenticati in FastComments nel loro browser per accedere a questi endpoint.

Recupera tutte le conversazioni

Recupera tutte le conversazioni testuali per una pagina specifica.

Endpoint

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

Parametri

tenantId (parametro del percorso, obbligatorio) è il tuo FastComments Tenant ID.

urlId (parametro di query, obbligatorio) è l'identificatore della pagina per cui vuoi recuperare le conversazioni.

Risposta

La risposta include lo stato API, le informazioni sulla sessione dell'utente corrente se autenticato, un array di conversazioni con i loro ID, URL e intervalli di testo, un identificatore URL pulito, un flag che indica se l'utente corrente è amministratore del sito o moderatore, e i dettagli di connessione WebSocket per la sincronizzazione in tempo reale inclusi tenantIdWS, urlIdWS, e userIdWS.

Esempio di richiesta

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

Esempio di risposta

Esempio di risposta 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

Crea conversazione

Crea una nuova conversazione testuale per una selezione di testo specifica.

Endpoint

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

Parametri

tenantId (parametro del percorso, obbligatorio) è il tuo FastComments Tenant ID.

Il corpo della richiesta deve essere JSON e includere questi campi obbligatori.

urlId (stringa, obbligatorio) è l'identificatore base della pagina.

urlIdWithRange (stringa, obbligatorio) è l'URL combinato con l'intervallo di testo, per esempio my-page:p:0:15,0:45{abc123}.

pageTitle (stringa, obbligatorio) è il titolo della pagina.

selector (stringa, obbligatorio) è il percorso DOM all'elemento che contiene il testo selezionato.

range (stringa, obbligatorio) è l'intervallo di testo serializzato nel formato startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (stringa, obbligatorio) è l'ID del commento che ha avviato questa chat.

broadcastId (stringa, obbligatorio) è un UUID per la sincronizzazione in tempo reale per prevenire effetti di eco.

Risposta

La risposta include lo stato API e l'ID della conversazione appena creata.

Esempio di richiesta

Esempio di richiesta 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

Esempio di risposta

Esempio di risposta POST
Copy Copy
1
2{
3 "status": "success",
4 "createdChatId": "conv789"
5}
6

Elimina conversazione

Elimina una conversazione testuale esistente. Questo endpoint richiede permessi di amministratore o moderatore, oppure la conversazione deve essere stata creata dall'utente autenticato.

Endpoint

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

Parametri

tenantId (parametro del percorso, obbligatorio) è il tuo FastComments Tenant ID.

chatId (parametro del percorso, obbligatorio) è l'ID della conversazione da eliminare.

broadcastId (corpo della richiesta, obbligatorio) è un UUID per la sincronizzazione in tempo reale.

Esempio di richiesta

Esempio di richiesta 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

Esempio di risposta

Esempio di risposta DELETE
Copy Copy
1
2{
3 "status": "success"
4}
5

Limitazione delle richieste

Questi endpoint sono soggetti alla limitazione delle richieste standard di FastComments. Il middleware di limitazione del rate si applica per tenant per prevenire abusi consentendo al contempo modelli di utilizzo normali.

Risposte di errore

Tutti gli endpoint restituiscono codici di stato HTTP standard. Una risposta 400 indica parametri di richiesta non validi. Una 401 significa che l'autenticazione è fallita. Una 403 indica permessi insufficienti. Una 404 significa che la conversazione non è stata trovata. Una 429 indica che è stato superato il limite di richieste.

Le risposte di errore includono un corpo JSON con i dettagli:

Esempio di risposta di errore
Copy Copy
1
2{
3 "status": "error",
4 "message": "Conversation not found"
5}
6

Monitoraggio dell'utilizzo

La creazione delle conversazioni incrementa la metrica di utilizzo conversationCreateCount. Tutta l'attività di sincronizzazione WebSocket incrementa pubSubMessageCount e pubSubBandwidth. Puoi monitorare queste metriche nella dashboard di FastComments nella sezione analytics sull'utilizzo.

Hai domande?

Questo è tutto per FastComments Collab Chat! Se hai domande, hai bisogno di aiuto con l'implementazione o hai suggerimenti per funzionalità, faccelo sapere qui sotto o contatta il nostro team di supporto.

Per esempi dal vivo, consulta Govscent.org che utilizza Collab Chat in produzione.

Contribuisci a questa guida