Collab Chat | FastComments Docs

הוספת הערות חיות מקוונות למסמכים, ספרים וכו'

FastComments Collab Chat מאפשר למשתמשים להדגיש ולהוסיף הערות לכל תוכן טקסט באתר שלך, וליצור דיונים בשרשורים שקשורים לבחירות טקסט ספציפיות. משתמשים יכולים לבחור מילים, משפטים או פסקאות שלמות כדי להתחיל שיחות שיתופיות ישירות בתוך התוכן שלך.

תכונה זו מתאימה במיוחד למשוב עריכי, סביבות קריאה שיתופיות, פלטפורמות חינוכיות, סקירת מסמכים ובכל תרחיש שבו ברצונך לקיים דיונים בהקשר הטקסט הקשור לחלק טקסט מסוים.

שים לב שמסמכים אלה ספציפיים לפונקציית ה-Collab Chat. ניתן להוסיף מערכת תגובות לתוכן בעל דפים רבים, כמו ספרים, עם thread-per-page, בלי להשתמש ב-Collab Chat. FastComments גם לא גובה תשלום פר-דף או פר-שרשור. Collab Chat מיועדת במיוחד כאשר אתה רוצה לאפשר למשתמשים לבחור טקסט ולהגיב על החלק המסומן של הטקסט.

ניתן לראות דוגמה כאן.

התחלה

התחלה מהירה

התחלה עם Collab Chat פשוטה. אתה צריך את סקריפט FastComments Collab Chat, אלמנט HTML שמכיל את הטקסט שתרצה להוסיף לו הערות, ואובייקט תצורה עם ה-Tenant ID שלך.

התקנה

Add the Collab Chat script to your page:

טעינת סקריפט Collab Chat

Copy

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

יישום בסיסי

Here's a minimal example:

יישום בסיסי של Collab Chat

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat</title>
</head>
<body>
    <!-- מיכל התוכן שלך -->
    <div id="article-content" style="min-height: 500px;">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <!-- Load the Collab Chat script -->
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <!-- אתחל את Collab Chat -->
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

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

כיצד זה עובד

Once initialized, users can select any text within the target element. After a brief delay (3.5 seconds on desktop), a prompt appears allowing them to start a discussion. When a discussion is created, a visual highlight appears on the text. Other users can hover over or click the highlight to view and participate in the discussion. All discussions sync in real-time across all visitors.

הדגמה חיה

You can see Collab Chat in action on our live demo page.

הצעדים הבאים

Now that you have the basics working, you can customize the appearance and behavior in the Configuration Options guide. Check out the Text Selection Behavior guide to understand how text selection works. Learn about styling and dark mode support in the Customization guide. For advanced integrations, explore the API Reference.

Frontend Libraries

All FastComments frontend libraries (react, vue, angular, etc) have Collab Chat.

דוגמאות

דוגמה בסיסית

הדרך הפשוטה ביותר להשתמש ב-Collab Chat היא למקד מיכל תוכן יחיד. הדוגמה הזו מראה כיצד להפעיל הערות טקסט במאמר:

דוגמה בסיסית של Collab Chat

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat</title>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

דוגמה עם מזהה URL מותאם (לעמוד בספר, מאמר וכו')

כברירת מחדל, Collab Chat משתמש ב-URL של הדף בשילוב עם נתיב האלמנט וטווח הטקסט כדי לזהות שיחות. תוכלו לספק urlId מותאם כדי לקבל שליטה רבה יותר על האופן שבו השיחות מקובצות:

Collab Chat עם מזהה URL מותאם

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    FastCommentsCollabChat(document.getElementById('article-content'), {
        tenantId: 'demo',
        urlId: 'book-one-page-2'
    });
</script>

זה שימושי אם מבנה ה-URL שלכם משתנה אבל אתם רוצים לשמור על אותן שיחות, או אם אתם רוצים לשתף את אותן ההערות של השיחה בין עמודים מרובים.

דוגמה עם מצב כהה

אם לאתר שלכם יש רקע כהה, אפשרו תמיכה במצב כהה כדי להבטיח שממשק הצ'אט ייראה תקין:

Collab Chat עם מצב כהה

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat - Dark Mode</title>
    <style>
        body {
            background-color: #1a1a1a !important;
            color: #e0e0e0 !important;
            font-family: system-ui, -apple-system, sans-serif;
            padding: 20px;
            margin: 0;
        }
        #article-content {
            max-width: 800px;
            margin: 0 auto;
            background-color: #2d2d2d;
            padding: 20px;
            border-radius: 8px;
        }
        h1 {
            color: #ffffff !important;
        }
        p {
            color: #e0e0e0 !important;
            line-height: 1.6;
        }
        .fastcomments-collab-chat-top-bar {
            background-color: #2d2d2d !important;
            color: #e0e0e0 !important;
            border-bottom: 1px solid #444 !important;
        }
    </style>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo',
            hasDarkBackground: true
        });
    </script>
