FastComments.com

Menu Icon

Idioma 🇪🇸 Español
🇺🇸 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

Primeros pasos

Primeros pasos
Ejemplos
Agregar comentarios en vivo a libros en línea

Configuración

Opciones de configuración
Comportamiento de selección de texto

Personalización

Personalización

Avanzado

Sincronización en vivo
Referencia de la API

Añadir comentarios en vivo integrados a documentos, libros, etc

FastComments Collab Chat permite a los usuarios resaltar y anotar cualquier contenido de texto en su sitio web, creando discusiones en hilos vinculadas a selecciones de texto específicas. Los usuarios pueden seleccionar palabras, frases o párrafos enteros para iniciar conversaciones colaborativas directamente dentro de su contenido.

Esta función es perfecta para retroalimentación editorial, entornos de lectura colaborativa, plataformas educativas, revisión de documentos y cualquier escenario en el que desee discusiones contextuales ancladas a texto específico.

Tenga en cuenta que esta documentación es específica de la funcionalidad Collab Chat. Puede añadir comentarios para contenido con muchas páginas, como libros, con thread-per-page, sin usar collab chat. FastComments tampoco cobra por página ni por hilo. Collab Chat es específicamente cuando usted quiere permitir que los usuarios seleccionen texto y comenten la sección de texto resaltada.

You can see an example here.

Primeros pasos Internal Link

Inicio rápido

Comenzar con Collab Chat es sencillo. Necesitas el script de FastComments Collab Chat, un elemento HTML que contenga el texto que deseas anotar y un objeto de configuración con tu Tenant ID.

Instalación

Añade el script de Collab Chat a tu página:

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

Implementación básica

Aquí tienes un ejemplo mínimo:

Implementación básica de 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 <!-- Contenedor de contenido -->
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 <!-- Cargar el script de Collab Chat -->
16 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
17
18 <!-- Inicializar Collab Chat -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

Replace 'demo' with your actual FastComments Tenant ID if it's not already, which you can find in your FastComments dashboard.

Cómo funciona

Una vez inicializado, los usuarios pueden seleccionar cualquier texto dentro del elemento objetivo. Tras una breve demora (3,5 segundos en escritorio), aparece un aviso que les permite iniciar una discusión. Cuando se crea una discusión, aparece un resaltado visual en el texto. Otros usuarios pueden pasar el cursor o hacer clic en el resaltado para ver y participar en la discusión. Todas las discusiones se sincronizan en tiempo real entre todos los visitantes.

Demostración en vivo

Puedes ver Collab Chat en acción en nuestra página de demostración en vivo.

Siguientes pasos

Ahora que tienes lo básico funcionando, puedes personalizar la apariencia y el comportamiento en la guía de Opciones de Configuración. Consulta la guía de Comportamiento de Selección de Texto para entender cómo funciona la selección de texto. Aprende sobre estilos y soporte de modo oscuro en la guía de Personalización. Para integraciones avanzadas, explora la Referencia de la API.

Bibliotecas frontend

Todas las bibliotecas frontend de FastComments (react, vue, angular, etc) incluyen Collab Chat.

Ejemplos Internal Link

Ejemplo básico

La forma más sencilla de usar Collab Chat es apuntar a un único contenedor de contenido. Este ejemplo muestra cómo habilitar anotaciones de texto en un artículo:

Ejemplo básico de 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

Ejemplo con ID de URL personalizado (por página de libro, artículo, etc.)

Por defecto, Collab Chat usa la URL de la página combinada con la ruta del elemento y el rango de texto para identificar conversaciones. Puedes proporcionar un urlId personalizado para tener más control sobre cómo se agrupan las conversaciones:

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

Esto es útil si la estructura de tus URL cambia pero quieres mantener las mismas conversaciones, o si deseas compartir las mismas anotaciones de conversación en varias páginas.

Ejemplo con modo oscuro

Si tu sitio tiene un fondo oscuro, activa el soporte de modo oscuro para asegurar que la interfaz de chat se vea correctamente:

Collab Chat con modo oscuro
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

Ejemplo con barra superior desactivada

