Chat collaboratif

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 Run

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 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 :

Collab Chat avec identifiant URL personnalisé

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

Collab Chat avec le mode sombre

Copy Run

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 la barre supérieure désactivée

Copy Run

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 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 :

Collab Chat avec callback de mise à jour du nombre de commentaires

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

1

2<div id="intro-section">

3 <h2>Introduction</h2>

4 <p>Content for the introduction...</p>

5</div>

6

7<div id="main-section">

8 <h2>Main Content</h2>

9 <p>Content for the main article...</p>

10</div>

11

12<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>

13<script>

14 // Initialize on intro section

15 FastCommentsCollabChat(document.getElementById('intro-section'), {

16 tenantId: 'demo',

17 urlId: 'my-article-intro'

18 });

19

20 // Initialize on main section

21 FastCommentsCollabChat(document.getElementById('main-section'), {

22 tenantId: 'demo',

23 urlId: 'my-article-main'

24 });

25</script>

26

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.

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.

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.

Exemple CSS pour le mode sombre

Copy

1

2/* Votre CSS pour le mode sombre */

3body.dark {

4 background: #1a1a1a;

5 color: #ffffff;

6}

7

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 :

Emplacement personnalisé de la barre supérieure

Copy

1

2FastCommentsCollabChat(element, {

3 tenantId: 'demo',

4 topBarTarget: document.getElementById('my-custom-header')

5});

6

Ou la désactiver complètement en la définissant sur null :

Désactiver la barre supérieure

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 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 :

Définir la locale

Copy

1

2FastCommentsCollabChat(element, {

3 tenantId: 'demo',

4 locale: 'es' // Espagnol

5});

6

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.

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é.