</body>
</html>

דוגמה עם הסרגל העליון מושבת

כברירת מחדל, Collab Chat מציג סרגל עליון עם מונה משתמשים ומונה דיונים. ניתן להשבית אותו:

Collab Chat עם הסרגל העליון מושבת

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat - No Top Bar</title>
</head>
<body>
    <div id="article-content" style="min-height: 500px">
        <h1>My Article Title</h1>
        <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
        <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
    </div>
    <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo',
            topBarTarget: null
        });
    </script>
</body>
</html>

דוגמה עם קריאת חזרה לעדכון ספירת תגובות

ניתן לעקוב לאחר הוספה או עדכון של תגובות באמצעות פונקציית ה-commentCountUpdated:

Collab Chat עם קריאת חזרה לספירת תגובות

Copy

<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    FastCommentsCollabChat(document.getElementById('article-content'), {
        tenantId: 'demo',
        commentCountUpdated: function(count) {
            console.log('Total comments:', count);
            document.getElementById('comment-badge').textContent = count;
        }
    });
</script>

דוגמה עם מקטעים מרובים

ניתן לאתחל את Collab Chat על מספר מקטעים נפרדים בדף שלכם. לכל מקטע יהיו ההערות העצמאיות שלו:

Collab Chat על מספר מקטעים

Copy

<div id="intro-section">
    <h2>Introduction</h2>
    <p>Content for the introduction...</p>
</div>
<div id="main-section">
    <h2>Main Content</h2>
    <p>Content for the main article...</p>
</div>
<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
<script>
    // Initialize on intro section
    FastCommentsCollabChat(document.getElementById('intro-section'), {
        tenantId: 'demo',
        urlId: 'my-article-intro'
    });
    // Initialize on main section
    FastCommentsCollabChat(document.getElementById('main-section'), {
        tenantId: 'demo',
        urlId: 'my-article-main'
    });
</script>

הוספת הערות בזמן אמת לספרים מקוונים

ניתן לאתחל את Collab Chat לכל עמוד במידת הצורך, וליצור שרשורים נפרדים לכל עמוד, פשוט העבר את הפרמטר urlId ערך כמו book-one-page1. תצורה זו עובדת גם עבור ווידג'ט ההערות הרגיל.

אפשרויות תצורה

סקירה

FastComments Collab Chat מרחיב את ווידג'ט התגובות הסטנדרטי של FastComments, כך שהוא יורש את כל אפשרויות התצורה מהווידג'ט הבסיסי ומוסיף כמה אפשרויות ספציפיות להערות טקסט.

תצורה נדרשת

tenantId

נדרש מזהה השוכר (Tenant ID) של FastComments שלך. ניתן למצוא אותו בלוח הבקרה של FastComments.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo'
});

אפשרויות ספציפיות ל-Collab Chat

urlId

ברירת המחדל היא ש-Collab Chat מייצר מזהה ייחודי לכל שיחה בהתבסס על כתובת הדף, נתיב ה-DOM לאלמנט וטווח הטקסט שנבחר. ניתן לעקוף זאת עם urlId מותאם אישית.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    urlId: 'my-custom-page-id'
});

זה שימושי כאשר מבנה ה-URL שלך עשוי להשתנות ואתה רוצה לשמור על אותן שיחות, או כאשר אתה רוצה לשתף הערות על פני מספר דפים.

topBarTarget