Por defecto, Collab Chat muestra una barra superior con el conteo de usuarios y el conteo de discusiones. Puedes desactivarla:

Collab Chat con barra superior desactivada
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

Ejemplo con callback de recuento de comentarios

Puedes rastrear cuando se agregan o actualizan comentarios usando el callback commentCountUpdated:

Collab Chat con callback de recuento de comentarios
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

Ejemplo con múltiples secciones

Puedes inicializar Collab Chat en múltiples secciones separadas de tu página. Cada sección tendrá sus propias anotaciones independientes:

Collab Chat en múltiples secciones
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 // Inicializar en la sección de introducción
15 FastCommentsCollabChat(document.getElementById('intro-section'), {
16 tenantId: 'demo',
17 urlId: 'my-article-intro'
18 });
19
20 // Inicializar en la sección principal
21 FastCommentsCollabChat(document.getElementById('main-section'), {
22 tenantId: 'demo',
23 urlId: 'my-article-main'
24 });
25</script>
26

Agregar comentarios en vivo a libros en línea Internal Link

Puedes inicializar Collab Chat por página si lo deseas, y tener hilos separados por página; simplemente pasa el parámetro urlId un valor como book-one-page1. Esta configuración también funciona para el widget de comentarios normal.

Opciones de configuración Internal Link

Descripción general

FastComments Collab Chat amplía el widget de comentarios estándar de FastComments, por lo que hereda todas las opciones de configuración del widget base y añade algunas específicas para anotaciones de texto.

Configuración requerida

tenantId

Se requiere su ID de inquilino (Tenant ID) de FastComments. Puede encontrarlo en su panel de FastComments.

Ejemplo de configuración
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo'
4});
5

Opciones específicas de Collab Chat

urlId

Por defecto, Collab Chat genera un identificador único para cada conversación basado en la URL de la página, la ruta DOM al elemento y el rango de texto seleccionado. Puede sobrescribir esto con un urlId personalizado.

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

Esto es útil cuando la estructura de sus URL puede cambiar pero quiere mantener las mismas conversaciones, o cuando desea compartir anotaciones entre varias páginas.

topBarTarget

Controla la visualización de la barra superior que muestra el recuento de usuarios y el recuento de discusiones. Establézcalo en null para desactivar la barra superior por completo, o proporcione un elemento DOM para renderizarla en una ubicación específica.

Ejemplo de configuración
Copy Copy
1
2// Desactivar la barra superior
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Mostrar la barra superior en una ubicación personalizada
9FastCommentsCollabChat(element, {
10 tenantId: 'demo',
11 topBarTarget: document.getElementById('custom-header')
12});
13

hasDarkBackground

Habilite el estilo de modo oscuro cuando su página tenga un fondo oscuro. Esta detección es automática, pero puede ser deseable sobrescribirla.

Ejemplo de configuración
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 hasDarkBackground: true
5});
6

commentCountUpdated

Una función de callback que se dispara cada vez que cambia el recuento de comentarios. Esto es útil para actualizar elementos de la UI como insignias o títulos de página.

Ejemplo de configuración
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

Opciones de configuración heredadas

Dado que Collab Chat extiende el widget de comentarios estándar, puede usar cualquier opción de configuración del widget base de FastComments. Aquí hay algunas opciones comúnmente utilizadas:

locale

Establece el idioma para la interfaz del widget. FastComments admite docenas de idiomas.

Ejemplo de configuración
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Español
5});
6

readonly

Haga que todas las conversaciones sean de solo lectura. Los usuarios pueden ver las anotaciones existentes pero no pueden crear nuevas ni responder.

Ejemplo de configuración
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 readonly: true
5});
6

sso and simpleSSO

Integre con su sistema de autenticación usando Single Sign-On.

Ejemplo de configuración
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 sso: {
5 // Configuración de SSO
6 }
7});
8

Consulte la documentación de SSO para obtener detalles completos sobre las opciones de autenticación.

maxReplyDepth

