FastComments.com

Menu Icon

Langue 🇨🇦 Français (Canada)
🇺🇸 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

Premiers pas

Premiers pas
Exemples
Ajout de commentaires en direct aux livres en ligne

Configuration

Options de configuration
Comportement de la sélection de texte

Personnalisation

Personnalisation

Avancé

Synchronisation en direct
Référence de l'API

Ajouter des commentaires en direct intégrés aux documents, livres, etc.

FastComments Collab Chat permet aux utilisateurs de surligner et d'annoter n'importe quel contenu textuel sur votre site Web, en créant des discussions en fil de conversation 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 parfaite 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 précis.

Notez que cette documentation est spécifique à la fonctionnalité Collab Chat. Vous pouvez ajouter des commentaires pour du contenu 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 correspond spécifiquement à la possibilité pour les utilisateurs de sélectionner du texte et de commenter la portion de texte surlignée.

Vous pouvez voir un exemple ici.

Premiers pas Internal Link

Démarrage rapide

Commencer avec Collab Chat est simple. Vous avez besoin du script FastComments Collab Chat, d'un élément HTML contenant le texte que vous voulez annoter, et d'un objet de configuration avec votre Tenant ID.

Installation

Ajoutez le script Collab Chat à votre page :

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

Implémentation de base

Voici un exemple minimal :

Implémentation de base 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 <!-- Votre conteneur de contenu -->
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 <!-- Charger le script Collab Chat -->
16 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
17
18 <!-- Initialiser Collab Chat -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

Remplacez 'demo' par votre FastComments Tenant ID réel si ce n'est pas déjà fait, que vous pouvez trouver dans votre tableau de bord FastComments.

Comment ça fonctionne

Une fois initialisé, les utilisateurs peuvent sélectionner n'importe quel texte à l'intérieur de l'élément cible. Après un bref délai (3,5 secondes sur ordinateur), une invite apparaît leur permettant de démarrer une discussion. Lorsqu'une discussion est créée, une surbrillance visuelle apparaît sur le texte. D'autres utilisateurs peuvent survoler ou cliquer la surbrillance pour voir et participer à la discussion. Toutes les discussions se synchronisent en temps réel entre tous les visiteurs.

Démo en direct

Vous pouvez voir Collab Chat en action sur notre page de démonstration en direct.

Prochaines étapes

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 le fonctionnement de la sélection de texte. Découvrez le support du style et du mode sombre dans le guide Customization. Pour des intégrations avancées, explorez la Référence de l'API.

Bibliothèques frontend

Toutes les bibliothèques frontend FastComments (react, vue, angular, etc.) incluent Collab Chat.

Exemples Internal Link

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 :

Exemple de base 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