שולט בתצוגת הסרגל העליון שמראה את מספר המשתמשים ומספר הדיונים. הגדר כ-null כדי להשבית את הסרגל העליון לחלוטין, או ספק אלמנט DOM כדי להציג אותו במיקום ספציפי.

דוגמת תצורה

Copy

// השבתת סרגל עליון
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});
// הצג את הסרגל העליון במיקום מותאם אישית
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('custom-header')
});

hasDarkBackground

הפעל סגנון מצב כהה כשלעמוד שלך יש רקע כהה. זיהוי זה אוטומטי, אך ייתכן שתרצה לעקוף אותו.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    hasDarkBackground: true
});

commentCountUpdated

פונקציית החזרה שמופעלת בכל פעם שמספר התגובות משתנה. זה שימושי לעדכון רכיבים בממשק המשתמש כמו סיכות או כותרות עמוד.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    commentCountUpdated: function(count) {
        console.log('Total comments:', count);
        document.getElementById('badge').textContent = count;
    }
});

אפשרויות תצורה שנירשו

מכיוון ש-Collab Chat מרחיב את ווידג'ט התגובות הסטנדרטי, ניתן להשתמש בכל אפשרות תצורה מהווידג'ט הבסיסי של FastComments. הנה כמה אפשרויות נפוצות:

locale

קבע את שפת ממשק הווידג'ט. FastComments תומך בעשרות שפות.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // ספרדית
});

readonly

הפוך את כל השיחות לקריאה בלבד. משתמשים יכולים לצפות בהערות קיימות אך לא יכולים ליצור חדשות או להגיב.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    readonly: true
});

sso and simpleSSO

שלב עם מערכת האימות שלך באמצעות Single Sign-On.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    sso: {
        // תצורת SSO
    }
});

עיין בתיעוד SSO לפרטים מלאים על אפשרויות האימות.

maxReplyDepth

שלוט כמה רמות עומק תגובות יכולות להיות. כברירת מחדל, Collab Chat מגדיר זאת כ-0, כלומר כל התגובות שטוחות (ללא תגובות מקוננות). ניתן לשנות זאת אם ברצונך לשוחח בשרשור תגובות.

דוגמת תצורה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    maxReplyDepth: 3  // אפשר 3 רמות קינון
});

תצורה פנימית

אופציות אלה מוגדרות אוטומטית על ידי Collab Chat ולא יש להן לעקוף אותן:

ה-productId מוגדר אוטומטית ל-3 עבור Collab Chat. התוסף floating-chat נטען אוטומטית כדי לספק את פונקציונליות חלון הצ'אט. הווידג'ט מזהה אוטומטית מכשירי מובייל (מסכים ברוחב פחות מ-768px) ומתאים את הממשק בהתאם.

דוגמה מלאה

הנה דוגמה המציגה מספר אפשרויות תצורה יחד:

דוגמת תצורה

Copy

FastCommentsCollabChat(document.getElementById('article'), {
    tenantId: 'demo',
    urlId: 'my-article-v2',
    hasDarkBackground: false,
    locale: 'en',
    topBarTarget: document.getElementById('custom-header'),
    commentCountUpdated: function(count) {
        document.title = count > 0 ? `(${count}) My Article` : 'My Article';
    },
    sso: {
        // תצורת SSO שלך
    },
    maxReplyDepth: 1
});

למידע מלא על כל אפשרויות התצורה הזמינות שנירשות מהווידג'ט הבסיסי, עיין בתיעוד התצורה הראשי של FastComments.

התנהגות בחירת הטקסט

How Text Selection Works

כאשר משתמשים בוחרים טקסט בתוך המכולה של Collab Chat, הווידג'ט קולט את הבחירה ומאפשר להם לפתוח דיון. הבחירה יכולה להיות קטנה ככל שמילה בודדת או גדולה עד מספר פסקאות החוצות אלמנטים שונים.

Selection Delay

במכשירי שולחן עבודה קיימת השהייה של 3.5 שניות בין הרגע שבו משתמש בוחר טקסט לבין הופעת ההנחיה לפתיחת הדיון. זה מונע מהממשק להבהב כאשר משתמשים רק מסמלים טקסט להעתקה או לקריאה. במכשירים ניידים ההנחיה מופיעה מיד מכיוון שבחירת טקסט במסכי מגע היא בדרך כלל מכוונת יותר.