Controle cuántos niveles de profundidad pueden tener las respuestas. Por defecto, Collab Chat establece esto en 0, lo que significa que todos los comentarios son planos (sin respuestas anidadas). Puede cambiar esto si desea conversaciones en hilos.

Ejemplo de configuración
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Permitir 3 niveles de anidamiento
5});
6

Configuración interna

Estas opciones son establecidas automáticamente por Collab Chat y no deben ser sobrescritas:

El productId se establece automáticamente en 3 para Collab Chat. La extensión floating-chat se carga automáticamente para proporcionar la funcionalidad de la ventana de chat. El widget detecta automáticamente dispositivos móviles (pantallas de menos de 768px de ancho) y ajusta la interfaz en consecuencia.

Ejemplo completo

Aquí hay un ejemplo que muestra múltiples opciones de configuración juntas:

Ejemplo de configuración
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 // Tu configuración de SSO
13 },
14 maxReplyDepth: 1
15});
16

Para una lista completa de todas las opciones de configuración disponibles heredadas del widget base, consulte la documentación principal de configuración de FastComments.

Comportamiento de selección de texto Internal Link

Cómo funciona la selección de texto

Cuando los usuarios seleccionan texto dentro del contenedor Collab Chat, el widget captura esa selección y les permite iniciar una discusión. La selección puede ser tan pequeña como una sola palabra o tan grande como varios párrafos que abarcan diferentes elementos.

Retardo de selección

En dispositivos de escritorio, hay un retraso de 3,5 segundos entre el momento en que un usuario selecciona texto y el momento en que aparece el aviso de discusión. Esto evita que la interfaz parpadee cuando los usuarios simplemente están resaltando texto para copiar o leer. En dispositivos móviles, el aviso aparece de inmediato ya que la selección de texto es más deliberada en pantallas táctiles.

IDs de conversación únicos

Cada conversación recibe un urlId único que combina la URL de la página, la ruta del elemento del DOM y el rango de texto serializado. Esto asegura que cada selección de texto cree una conversación distinta que se pueda encontrar más tarde.

Si proporciona un urlId personalizado en su configuración, se combinará con la ruta del elemento y el rango de texto para crear el identificador final.

Resaltados visuales

Cuando existe una discusión para una selección de texto determinada, ese texto recibe un resaltado visual. El resaltado se implementa mediante colores de fondo y aparece al pasar el cursor o cuando la ventana de chat asociada está abierta.

El sistema de resaltado funciona envolviendo el texto seleccionado en un elemento especial que puede ser estilizado. Este enfoque garantiza que los resaltados sigan siendo precisos incluso cuando la estructura HTML subyacente es compleja.

Posicionamiento de la ventana de chat

Cuando un usuario hace clic en un resaltado o crea una nueva anotación, aparece una ventana de chat cerca del texto seleccionado. El widget calcula automáticamente la mejor posición para esta ventana en función del espacio disponible en la ventana gráfica.

El sistema de posicionamiento utiliza clases CSS como to-right, to-left, to-top y to-bottom para indicar en qué dirección debe extenderse la ventana de chat desde el resaltado. En dispositivos móviles (pantallas de menos de 768px de ancho), la ventana de chat siempre aparece en pantalla completa para una mejor usabilidad.

Dimensiones de la ventana de chat

Las ventanas de chat tienen 410px de ancho en escritorio con 20px de separación y una flecha visual de 16px que apunta al texto resaltado. Estas dimensiones son fijas para asegurar un comportamiento coherente, pero puede personalizar la apariencia con CSS.

Selecciones entre elementos

Los usuarios pueden seleccionar texto que abarca múltiples elementos HTML, como resaltar desde la mitad de un párrafo hasta el inicio de otro. El sistema de serialización de rangos maneja esto correctamente y resaltará todo el texto seleccionado incluso a través de los límites de los elementos.

Compatibilidad con navegadores

El sistema de selección de texto utiliza la API estándar window.getSelection() que es compatible con todos los navegadores modernos. Para versiones antiguas de Internet Explorer, recurre a document.selection para compatibilidad.

Persistencia de la selección