Exemple avec URL personnalisée (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 avoir un meilleur contrôle sur la façon dont les conversations sont regroupées :

Collab Chat avec URL personnalisée
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

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 arrière-plan sombre, activez la prise en charge du mode sombre pour vous assurer que l'interface de discussion s'affiche correctement :

Collab Chat en mode sombre
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

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 :

Collab Chat avec barre supérieure désactivée
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

Exemple avec rappel du nombre de commentaires

Vous pouvez suivre quand des commentaires sont ajoutés ou mis à jour en utilisant le callback commentCountUpdated :

Collab Chat avec rappel du nombre de commentaires
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

Exemple avec plusieurs sections

Vous pouvez initialiser Collab Chat sur plusieurs sections distinctes de votre page. Chaque section aura ses propres annotations indépendantes :

Collab Chat sur plusieurs sections
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 // Initialiser la section d'introduction
15 FastCommentsCollabChat(document.getElementById('intro-section'), {
16 tenantId: 'demo',
17 urlId: 'my-article-intro'
18 });
19
20 // Initialiser la section principale
21 FastCommentsCollabChat(document.getElementById('main-section'), {
22 tenantId: 'demo',
23 urlId: 'my-article-main'
24 });
25</script>
26

Ajout de commentaires en direct aux livres en ligne Internal Link

Vous pouvez initialiser Collab Chat par page si vous le souhaitez, et avoir des fils de discussion distincts pour chaque page, il suffit de passer au paramètre urlId une valeur telle que book-one-page1. Cette configuration fonctionne également pour le widget de commentaires normal.

Options de configuration Internal Link

Aperçu

FastComments Collab Chat étend le widget de commentaires FastComments standard, il hérite donc de toutes les options de configuration du widget de base tout en ajoutant quelques options spécifiques aux annotations textuelles.

Configuration requise

tenantId

Votre identifiant de locataire FastComments (Tenant ID) est requis. Vous pouvez le trouver dans votre FastComments dashboard.

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

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 avec un urlId personnalisé.

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

Ceci est utile lorsque la structure de vos URL peut changer mais que vous voulez conserver les mêmes conversations, ou lorsque vous souhaitez partager des annotations entre plusieurs pages.

topBarTarget

Contrôle l'affichage de la barre supérieure qui montre 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.

Exemple de configuration
Copy Copy
1
2// Désactiver la barre supérieure
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Afficher la barre supérieure dans un emplacement personnalisé
9FastCommentsCollabChat(element, {
10 tenantId: 'demo',
11 topBarTarget: document.getElementById('custom-header')
12});
13

hasDarkBackground

Active le style mode sombre lorsque votre page a un fond sombre. Cette détection est automatique, mais il peut être souhaitable de la remplacer.

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

commentCountUpdated

Une fonction de rappel qui se déclenche à chaque fois que le nombre de commentaires change. Ceci est utile pour mettre à jour des éléments UI comme des badges ou le titre de la page.

Exemple de configuration
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

Options de configuration héritées

Puisque 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éfinissez la langue de l'interface du widget. FastComments prend en charge des dizaines de langues.

Exemple de configuration
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Espagnol
5});
6

readonly

Rendre toutes les conversations en lecture seule. Les utilisateurs peuvent voir les annotations existantes mais ne peuvent pas en créer de nouvelles ni répondre.

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

sso and simpleSSO

Intégrez votre système d'authentification en utilisant Single Sign-On.

Exemple de configuration
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 sso: {
5 // Configuration SSO
6 }
7});
8

Consultez la documentation SSO pour tous les détails sur les options d'authentification.

maxReplyDepth

Contrôlez combien de niveaux de réponses peuvent être imbriqués. Par défaut, Collab Chat définit ceci à 0, ce qui signifie que tous les commentaires sont à plat (pas de réponses imbriquées). Vous pouvez changer cela si vous voulez des conversations en fils.

Exemple de configuration
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Permettre 3 niveaux d'imbrication
5});
6

Configuration interne

Ces options sont automatiquement définies par Collab Chat et ne doivent pas être remplacées :

Le productId est automatiquement défini à 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 :

Exemple de configuration
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 // Votre configuration SSO
13 },
14 maxReplyDepth: 1
15});
16

Pour une liste complète de toutes les options de configuration disponibles héritées du widget de base, consultez la documentation principale de configuration FastComments.

Comportement de la sélection de texte Internal Link

Comment fonctionne la sélection de texte

Lorsque les utilisateurs sélectionnent du texte à l'intérieur du 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 utilisateur ne scintille lorsque les utilisateurs mettent simplement du texte en surbrillance pour le copier ou le lire. Sur les appareils mobiles, l'invite apparaît immédiatement puisque la sélection de texte est plus volontaire sur les écrans tactiles.

Identifiants de conversation uniques

Chaque conversation obtient 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 pouvant ê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. La mise en évidence est implémentée à l'aide de couleurs d'arrière-plan et apparaît au survol ou lorsque la fenêtre de chat associée est ouverte.

Le système de mise en évidence fonctionne en enveloppant le texte sélectionné dans un élément spécial pouvant être stylisé. Cette approche garantit que les mises en évidence restent précises même lorsque la structure HTML sous-jacente est complexe.

Positionnement de la fenêtre de chat