Unique Conversation IDs

לכל שיחה מוקצה urlId ייחודי שמשלב את כתובת הדף, נתיב אלמנט ה-DOM, וטווח הטקסט הסריאליזованный. זה מבטיח שלכל בחירת טקסט נוצר דיון נפרד שאפשר למצוא שוב מאוחר יותר.

אם תספק urlId מותאם בקונפיגורציה שלך, הוא ישולב עם נתיב האלמנט וטווח הטקסט ליצירת המזהה הסופי.

Visual Highlights

כאשר יש דיון עבור בחירת טקסט מסוימת, הטקסט מקבל הדגשה ויזואלית. ההדגשה ממומשת באמצעות צבעי רקע ומופיעה בעת ריחוף או כאשר חלון הצ'אט המשויך פתוח.

מערכת ההדגשה עובדת על ידי עטיפת הטקסט הנבחר ברכיב מיוחד שניתן לעיצוב. גישה זו מוודאת שההדגשות נשארות מדויקות גם כאשר מבנה ה-HTML הבסיסי מורכב.

Chat Window Positioning

כאשר משתמש לוחץ על הדגשה או יוצר תיאור חדש, חלון צ'אט מופיע בסמוך לטקסט הנבחר. הווידג'ט מחשב אוטומטית את המיקום הטוב ביותר לחלון זה בהתבסס על מרחב התצוגה הזמין.

מנגנון המיקום משתמש במחלקות CSS כמו to-right, to-left, to-top, ו-to-bottom כדי להצביע לאיזו כיוון חלון הצ'אט צריך להתרחב מההדגשה. במכשירי מובייל (מסכים פחות מ-768px ברוחב), חלון הצ'אט תמיד מופיע במסך מלא לשימוש נוח יותר.

Chat Window Dimensions

חלונות הצ'אט ברוחב של 410px בשולחן העבודה עם ריווח של 20px וחץ ויזואלי של 16px שמצביע לטקסט המודגש. מימדים אלה קבועים כדי להבטיח התנהלות עקבית, אך ניתן להתאים את המראה באמצעות CSS.

Cross-Element Selections

משתמשים יכולים לבחור טקסט החוצה אלמנטים HTML מרובים, כמו הדגשה מהאמצע של פסקה ועד תחילתה של פסקה אחרת. מערכת סריאליזציית הטווח מטפלת בזה נכון ותדגיש את כל הטקסט הנבחר אפילו מעבר לגבולות אלמנטים.

Browser Compatibility

מערכת בחירת הטקסט משתמשת ב-API הסטנדרטי window.getSelection() הנתמך בכל הדפדפנים המודרניים. לגרסאות ישנות של Internet Explorer יש fallback ל-document.selection לתאימות.

Selection Persistence

לאחר שנוצר דיון עבור בחירת טקסט, ההערה נשמרת גם אם הדף נטען מחדש. הטווח הסריאליזованный ונתיב ה-DOM מאפשרים לווידג'ט לשחזר את ההדגשות באותו מיקום בדיוק כאשר משתמשים חוזרים לדף.

זה עובד באופן אמין כל עוד תוכן הדף שלך נשאר יציב. אם תשנה את תוכן הטקסט או תבנה מחדש את ה-HTML שלך, ההערות הקיימות עשויות לא להתיישב יותר כהלכה עם הטקסט. מסיבה זו עדיף להימנע משינויים משמעותיים בתוכן בעמודים עם הערות פעילות, או לשקול להעביר את ההערות כאשר שינויים בתוכן הכרחיים.

התאמה אישית

תמיכה במצב כהה

מצב כהה דינמי

אם מצב כהה באתר שלך נשלט על ידי הוספת מחלקת .dark לאלמנט body, ממשק המשתמש של Collab Chat יתאים זאת אוטומטית מבלי שיידרש אתחול מחדש. סגנונות הווידג'ט מעוצבים כדי להגיב לנוכחות מחלקה זו.

דוגמת CSS למצב כהה

Copy

/* CSS למצב כהה */
body.dark {
    background: #1a1a1a;
    color: #ffffff;
}