Una vez que se crea una conversación para una selección de texto, esa anotación persiste incluso si se recarga la página. El rango serializado y la ruta del DOM permiten que el widget restaure los resaltados en la misma ubicación exacta cuando los usuarios regresen a la página.

Esto funciona de manera fiable siempre que el contenido de su página permanezca estable. Si cambia el contenido de texto o reestructura su HTML, las anotaciones existentes pueden dejar de alinearse correctamente con el texto. Por esta razón, es mejor evitar cambios importantes en el contenido de las páginas con anotaciones activas, o considerar migrar las anotaciones cuando sean necesarios cambios en el contenido.

Personalización Internal Link

Soporte de Modo Oscuro

Modo Oscuro Dinámico

Si el modo oscuro de tu sitio se controla agregando una clase .dark al elemento body, la interfaz de Collab Chat respetará esto automáticamente sin requerir reinitialización. Los estilos del widget están diseñados para responder a la presencia de esta clase.

Ejemplo de CSS de modo oscuro
Copy Copy
1
2/* Tu CSS de modo oscuro */
3body.dark {
4 background: #1a1a1a;
5 color: #ffffff;
6}
7

Estilizado personalizado con CSS

Puedes personalizar la apariencia de los resaltados, las ventanas de chat y otros elementos usando CSS. El widget añade clases específicas a las que puedes dirigirte en tu hoja de estilos.

Los resaltados de texto usan el sistema de estilo de burbujas de comentario de FastComments, por lo que cualquier personalización que hayas aplicado al widget de comentarios estándar también afectará a Collab Chat.

Personalización de la barra superior

La barra superior muestra el número de usuarios en línea y el número de discusiones. Puedes personalizar su posición proporcionando un elemento personalizado como topBarTarget:

Ubicación personalizada de la barra superior
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: document.getElementById('my-custom-header')
5});
6

O desactívala por completo estableciéndola en null:

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

Comportamiento móvil

En pantallas de menos de 768px de ancho, Collab Chat cambia automáticamente a una disposición optimizada para móvil. Las ventanas de chat aparecen a pantalla completa en lugar de flotar junto al texto, y se elimina el retraso de selección para una interacción más inmediata.

Este comportamiento está integrado y no requiere ninguna configuración. El widget detecta el tamaño de la pantalla automáticamente y se ajusta en consecuencia.

Apariencia de la ventana de chat

Las ventanas de chat tienen 410px de ancho en escritorio con una flecha de 16px apuntando al texto resaltado. Las ventanas se posicionan automáticamente según el espacio disponible en la ventana gráfica, usando clases de posicionamiento como to-right, to-left, to-top, y to-bottom.

Puedes añadir CSS personalizado para ajustar colores, fuentes, espaciado u otras propiedades visuales de estas ventanas. Las ventanas de chat usan la misma estructura de componentes que el widget estándar de FastComments, por lo que heredan cualquier personalización global que hayas aplicado.

Localización

Collab Chat admite todas las mismas opciones de localización que el widget estándar de FastComments. Establece la opción locale para mostrar el texto de la interfaz en diferentes idiomas:

Establecer locale
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Español
5});
6

FastComments admite docenas de idiomas. La configuración de locale afecta todo el texto de la interfaz, incluidos los mensajes, botones y texto de marcador de posición.

Opciones de personalización heredadas

Como Collab Chat extiende el widget de comentarios estándar, hereda todas las opciones de personalización del widget base. Esto incluye clases CSS personalizadas, traducciones personalizadas, personalización de avatar, formato de fechas y mucho más.

Consulta la documentación principal de personalización de FastComments para la lista completa de opciones de personalización disponibles.

Trabajar con fuentes personalizadas

Si tu sitio usa fuentes personalizadas, la interfaz de Collab Chat heredará esas fuentes desde el CSS de tu página. Es posible que tengas que crear una regla de personalización de widget e @import cualquier fuente en el CSS personalizado dentro de esa regla si deseas que la ventana de chat flotante use las mismas fuentes.

Sincronización en vivo Internal Link

Actualizaciones en tiempo real

