Ajouter des commentaires en ligne en direct aux documents, livres, etc.
FastComments Collab Chat permet aux utilisateurs de surligner et d'annoter n'importe quel contenu textuel de votre site, créant des discussions en fil liées à des sélections de texte spécifiques. Les utilisateurs peuvent sélectionner des mots, des phrases ou des paragraphes entiers pour lancer des conversations collaboratives directement dans votre contenu.
Cette fonctionnalité est idéale pour les retours éditoriaux, les environnements de lecture collaborative, les plateformes éducatives, la révision de documents, et tout scénario où vous souhaitez des discussions contextuelles ancrées à un texte spécifique.
Notez que cette documentation concerne spécifiquement la fonctionnalité Collab Chat. Vous pouvez ajouter des commentaires pour des contenus comportant de nombreuses pages, comme des livres, avec un fil par page, sans utiliser collab chat. FastComments ne facture pas non plus par page ni par fil. Collab Chat sert spécifiquement lorsque vous souhaitez permettre aux utilisateurs de sélectionner du texte et de commenter la section de texte surlignée.
Vous pouvez voir un exemple ici.
Premiers pas 
Quick Start
Commencer avec Collab Chat est simple. Vous avez besoin du script FastComments Collab Chat, d'un élément HTML contenant le texte que vous souhaitez annoter, et d'un objet de configuration avec votre Tenant ID.
Installation
Ajoutez le script Collab Chat à votre page :
Basic Implementation
Voici un exemple minimal :
Run 
Remplacez 'demo' par votre véritable Tenant ID FastComments si ce n'est pas déjà fait, que vous pouvez trouver dans votre tableau de bord FastComments.
How It Works
Une fois initialisé, les utilisateurs peuvent sélectionner n'importe quel texte dans l'élément ciblé. Après un bref délai (3,5 secondes sur desktop), une invite apparaît leur permettant de démarrer une discussion. Lorsqu'une discussion est créée, une mise en évidence visuelle apparaît sur le texte. D'autres utilisateurs peuvent survoler ou cliquer sur la mise en évidence pour voir et participer à la discussion. Toutes les discussions se synchronisent en temps réel entre tous les visiteurs.
Live Demo
Vous pouvez voir Collab Chat en action sur notre page de démo en direct.
Next Steps
Maintenant que vous avez les bases en place, vous pouvez personnaliser l'apparence et le comportement dans le guide Configuration Options. Consultez le guide Text Selection Behavior pour comprendre comment fonctionne la sélection de texte. Informez-vous sur le style et la prise en charge du mode sombre dans le guide Customization. Pour des intégrations avancées, explorez la API Reference.
Frontend Libraries
Toutes les bibliothèques frontend FastComments (react, vue, angular, etc.) incluent Collab Chat.
Exemples
Exemple de base
La façon la plus simple d'utiliser Collab Chat est de cibler un seul conteneur de contenu. Cet exemple montre comment activer les annotations de texte sur un article :
Run Exemple avec un identifiant d'URL personnalisé (par page de livre, article, etc.)
Par défaut, Collab Chat utilise l'URL de la page combinée au chemin de l'élément et à la plage de texte pour identifier les conversations. Vous pouvez fournir un urlId personnalisé pour mieux contrôler la façon dont les conversations sont regroupées :
Ceci est utile si la structure de vos URL change mais que vous souhaitez conserver les mêmes conversations, ou si vous voulez partager les mêmes annotations de conversation sur plusieurs pages.
Exemple avec le mode sombre
Si votre site a un fond sombre, activez la prise en charge du mode sombre pour vous assurer que l'interface de chat s'affiche correctement :
Run Exemple avec la barre supérieure désactivée
Par défaut, Collab Chat affiche une barre supérieure avec le nombre d'utilisateurs et le nombre de discussions. Vous pouvez la désactiver :
Run Exemple avec callback de mise à jour du nombre de commentaires
Vous pouvez suivre quand des commentaires sont ajoutés ou mis à jour en utilisant le callback commentCountUpdated :
Exemple avec plusieurs sections
Vous pouvez initialiser Collab Chat sur plusieurs sections distinctes de votre page. Chaque section aura ses propres annotations indépendantes :
Ajouter des commentaires en direct aux livres en ligne
Vous pouvez initialiser Collab Chat par page si vous le souhaitez, et avoir des fils séparés par page ; il suffit de transmettre au paramètre urlId une valeur telle que book-one-page1. Cette configuration fonctionne également pour le widget de commentaires standard.
Options de configuration
Vue d'ensemble
FastComments Collab Chat étend le widget de commentaires standard FastComments, il hérite donc de toutes les options de configuration du widget de base tout en ajoutant quelques options spécifiques aux annotations de texte.
Configuration requise
tenantId
Votre ID de locataire FastComments est requis. Vous pouvez le trouver dans votre FastComments dashboard.
Options spécifiques à Collab Chat
urlId
Par défaut, Collab Chat génère un identifiant unique pour chaque conversation basé sur l'URL de la page, le chemin DOM vers l'élément et la plage de texte sélectionnée. Vous pouvez remplacer ceci par un urlId personnalisé.
Ceci est utile lorsque la structure de vos URL peut changer mais que vous souhaitez conserver les mêmes conversations, ou lorsque vous voulez partager des annotations entre plusieurs pages.
topBarTarget
Contrôle l'affichage de la barre supérieure qui affiche le nombre d'utilisateurs et le nombre de discussions. Définissez sur null pour désactiver complètement la barre supérieure, ou fournissez un élément DOM pour l'afficher à un emplacement spécifique.
hasDarkBackground
Active le style en mode sombre lorsque votre page a un fond sombre. Cette détection est automatique, mais il peut être souhaitable de la remplacer.
commentCountUpdated
Une fonction de rappel qui est déclenchée chaque fois que le nombre de commentaires change. Utile pour mettre à jour des éléments d'interface tels que des badges ou le titre de la page.
Options de configuration héritées
Comme Collab Chat étend le widget de commentaires standard, vous pouvez utiliser n'importe quelle option de configuration du widget FastComments de base. Voici quelques options couramment utilisées :
locale
Définit la langue de l'interface du widget. FastComments prend en charge des dizaines de langues.
readonly
Rendre toutes les conversations en lecture seule. Les utilisateurs peuvent voir les annotations existantes mais ne peuvent pas en créer de nouvelles ou répondre.
sso and simpleSSO
Intégrez votre système d'authentification via Single Sign-On.
Consultez la documentation SSO pour les détails complets sur les options d'authentification.
maxReplyDepth
Contrôlez la profondeur des niveaux de réponses. Par défaut, Collab Chat définit cela à 0, ce qui signifie que tous les commentaires sont plats (pas de réponses imbriquées). Vous pouvez modifier cela si vous souhaitez des conversations avec fils de discussion.
Configuration interne
Ces options sont automatiquement définies par Collab Chat et ne doivent pas être remplacées :
Le productId est automatiquement défini sur 3 pour Collab Chat. L'extension floating-chat est automatiquement chargée pour fournir la fonctionnalité de fenêtre de chat. Le widget détecte automatiquement les appareils mobiles (écrans de moins de 768px de large) et ajuste l'interface en conséquence.
Exemple complet
Voici un exemple montrant plusieurs options de configuration ensemble :
Pour une liste complète de toutes les options de configuration disponibles héritées du widget de base, consultez la documentation de configuration principale de FastComments.
Comportement de la sélection de texte
Comment fonctionne la sélection de texte
Lorsque les utilisateurs sélectionnent du texte dans le conteneur Collab Chat, le widget capture cette sélection et leur permet de démarrer une discussion. La sélection peut être aussi petite qu’un seul mot ou aussi grande que plusieurs paragraphes couvrant différents éléments.
Délai de sélection
Sur les appareils de bureau, il y a un délai de 3,5 secondes entre le moment où un utilisateur sélectionne du texte et l’apparition de l’invite de discussion. Cela évite que l’interface clignote lorsque les utilisateurs mettent simplement en surbrillance du texte pour le copier ou le lire. Sur les appareils mobiles, l’invite apparaît immédiatement puisque la sélection de texte est plus délibérée sur les écrans tactiles.
Identifiants de conversation uniques
Chaque conversation reçoit un urlId unique qui combine l’URL de la page, le chemin de l’élément DOM et la plage de texte sérialisée. Cela garantit que chaque sélection de texte crée une conversation distincte qui peut être retrouvée ultérieurement.
Si vous fournissez un urlId personnalisé dans votre configuration, il sera combiné avec le chemin de l’élément et la plage de texte pour créer l’identifiant final.
Mises en évidence visuelles
Lorsqu’une discussion existe pour une sélection de texte particulière, ce texte reçoit une mise en évidence visuelle. Le surlignage est implémenté à l’aide de couleurs de fond et apparaît au survol ou lorsque la fenêtre de chat associée est ouverte.
Le système de surlignage fonctionne en enveloppant le texte sélectionné dans un élément spécial qui peut être stylé. Cette approche garantit que les surlignages restent précis même lorsque la structure HTML sous-jacente est complexe.
Positionnement de la fenêtre de chat
Lorsqu’un utilisateur clique sur un surlignage ou crée une nouvelle annotation, une fenêtre de chat apparaît près du texte sélectionné. Le widget calcule automatiquement la meilleure position pour cette fenêtre en fonction de l’espace disponible dans la fenêtre d’affichage.
Le système de positionnement utilise des classes CSS comme to-right, to-left, to-top et to-bottom pour indiquer dans quelle direction la fenêtre de chat doit s’étendre à partir du surlignage. Sur les appareils mobiles (écrans de moins de 768px de large), la fenêtre de chat apparaît toujours en plein écran pour une meilleure ergonomie.
Dimensions de la fenêtre de chat
Les fenêtres de chat font 410px de large sur desktop avec un espacement de 20px et une flèche visuelle de 16px pointant vers le texte surligné. Ces dimensions sont fixes pour garantir un comportement cohérent, mais vous pouvez personnaliser l’apparence avec du CSS.
Sélections inter-éléments
Les utilisateurs peuvent sélectionner du texte qui s’étend sur plusieurs éléments HTML, comme un surlignage allant du milieu d’un paragraphe au début d’un autre. Le système de sérialisation de plage gère cela correctement et mettra en évidence tout le texte sélectionné même à travers les limites des éléments.
Compatibilité des navigateurs
Le système de sélection de texte utilise l’API standard window.getSelection() qui est prise en charge par tous les navigateurs modernes. Pour les anciennes versions d’Internet Explorer, il revient à document.selection pour la compatibilité.
Persistance des sélections
Une fois qu’une conversation est créée pour une sélection de texte, cette annotation persiste même si la page est rechargée. La plage sérialisée et le chemin DOM permettent au widget de restaurer les surlignages exactement au même endroit lorsque les utilisateurs reviennent sur la page.
Cela fonctionne de manière fiable tant que le contenu de votre page reste stable. Si vous modifiez le contenu textuel ou restructurez votre HTML, les annotations existantes peuvent ne plus s’aligner correctement avec le texte. Pour cette raison, il est préférable d’éviter des modifications majeures du contenu sur les pages comportant des annotations actives, ou d’envisager de migrer les annotations lorsque des changements de contenu sont nécessaires.
Personnalisation
Prise en charge du mode sombre
Mode sombre dynamique
Si le mode sombre de votre site est activé en ajoutant une classe .dark à l'élément body, l'interface Collab Chat respectera automatiquement ce réglage sans nécessiter de réinitialisation. Les styles du widget sont conçus pour réagir à la présence de cette classe.
Personnalisation par CSS
Vous pouvez personnaliser l'apparence des surlignages, des fenêtres de chat et d'autres éléments à l'aide de CSS. Le widget ajoute des classes spécifiques que vous pouvez cibler dans votre feuille de style.
Les surlignages de texte utilisent le système de style des bulles de commentaire de FastComments, donc toutes les personnalisations que vous avez appliquées au widget de commentaires standard affecteront également Collab Chat.
Personnalisation de la barre supérieure
La barre supérieure affiche le nombre d'utilisateurs en ligne et le nombre de discussions. Vous pouvez personnaliser sa position en fournissant un élément personnalisé comme topBarTarget :
Ou la désactiver complètement en la définissant sur null :
Comportement sur mobile
Sur les écrans de moins de 768px de large, Collab Chat bascule automatiquement vers une mise en page optimisée pour mobile. Les fenêtres de chat apparaissent en plein écran au lieu de flotter à côté du texte, et le délai de sélection est supprimé pour une interaction plus immédiate.
Ce comportement est intégré et ne nécessite aucune configuration. Le widget détecte automatiquement la taille de l'écran et s'ajuste en conséquence.
Apparence de la fenêtre de chat
Les fenêtres de chat font 410px de large sur desktop avec une flèche de 16px pointant vers le texte surligné. Les fenêtres se positionnent automatiquement en fonction de l'espace disponible dans la fenêtre d'affichage, en utilisant des classes de positionnement comme to-right, to-left, to-top, et to-bottom.
Vous pouvez ajouter du CSS personnalisé pour ajuster les couleurs, les polices, les espacements ou d'autres propriétés visuelles de ces fenêtres. Les fenêtres de chat utilisent la même structure de composants que le widget FastComments standard, elles héritent donc de toutes les personnalisations globales que vous avez appliquées.
Localisation
Collab Chat prend en charge toutes les mêmes options de localisation que le widget FastComments standard. Définissez l'option locale pour afficher le texte de l'interface dans différentes langues :
FastComments prend en charge des dizaines de langues. Le paramètre locale affecte tout le texte de l'interface utilisateur, y compris les invites, les boutons et le texte des champs de saisie.
Options de personnalisation héritées
Puisque Collab Chat étend le widget de commentaires standard, il hérite de toutes les options de personnalisation du widget de base. Cela inclut les classes CSS personnalisées, les traductions personnalisées, la personnalisation des avatars, le formatage des dates, et bien plus encore.
Consultez la documentation principale de personnalisation de FastComments pour la liste complète des options de personnalisation disponibles.
Utilisation de polices personnalisées
Si votre site utilise des polices personnalisées, l'interface Collab Chat héritera de ces polices depuis le CSS de votre page. Il se peut que vous deviez créer une règle de personnalisation du widget et @import toutes les polices dans le CSS personnalisé de cette règle si vous
souhaitez que la fenêtre de chat flottante utilise les mêmes polices.
Synchronisation en temps réel
Mises à jour en temps réel
Collab Chat utilise des connexions WebSocket pour synchroniser toutes les conversations en temps réel entre tous les utilisateurs connectés. Lorsqu'une personne crée une nouvelle annotation, ajoute un commentaire ou supprime une discussion, tous les autres utilisateurs affichant la même page voient la mise à jour immédiatement sans actualiser.
Comment fonctionne la synchronisation WebSocket
Lorsque vous initialisez Collab Chat, le widget établit une connexion WebSocket aux serveurs FastComments. Cette connexion reste ouverte pendant la durée de la session de l'utilisateur et écoute les mises à jour liées à la page en cours.
Le système WebSocket utilise trois types de messages de diffusion pour Collab Chat. L'événement new-text-chat se déclenche lorsqu'une personne crée une nouvelle annotation sur la page. L'événement updated-text-chat se déclenche lorsqu'une personne met à jour une conversation existante. L'événement deleted-text-chat se déclenche lorsqu'une personne supprime une annotation.
Système d'ID de diffusion
Pour éviter les effets d'écho où les utilisateurs voient leurs propres actions leur être renvoyées, chaque mise à jour inclut un broadcastId unique. Lorsqu'un utilisateur crée ou met à jour une annotation, son client génère un UUID pour cette opération. Lorsque le WebSocket diffuse la mise à jour à tous les clients, le client d'origine ignore la mise à jour parce qu'elle correspond à son propre broadcastId.
Cela garantit une interaction fluide où les utilisateurs voient leurs modifications immédiatement dans l'UI sans attendre l'aller-retour via le serveur, tout en s'assurant que tous les autres utilisateurs reçoivent la mise à jour.
Nombre d'utilisateurs connectés
La barre supérieure affiche le nombre d'utilisateurs actuellement en train de consulter la page. Ce nombre se met à jour en temps réel au fur et à mesure que des utilisateurs rejoignent et quittent. Le nombre d'utilisateurs est fourni via la même connexion WebSocket et s'incrémente/s décrémente automatiquement en fonction des événements de connexion et de déconnexion.
Résilience de la connexion
Si la connexion WebSocket tombe à cause de problèmes réseau ou de maintenance serveur, le widget tente automatiquement de se reconnecter. Pendant la période de reconnexion, les utilisateurs peuvent toujours interagir avec les annotations existantes, mais ils ne verront pas les mises à jour en temps réel des autres utilisateurs tant que la connexion n'est pas rétablie.
Une fois reconnecté, le widget se resynchronise pour s'assurer qu'aucune mise à jour n'a été manquée. Cela se produit de manière transparente sans nécessiter d'intervention de l'utilisateur.
Considérations sur la bande passante
Les messages WebSocket sont légers et ne contiennent que les informations essentielles nécessaires pour synchroniser l'état. La création d'une nouvelle annotation utilise généralement moins de 1 Ko de bande passante. Le système inclut également un regroupement intelligent pour réduire la fréquence des messages pendant les périodes d'activité élevée.
Vos métriques d'utilisation dans le tableau de bord FastComments suivent pubSubMessageCount et pubSubBandwidth afin que vous puissiez surveiller l'activité de synchronisation en temps réel sur vos sites.
Synchronisation entre onglets
Si un utilisateur a la même page ouverte dans plusieurs onglets du navigateur, les mises à jour dans un onglet apparaissent immédiatement dans les autres onglets. Cela fonctionne via le même mécanisme de synchronisation WebSocket et ne nécessite aucune configuration supplémentaire.
Sécurité
Les messages WebSocket sont transmis via des connexions sécurisées (WSS) et incluent la validation du tenant pour garantir que les utilisateurs ne reçoivent que les mises à jour des conversations qu'ils sont autorisés à voir. Le serveur valide toutes les opérations avant de les diffuser afin d'empêcher tout accès ou manipulation non autorisé.
Référence de l'API
Aperçu de l'API
Collab Chat fournit trois endpoints REST API pour gérer les conversations textuelles de manière programmatique. Ces endpoints vous permettent de récupérer, créer et supprimer des annotations sans utiliser le widget du navigateur.
Ce sont des points de terminaison publics qui authentifient les utilisateurs via les cookies du navigateur. Ils n'utilisent pas de clés API. Les utilisateurs doivent être connectés à FastComments dans leur navigateur pour accéder à ces endpoints.
Base URL
All Collab Chat API endpoints are under:
Authentication
These endpoints authenticate users via browser cookies. They do not use API keys. Users must be logged into FastComments in their browser to access these endpoints.
Get All Conversations
Retrieve all text conversations for a specific page.
Endpoint
Parameters
tenantId (path parameter, required) is your FastComments Tenant ID.
urlId (query parameter, required) is the page identifier you want to retrieve conversations for.
Response
The response includes the API status, current user session information if authenticated, an array of conversations with their IDs, URLs, and text ranges, a cleaned URL identifier, a flag indicating if the current user is a site admin or moderator, and WebSocket connection details for live sync including tenantIdWS, urlIdWS, and userIdWS.
Example Request
Example Response
Create Conversation
Create a new text conversation for a specific text selection.
Endpoint
Parameters
tenantId (path parameter, required) is your FastComments Tenant ID.
The request body must be JSON and include these required fields.
urlId (string, required) is the base page identifier.
urlIdWithRange (string, required) is the URL combined with the text range, for example my-page:p:0:15,0:45{abc123}.
pageTitle (string, required) is the title of the page.
selector (string, required) is the DOM path to the element containing the selected text.
range (string, required) is the serialized text range in the format startOffset:endOffset,startOffset:endOffset{checksum}.
createdFromCommentId (string, required) is the ID of the comment that initiated this chat.
broadcastId (string, required) is a UUID for live synchronization to prevent echo effects.
Response
The response includes the API status and the ID of the newly created conversation.
Example Request
Example Response
Delete Conversation
Delete an existing text conversation. This endpoint requires admin or moderator permissions, or the conversation must have been created by the authenticated user.
Endpoint
Parameters
tenantId (path parameter, required) is your FastComments Tenant ID.
chatId (path parameter, required) is the ID of the conversation to delete.
broadcastId (request body, required) is a UUID for live synchronization.
Example Request
Example Response
Rate Limiting
These endpoints are subject to standard FastComments API rate limiting. The rate limit middleware applies per-tenant to prevent abuse while allowing normal usage patterns.
Error Responses
All endpoints return standard HTTP status codes. A 400 response indicates invalid request parameters. A 401 response means authentication failed. A 403 response indicates insufficient permissions. A 404 response means the conversation was not found. A 429 response indicates rate limit exceeded.
Error responses include a JSON body with details:
Usage Tracking
Creating conversations increments your conversationCreateCount usage metric. All WebSocket sync activity increments pubSubMessageCount and pubSubBandwidth. You can monitor these metrics in your FastComments dashboard under usage analytics.
Vous avez des questions ?
C'est tout pour FastComments Collab Chat ! Si vous avez des questions, besoin d'aide pour la mise en œuvre, ou des suggestions de fonctionnalités, veuillez nous le faire savoir ci-dessous ou contactez notre équipe d'assistance.
Pour des exemples en conditions réelles, consultez Govscent.org qui utilise Collab Chat en production.