עיצוב מותאם באמצעות CSS

ניתן להתאים את הופעת ההדגשות, חלונות הצ'אט ואלמנטים נוספים באמצעות CSS. הווידג'ט מוסיף מחלקות ספציפיות שניתן לטרגט בגליון הסגנונות שלך.

הדגשות הטקסט משתמשות במערכת עיצוב בועות ההערות של FastComments, לכן כל ההתאמות שהחלת על הווידג'ט התגובות הסטנדרטי ישפיעו גם על Collab Chat.

התאמת הסרגל העליון

הסרגל העליון מציג את מספר המשתמשים המקוונים ואת מספר הדיונים. ניתן להתאים את מיקומו על ידי מתן אלמנט מותאם כ-topBarTarget:

מיקום מותאם לסרגל העליון

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('my-custom-header')
});

או להשבית אותו לחלוטין על ידי הגדרתו ל-null:

השבתת הסרגל העליון

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});

התנהגות במובייל

במסכים ברוחב מתחת ל-768px, Collab Chat עובר אוטומטית לפריסת מותאמת לנייד. חלונות הצ'אט מופיעים במסך מלא במקום לרחף לצד הטקסט, ועיכוב הבחירה מוסר כדי לאפשר אינטראקציה מיידית יותר.

התנהגות זו מובנית ואינה דורשת קונפיגורציה. הווידג'ט מזהה את גודל המסך באופן אוטומטי ומתאים את עצמו בהתאם.

מראה חלון הצ'אט

חלונות הצ'אט רוחבם 410px בדסקטופ עם חץ בגודל 16px שמצביע לטקסט המודגש. החלונות ממקמים את עצמם באופן אוטומטי לפי שטח הצפייה הזמין, באמצעות מחלקות מיקום כמו to-right, to-left, to-top, ו-to-bottom.

ניתן להוסיף CSS מותאם כדי להתאים צבעים, גופנים, ריווח או מאפייני חזות אחרים של החלונות הללו. חלונות הצ'אט משתמשים באותה מבנה רכיבים כמו הווידג'ט הסטנדרטי של FastComments, ולכן הם יורשים כל התאמה גלובלית שהחלת.

לוקליזציה

Collab Chat תומך בכל אפשרויות הלוקליזציה אותן הווידג'ט הסטנדרטי של FastComments תומך. הגדר את האפשרות locale כדי להציג טקסט בממשק בשפות שונות:

הגדרת locale

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // ספרדית
});

FastComments תומכת בעשרות שפות. הגדרת ה-locale משפיעה על כל טקסט בממשק המשתמש, כולל הודעות, כפתורים וטקסטי מציין מקום.

אפשרויות התאמה שיורשות

מכיוון ש-Collab Chat מרחיב את הווידג'ט התגובות הסטנדרטי, הוא יורש את כל אפשרויות ההתאמה מהווידג'ט הבסיסי. זה כולל מחלקות CSS מותאמות, תרגומים מותאמים, התאמת אווטאר, עיצוב תאריכים ועוד הרבה.

עיין בתיעוד ההתאמה הראשי של FastComments לרשימה המלאה של אפשרויות ההתאמה הזמינות.

עבודה עם גופנים מותאמים

אם האתר שלך משתמש בגופנים מותאמים, ממשק המשתמש של Collab Chat יורש את אותם גופנים מקובץ ה-CSS של העמוד שלך. ייתכן שתצטרך ליצור כלל התאמה לווידג'ט ולייבא (@import) את כל הגופנים ב-CSS המותאם בכלל זה אם ברצונך שחלון הצ'אט הצף ישתמש באותם גופנים.

סנכרון בזמן אמת

עדכונים בזמן אמת

Collab Chat משתמש בחיבורים מסוג WebSocket כדי לסנכרן את כל השיחות בזמן אמת בין כל המשתמשים המחוברים. כאשר מישהו יוצר הערה חדשה, מוסיף תגובה, או מוחק דיון, כל המשתמשים האחרים הצופים באותה עמוד רואים את העדכון מיד בלי רענון.

איך הסנכרון ב-WebSocket עובד