Lorsqu'un utilisateur clique sur une mise en évidence 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 de la mise en évidence. Sur les appareils mobiles (écrans de moins de 768px de largeur), 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 largeur sur les ordinateurs de bureau avec un espacement de 20px et une flèche visuelle de 16px pointant vers le texte surligné. Ces dimensions sont fixes pour assurer un comportement cohérent, mais vous pouvez personnaliser l'apparence avec du CSS.

Sélections traversant plusieurs éléments

Les utilisateurs peuvent sélectionner du texte qui s'étend sur plusieurs éléments HTML, par exemple en surlignant du milieu d'un paragraphe jusqu'au début d'un autre. Le système de sérialisation des plages 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 dans tous les navigateurs modernes. Pour les anciennes versions d'Internet Explorer, il revient à document.selection pour assurer 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 mises en évidence 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 les 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 Internal Link

Prise en charge du mode sombre

Mode sombre dynamique

Si le mode sombre de votre site est contrôlé en ajoutant la 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.

Exemple CSS pour le mode sombre
Copy Copy
1
2/* Votre CSS pour le mode sombre */
3body.dark {
4 background: #1a1a1a;
5 color: #ffffff;
6}
7

Personnalisation avec 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 commentaires 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 :

Emplacement personnalisé de la barre supérieure
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: document.getElementById('my-custom-header')
5});
6

Ou désactivez-la entièrement en la définissant sur null :

Désactiver la barre supérieure
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: null
5});
6

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 des fenêtres de chat

Les fenêtres de chat font 410px de largeur sur bureau 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 :

Définir la locale
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Espagnol
5});
6

FastComments prend en charge des dizaines de langues. Le réglage de la locale affecte tout le texte de l'interface utilisateur, y compris les invites, les boutons et le texte des espaces réservés.

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 à partir du CSS de votre page. Vous pourriez devoir créer une règle de personnalisation du widget et @importer les polices dans le CSS personnalisé de cette règle si vous voulez que la fenêtre de chat flottante utilise les mêmes polices.

Synchronisation en direct Internal Link

Real-Time Updates

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 qui consultent la même page voient la mise à jour immédiatement sans actualiser.

How WebSocket Sync Works

Lorsque vous initialisez Collab Chat, le widget établit une connexion WebSocket avec les 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 courante.

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.

Broadcast ID System

Pour éviter les effets d'écho où les utilisateurs voient leurs propres actions leur être renvoyées, chaque mise à jour comprend 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.

Live User Count

La barre supérieure affiche le nombre d'utilisateurs qui consultent actuellement la page. Ce compteur se met à jour en temps réel au fur et à mesure que les utilisateurs rejoignent et quittent. Le nombre d'utilisateurs est fourni via la même connexion WebSocket et s'incrémente/se décrémente automatiquement en fonction des événements de connexion et de déconnexion.

Connection Resilience

Si la connexion WebSocket tombe en raison de problèmes réseau ou de maintenance du 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 fait de manière transparente sans nécessiter l'intervention de l'utilisateur.

Bandwidth Considerations

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 lors des 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.

Cross-Tab Synchronization

Si un utilisateur a la même page ouverte dans plusieurs onglets du navigateur, les mises à jour d'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.

Security

Les messages WebSocket sont transmis via des connexions sécurisées (WSS) et incluent une validation du tenant pour s'assurer 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 Internal Link

Aperçu de l'API

Collab Chat fournit trois points de terminaison REST API pour gérer les conversations textuelles de manière programmatique. Ces points de terminaison 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 points de terminaison.

URL de base

Tous les points de terminaison de l'API Collab Chat sont sous :

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

Authentification

Ces points de terminaison 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 points de terminaison.

Récupérer toutes les conversations

Récupère toutes les conversations textuelles pour une page spécifique.

Point de terminaison

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

Paramètres

tenantId (paramètre de chemin, requis) est votre FastComments Tenant ID.

urlId (paramètre de requête, requis) est l'identifiant de la page pour laquelle vous voulez récupérer les conversations.

Réponse