Collab Chat utiliza conexiones WebSocket para sincronizar todas las conversaciones en tiempo real entre todos los usuarios conectados. Cuando alguien crea una nueva anotación, añade un comentario o elimina una discusión, todos los demás usuarios que estén viendo la misma página ven la actualización de inmediato sin necesidad de recargar.

Cómo funciona la sincronización por WebSocket

Cuando inicializas Collab Chat, el widget establece una conexión WebSocket con los servidores de FastComments. Esta conexión permanece abierta durante la sesión del usuario y escucha actualizaciones relacionadas con la página actual.

El sistema WebSocket utiliza tres tipos de mensajes de difusión para Collab Chat. El evento new-text-chat se activa cuando alguien crea una nueva anotación en la página. El evento updated-text-chat se activa cuando alguien actualiza una conversación existente. El evento deleted-text-chat se activa cuando alguien elimina una anotación.

Sistema de ID de difusión

Para evitar efectos de eco en los que los usuarios ven sus propias acciones retransmitidas de vuelta, cada actualización incluye un broadcastId único. Cuando un usuario crea o actualiza una anotación, su cliente genera un UUID para esa operación. Cuando el WebSocket retransmite la actualización a todos los clientes, el cliente de origen ignora la actualización porque coincide con su propio broadcastId.

Esto garantiza una interacción fluida en la que los usuarios ven sus cambios de inmediato en la interfaz sin esperar el viaje de ida y vuelta al servidor, al mismo tiempo que asegura que todos los demás usuarios reciban la actualización.

Conteo de usuarios en vivo

La barra superior muestra el número de usuarios que actualmente están viendo la página. Este conteo se actualiza en tiempo real a medida que los usuarios se unen y abandonan. El recuento de usuarios se proporciona a través de la misma conexión WebSocket y se incrementa/decrementa automáticamente en función de los eventos de conexión y desconexión.

Resiliencia de la conexión

Si la conexión WebSocket se cae debido a problemas de red o mantenimiento del servidor, el widget intenta reconectarse automáticamente. Durante el período de reconexión, los usuarios aún pueden interactuar con las anotaciones existentes, pero no verán actualizaciones en tiempo real de otros usuarios hasta que la conexión se restablezca.

Una vez reconectado, el widget se resincroniza para asegurarse de que no se hayan perdido actualizaciones. Esto sucede de forma transparente sin requerir intervención del usuario.

Consideraciones de ancho de banda

Los mensajes WebSocket son ligeros y contienen solo la información esencial necesaria para sincronizar el estado. Crear una nueva anotación normalmente usa menos de 1 KB de ancho de banda. El sistema también incluye agrupamiento inteligente para reducir la frecuencia de mensajes durante períodos de alta actividad.

Tus métricas de uso en el panel de FastComments rastrean pubSubMessageCount y pubSubBandwidth para que puedas supervisar la actividad de sincronización en tiempo real en tus sitios.

Sincronización entre pestañas

Si un usuario tiene la misma página abierta en varias pestañas del navegador, las actualizaciones en una pestaña aparecen inmediatamente en las otras pestañas. Esto funciona mediante el mismo mecanismo de sincronización WebSocket y no requiere ninguna configuración adicional.

Seguridad

Los mensajes WebSocket se transmiten a través de conexiones seguras (WSS) e incluyen validación del tenant para garantizar que los usuarios solo reciban actualizaciones de las conversaciones que están autorizados a ver. El servidor valida todas las operaciones antes de difundirlas para evitar acceso no autorizado o manipulación.

Referencia de la API Internal Link

Descripción general de la API

Collab Chat proporciona tres endpoints REST API para gestionar conversaciones de texto de forma programática. Estos endpoints le permiten recuperar, crear y eliminar anotaciones sin usar el widget del navegador.

Estos son endpoints públicos que autentican a los usuarios mediante cookies del navegador. No utilizan claves de API. Los usuarios deben haber iniciado sesión en FastComments en su navegador para acceder a estos endpoints.

URL base

Todos los endpoints de la API de Collab Chat se encuentran en:

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

Autenticación