כאשר אתם מאתחלים את Collab Chat, הווידג'ט יוצר חיבור WebSocket לשרתים של FastComments. החיבור נשאר פתוח במשך כל זמן מושב המשתמש ומאזין לעדכונים הקשורים לעמוד הנוכחי.

מערכת ה-WebSocket משתמשת בשלושה סוגי הודעות שידור עבור Collab Chat. האירוע new-text-chat מתרחש כשמישהו יוצר הערה חדשה בעמוד. האירוע updated-text-chat מתרחש כשמישהו מעדכן שיחה קיימת. האירוע deleted-text-chat מתרחש כשמישהו מוחק הערה.

מערכת מזהה השידור

כדי למנוע אפקט של הדהוד שבו משתמשים רואים את הפעולות שלהם משודרות חזרה אליהם, כל עדכון כולל broadcastId ייחודי. כאשר משתמש יוצר או מעדכן הערה, הקליינט שלו מייצר UUID עבור הפעולה הזו. כאשר ה-WebSocket משדר את העדכון חזרה לכל הקליינטים, הקליינט שמקורו בעדכון מתעלם מהעדכון כי הוא תואם ל-broadcastId שלו.

זה מבטיח אינטראקציה חלקה שבה המשתמשים רואים את השינויים שלהם מיד בממשק המשתמש בלי לחכות לסבב ההעברה דרך השרת, ובמקביל מבטיח שכל המשתמשים האחרים יקבלו את העדכון.

ספירת משתמשים חיה

סרגל העליון מציג את מספר המשתמשים שבכּרגע צופים בעמוד. ספירה זו מתעדכנת בזמן אמת כאשר משתמשים מצטרפים ויוצאים. ספירת המשתמשים מסופקת דרך אותו חיבור WebSocket ומתעדכנת אוטומטית על בסיס אירועי חיבור וניתוק.

עמידות החיבור

אם חיבור ה-WebSocket נקטע עקב בעיות רשת או תחזוקת שרת, הווידג'ט מנסה להתחבר מחדש אוטומטית. במהלך תקופת החיבור מחדש, משתמשים עדיין יכולים לפעול עם ההערות הקיימות, אך הם לא יראו עדכוני זמן אמת מאחרים עד שהחיבור יוקם מחדש.

לאחר חיבור מחדש, הווידג'ט מסנכרן מחדש כדי לוודא שלא הוחמצו עדכונים. זה קורה בשקיפות וללא צורך בהתערבות המשתמש.

שיקולי רוחב פס

הודעות WebSocket קלות במשקל ומכילות רק את המידע החיוני הנדרש לסנכרון המצב. יצירת הערה חדשה בדרך כלל משתמשת בפחות מ-1KB של רוחב פס. המערכת כוללת גם איגוד חכם של הודעות כדי להפחית את תדירות ההודעות בתקופות פעילות גבוהה.

מדדי השימוש שלכם בלוח הבקרה של FastComments עוקבים אחרי pubSubMessageCount ו-pubSubBandwidth כך שתוכלו לנטר את פעילות הסנכרון בזמן אמת ברחבי האתרים שלכם.

סנכרון בין לשוניות

אם משתמש פתח את אותו עמוד בכמה כרטיסיות בדפדפן, עדכונים בכרטיסיה אחת מופיעים מיד בכרטיסיות האחרות. זה פועל דרך אותו מנגנון סנכרון WebSocket ואינו דורש תצורה נוספת.

אבטחה

הודעות WebSocket משודרות דרך חיבורים מאובטחים (WSS) וכוללות tenant validation כדי לוודא שמשתמשים מקבלים רק עדכונים עבור שיחות אותם הם מורשים לראות. השרת מאמת את כל הפעולות לפני שהוא משדר אותן כדי למנוע גישה או מניפולציה לא מורשית.

תיעוד ה-API

סקירת API

Collab Chat מספקת שלוש נקודות קצה REST API לניהול שיחות טקסט באופן תכנותי. נקודות קצה אלה מאפשרות לך לאחזר, ליצור ולמחוק הערות מבלי להשתמש בווידג'ט בדפדפן.

אלו נקודות קצה ציבוריות שמאמתות משתמשים באמצעות עוגיות הדפדפן. הן אינן משתמשות במפתחות API. משתמשים חייבים להיות מחוברים ל-FastComments בדפדפן שלהם כדי לגשת לנקודות קצה אלה.