La réponse inclut le statut de l'API, les informations de session de l'utilisateur actuel si authentifié, un tableau de conversations avec leurs IDs, URLs et plages de texte, un identifiant d'URL nettoyé, un indicateur indiquant si l'utilisateur actuel est administrateur du site ou modérateur, et les détails de connexion WebSocket pour la synchronisation en direct incluant tenantIdWS, urlIdWS, et userIdWS.

Exemple de requête

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

Exemple de réponse

Exemple de réponse 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

Créer une conversation

Créer une nouvelle conversation textuelle pour une sélection de texte spécifique.

Point de terminaison

Point de terminaison POST
Copy Copy
1
2POST /comment-collab-chats/:tenantId
3

Paramètres

tenantId (paramètre de chemin, requis) est votre FastComments Tenant ID.

Le corps de la requête doit être au format JSON et inclure les champs requis suivants.

urlId (string, requis) est l'identifiant de la page de base.

urlIdWithRange (string, requis) correspond à l'URL combinée avec la plage de texte, par exemple my-page:p:0:15,0:45{abc123}.

pageTitle (string, requis) est le titre de la page.

selector (string, requis) est le chemin DOM vers l'élément contenant le texte sélectionné.

range (string, requis) est la plage de texte sérialisée au format startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (string, requis) est l'ID du commentaire qui a initié cette discussion.

broadcastId (string, requis) est un UUID pour la synchronisation en direct afin d'empêcher les effets d'écho.

Réponse

La réponse inclut le statut de l'API et l'ID de la conversation nouvellement créée.

Exemple de requête

Exemple de requête 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

Exemple de réponse

Exemple de réponse POST
Copy Copy
1
2{
3 "status": "success",
4 "createdChatId": "conv789"
5}
6

Supprimer une conversation

Supprime une conversation textuelle existante. Ce point de terminaison nécessite les permissions d'administrateur ou de modérateur, ou la conversation doit avoir été créée par l'utilisateur authentifié.

Point de terminaison

Point de terminaison DELETE
Copy Copy
1
2DELETE /comment-collab-chats/:tenantId/:chatId
3

Paramètres

tenantId (paramètre de chemin, requis) est votre FastComments Tenant ID.

chatId (paramètre de chemin, requis) est l'ID de la conversation à supprimer.

broadcastId (corps de la requête, requis) est un UUID pour la synchronisation en direct.

Exemple de requête

Exemple de requête 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

Exemple de réponse

Exemple de réponse DELETE
Copy Copy
1
2{
3 "status": "success"
4}
5

Limitation de débit

Ces points de terminaison sont soumis à la limitation de débit standard de l'API FastComments. Le middleware de limitation s'applique par locataire afin d'empêcher les abus tout en permettant des modèles d'utilisation normaux.

Réponses d'erreur

Tous les points de terminaison renvoient des codes de statut HTTP standard. Une réponse 400 indique des paramètres de requête invalides. Une réponse 401 signifie que l'authentification a échoué. Une réponse 403 indique des permissions insuffisantes. Une réponse 404 signifie que la conversation est introuvable. Une réponse 429 indique que la limite de taux a été dépassée.

Les réponses d'erreur incluent un corps JSON avec des détails :

Exemple de réponse d'erreur
Copy Copy
1
2{
3 "status": "error",
4 "message": "Conversation not found"
5}
6

Suivi de l'utilisation

La création de conversations incrémente votre métrique d'utilisation conversationCreateCount. Toute activité de synchronisation WebSocket incrémente pubSubMessageCount et pubSubBandwidth. Vous pouvez surveiller ces métriques dans votre tableau de bord FastComments sous les analyses d'utilisation.

Vous avez des questions ?

C'est tout pour FastComments Collab Chat ! Si vous avez des questions, besoin d'aide pour l'implémentation, ou des suggestions de fonctionnalités, faites-le-nous savoir ci-dessous ou contactez notre équipe d'assistance.

Pour des exemples en direct, consultez Govscent.org qui utilise Collab Chat en production.

Contribuer à ce guide