Estos endpoints autentican a los usuarios mediante cookies del navegador. No utilizan claves de API. Los usuarios deben haber iniciado sesión en FastComments en su navegador para acceder a estos endpoints.

Obtener todas las conversaciones

Recupera todas las conversaciones de texto para una página específica.

Punto final

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

Parámetros

tenantId (parámetro de ruta, requerido) es su Tenant ID de FastComments.

urlId (parámetro de consulta, requerido) es el identificador de la página para la que desea recuperar las conversaciones.

Respuesta

La respuesta incluye el estado de la API, la información de la sesión del usuario actual si está autenticado, un array de conversaciones con sus IDs, URLs y rangos de texto, un identificador de URL limpiado, una bandera que indica si el usuario actual es administrador del sitio o moderador, y detalles de conexión WebSocket para la sincronización en vivo incluyendo tenantIdWS, urlIdWS, y userIdWS.

Ejemplo de solicitud

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

Ejemplo de respuesta

Ejemplo de respuesta 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

Crear conversación

Crea una nueva conversación de texto para una selección de texto específica.

Punto final

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

Parámetros

tenantId (parámetro de ruta, requerido) es su Tenant ID de FastComments.

El cuerpo de la solicitud debe ser JSON e incluir estos campos obligatorios.

urlId (string, requerido) es el identificador base de la página.

urlIdWithRange (string, requerido) es la URL combinada con el rango de texto, por ejemplo my-page:p:0:15,0:45{abc123}.

pageTitle (string, requerido) es el título de la página.

selector (string, requerido) es la ruta DOM al elemento que contiene el texto seleccionado.

range (string, requerido) es el rango de texto serializado en el formato startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (string, requerido) es el ID del comentario que inició este chat.

broadcastId (string, requerido) es un UUID para la sincronización en vivo para prevenir efectos de eco.

Respuesta

La respuesta incluye el estado de la API y el ID de la conversación recién creada.

Ejemplo de solicitud

Ejemplo de solicitud 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

Ejemplo de respuesta

Ejemplo de respuesta POST
Copy Copy
1
2{
3 "status": "success",
4 "createdChatId": "conv789"
5}
6

Eliminar conversación

Elimina una conversación de texto existente. Este endpoint requiere permisos de administrador o moderador, o la conversación debe haber sido creada por el usuario autenticado.

Punto final

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

Parámetros

tenantId (parámetro de ruta, requerido) es su Tenant ID de FastComments.

chatId (parámetro de ruta, requerido) es el ID de la conversación a eliminar.

broadcastId (cuerpo de la solicitud, requerido) es un UUID para la sincronización en vivo.

Ejemplo de solicitud

Ejemplo de solicitud 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

Ejemplo de respuesta

Ejemplo de respuesta DELETE
Copy Copy
1
2{
3 "status": "success"
4}
5

Limitación de tasa

Estos endpoints están sujetos a la limitación de tasa estándar de la API de FastComments. El middleware de limitación de tasa se aplica por tenant para prevenir el abuso a la vez que permite patrones de uso normales.

Respuestas de error

Todos los endpoints devuelven códigos de estado HTTP estándar. Una respuesta 400 indica parámetros de solicitud inválidos. Una respuesta 401 significa que la autenticación falló. Una respuesta 403 indica permisos insuficientes. Una respuesta 404 significa que la conversación no se encontró. Una respuesta 429 indica que se excedió el límite de tasa.

Las respuestas de error incluyen un cuerpo JSON con detalles:

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

Seguimiento de uso

La creación de conversaciones incrementa su métrica de uso conversationCreateCount. Toda la actividad de sincronización por WebSocket incrementa pubSubMessageCount y pubSubBandwidth. Puede monitorizar estas métricas en su panel de FastComments bajo analytics de uso.

¿Tienes preguntas?

¡Eso es todo por FastComments Collab Chat! Si tienes alguna pregunta, necesitas ayuda con la implementación o tienes sugerencias de funciones, háznoslo saber más abajo o ponte en contacto con nuestro equipo de soporte.

Para ejemplos en vivo, visita Govscent.org que usa Collab Chat en producción.

Contribuir a esta guía