Base URL

All Collab Chat API endpoints are under:

כתובת בסיס

Copy

https://fastcomments.com/comment-collab-chats

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

החזר את כל שיחות הטקסט עבור דף מסוים.

Endpoint

נקודת קצה GET

Copy

GET /comment-collab-chats/:tenantId?urlId=<urlId>

Parameters

tenantId (path parameter, required) הוא מזהה ה-Tenant של FastComments שלך.

urlId (query parameter, required) הוא מזהה הדף שעליו ברצונך לאחזר שיחות.

Response

התשובה כוללת את סטטוס ה-API, מידע על סשן המשתמש הנוכחי אם מאומת, מערך שיחות עם ה-IDs שלהן, כתובות URL וטווחי טקסט, מזהה URL מנוקה, דגל המציין האם המשתמש הנוכחי הוא מנהל אתר או מודרטור, ופרטי חיבור WebSocket לסנכרון חי הכוללים את tenantIdWS, urlIdWS, ו-userIdWS.

Example Request

דוגמת בקשת GET

Copy

curl "https://fastcomments.com/comment-collab-chats/demo?urlId=my-article-page" \
  --cookie "your-session-cookie"

Example Response

דוגמת תגובת GET

Copy

{
  "status": "success",
  "user": {
    "id": "user123",
    "username": "john_doe"
  },
  "conversations": [
    {
      "_id": "conv123",
      "urlId": "my-article-page:p:0:15,0:45{abc123}",
      "range": "0:15,0:45{abc123}"
    },
    {
      "_id": "conv456",
      "urlId": "my-article-page:h1:5:20,5:35{def456}",
      "range": "5:20,5:35{def456}"
    }
  ],
  "urlIdClean": "my-article-page",
  "isSiteAdmin": false,
  "tenantIdWS": "demo",
  "urlIdWS": "my-article-page",
  "userIdWS": "user123"
}

Create Conversation

צור שיחת טקסט חדשה עבור בחירת טקסט מסוימת.

Endpoint

נקודת קצה POST

Copy

POST /comment-collab-chats/:tenantId

Parameters

tenantId (path parameter, required) הוא מזהה ה-Tenant של FastComments שלך.

גוף הבקשה חייב להיות JSON ולכלול את השדות החובה הבאים.

urlId (string, required) הוא מזהה הדף הבסיסי.

urlIdWithRange (string, required) הוא ה-URL המשולב עם טווח הטקסט, לדוגמה my-page:p:0:15,0:45{abc123}.

pageTitle (string, required) הוא כותרת הדף.

selector (string, required) הוא נתיב ה-DOM לאלמנט שמכיל את הטקסט הנבחר.

range (string, required) הוא טווח הטקסט הסריאלי בפורמט startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (string, required) הוא ה-ID של ההערה שהחלה את הצ'אט הזה.

broadcastId (string, required) הוא UUID לסנכרון חי כדי למנוע אפקטי הדהוד.

Response

התשובה כוללת את סטטוס ה-API ואת ה-ID של השיחה שנוצרה זה עתה.

Example Request

דוגמת בקשת POST

Copy

curl -X POST "https://fastcomments.com/comment-collab-chats/demo" \
  --cookie "your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "urlId": "my-article-page",
    "urlIdWithRange": "my-article-page:p:0:15,0:45{abc123}",
    "pageTitle": "My Article Title",
    "selector": "div#article > p:nth-child(2)",
    "range": "0:15,0:45{abc123}",
    "createdFromCommentId": "comment789",
    "broadcastId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Example Response

דוגמת תגובת POST

Copy

{
  "status": "success",
  "createdChatId": "conv789"
}

Delete Conversation

מחק שיחת טקסט קיימת. נקודת קצה זו דורשת הרשאות מנהל או מודרטור, או שהשיחה חייבת להיות נוצרה על ידי המשתמש המאומת.

Endpoint

נקודת קצה DELETE

Copy

DELETE /comment-collab-chats/:tenantId/:chatId

Parameters

tenantId (path parameter, required) הוא מזהה ה-Tenant של FastComments שלך.

chatId (path parameter, required) הוא ה-ID של השיחה למחיקה.

broadcastId (request body, required) הוא UUID לסנכרון חי.

Example Request

דוגמת בקשת DELETE

Copy

curl -X DELETE "https://fastcomments.com/comment-collab-chats/demo/conv789" \
  --cookie "your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcastId": "550e8400-e29b-41d4-a716-446655440001"
  }'

Example Response

דוגמת תגובת DELETE

Copy

{
  "status": "success"
}

Rate Limiting

נקודות קצה אלה כפופות להגבלת קצב הסטנדרטית של FastComments API. ה-middleware של הגבלת הקצב מופעל לכל Tenant כדי למנוע ניצול לרעה תוך שמירה על דפוסי שימוש רגילים.

Error Responses

כל נקודות הקצה מחזירות קודי סטטוס HTTP סטנדרטיים. תגובת 400 מעידה על פרמטרי בקשה לא חוקיים. תגובת 401 משמעותה שהאימות נכשל. תגובת 403 מציינת חוסר הרשאות מספיקות. תגובת 404 פירושה שהשיחה לא נמצאה. תגובת 429 מעידה על חריגה ממגבלת הקצב.

תגובות שגיאה כוללות גוף JSON עם פרטים:

דוגמת תגובת שגיאה

Copy

{
  "status": "error",
  "message": "Conversation not found"
}

Usage Tracking

יצירת שיחות מגדילה את מדד השימוש conversationCreateCount. כל פעילות סנכרון WebSocket מגדילה את pubSubMessageCount ו-pubSubBandwidth. ניתן לעקוב אחר מדדים אלה בלוח המחוונים של FastComments תחת ניתוחי שימוש.

יש לכם שאלות?

זה הכל עבור FastComments Collab Chat! אם יש לכם שאלות, זקוקים לעזרה ביישום, או יש לכם הצעות לתכונות, אנא הודיעו לנו למטה או פנו לצוות התמיכה שלנו.

לדוגמאות חיות, בדקו את Govscent.org שמשתמשת ב-Collab Chat בסביבת הייצור.

שפה 🇮🇱 עברית

התחלה

תצורה

התאמה אישית

מתקדם

הוספת הערות חיות מקוונות למסמכים, ספרים וכו'

התחלה

התחלה מהירה

התקנה

יישום בסיסי

כיצד זה עובד

הדגמה חיה

הצעדים הבאים

Frontend Libraries

דוגמאות

דוגמה בסיסית

דוגמה עם מזהה URL מותאם (לעמוד בספר, מאמר וכו')

דוגמה עם מצב כהה

דוגמה עם הסרגל העליון מושבת

דוגמה עם קריאת חזרה לעדכון ספירת תגובות

דוגמה עם מקטעים מרובים

הוספת הערות בזמן אמת לספרים מקוונים

אפשרויות תצורה

סקירה

תצורה נדרשת

tenantId

אפשרויות ספציפיות ל-Collab Chat

urlId

topBarTarget

hasDarkBackground

commentCountUpdated

אפשרויות תצורה שנירשו

locale

readonly

sso and simpleSSO

maxReplyDepth

תצורה פנימית

דוגמה מלאה

התנהגות בחירת הטקסט

How Text Selection Works

Selection Delay

Unique Conversation IDs

Visual Highlights

Chat Window Positioning

Chat Window Dimensions

Cross-Element Selections

Browser Compatibility

Selection Persistence

התאמה אישית

תמיכה במצב כהה

מצב כהה דינמי

עיצוב מותאם באמצעות CSS

התאמת הסרגל העליון

התנהגות במובייל

מראה חלון הצ'אט

לוקליזציה

אפשרויות התאמה שיורשות

עבודה עם גופנים מותאמים

סנכרון בזמן אמת

עדכונים בזמן אמת

איך הסנכרון ב-WebSocket עובד

מערכת מזהה השידור

ספירת משתמשים חיה

עמידות החיבור

שיקולי רוחב פס

סנכרון בין לשוניות

אבטחה

תיעוד ה-API

סקירת API

Base URL

Authentication

Get All Conversations

Endpoint

Parameters

Response

Example Request

Example Response

Create Conversation

Endpoint

Parameters