צ'אט שיתופי

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

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

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

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

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

התחלה

התחלה מהירה

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

התקנה

הוסיפו את סקריפט Collab Chat לדף שלכם:

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

Copy

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

מימוש בסיסי

הנה דוגמה מינימלית:

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

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Article with Collab Chat</title>
</head>
<body>
    <!-- Your content container -->
    <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>
    <!-- Initialize Collab Chat -->
    <script>
        FastCommentsCollabChat(document.getElementById('article-content'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

החליפו את 'demo' ב-Tenant ID האמיתי שלכם ב-FastComments אם זה עדיין לא כך, אותו תוכלו למצוא ב-לוח הבקרה של FastComments.

איך זה עובד

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

הדגמה חיה

תוכלו לראות את Collab Chat בפעולה ב-דף ההדגמה החיה שלנו.

הצעדים הבאים

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

ספריות Frontend

כל ספריות ה-Frontend של FastComments (react, vue, angular וכו') כוללות את 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 שלך ב-FastComments. ניתן למצוא אותו ב-לוח הבקרה של FastComments.

דוגמת הגדרה

Copy

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

אפשרויות ייחודיות ל-Collab Chat

urlId

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

דוגמת הגדרה

Copy

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

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

topBarTarget

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

דוגמת הגדרה

Copy

// Disable top bar
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});
// Render top bar in custom location
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('custom-header')
});

hasDarkBackground

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

דוגמת הגדרה

Copy

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

commentCountUpdated

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

דוגמת הגדרה

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'  // Spanish
});

readonly

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

דוגמת הגדרה

Copy

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

sso and simpleSSO

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

דוגמת הגדרה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    sso: {
        // SSO configuration
    }
});

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

maxReplyDepth

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

דוגמת הגדרה

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    maxReplyDepth: 3  // Allow 3 levels of nesting
});

הגדרה פנימית

אפשרויות אלו מוגדרות אוטומטית על ידי 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: {
        // Your SSO config
    },
    maxReplyDepth: 1
});

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

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

איך פועלת בחירת טקסט

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

השהיה בבחירה

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

מזהי שיחות ייחודיים

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

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

סימון חזותי

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

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

מיקום חלון הצ'אט

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

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

ממדי חלון הצ'אט

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

בחירות חוצות אלמנטים

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

תאימות דפדפנים

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

שמירת הבחירה

ברגע שנוצרת שיחה עבור בחירת טקסט, ההערה נשמרת גם אם הדף נטען מחדש. הטווח המסודר ונתיב ה-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 מספק שלושה נקודות קצה (endpoints) של REST API לניהול שיחות טקסט באופן תוכנתי. נקודות קצה אלו מאפשרות לך לאחזר, ליצור ולמחוק הערות (annotations) מבלי להשתמש בווידג'ט הדפדפן.

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

כתובת בסיס (Base URL)

כל נקודות הקצה של Collab Chat API נמצאות תחת:

כתובת בסיס

Copy

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

אימות

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

קבלת כל השיחות

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

נקודת קצה

נקודת קצה GET

Copy

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

פרמטרים

tenantId (פרמטר נתיב, נדרש) הוא מזהה ה-Tenant שלך ב-FastComments.

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

תגובה

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

דוגמת בקשה

דוגמת בקשת GET

Copy

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

דוגמת תגובה

דוגמת תגובת 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"
}

יצירת שיחה

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

נקודת קצה

נקודת קצה POST

Copy

POST /comment-collab-chats/:tenantId

פרמטרים

tenantId (פרמטר נתיב, נדרש) הוא מזהה ה-Tenant שלך ב-FastComments.

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

urlId (מחרוזת, נדרש) הוא מזהה הדף הבסיסי.

urlIdWithRange (מחרוזת, נדרש) הוא הכתובת המשולבת עם טווח הטקסט, לדוגמה my-page:p:0:15,0:45{abc123}.

pageTitle (מחרוזת, נדרש) הוא כותרת הדף.

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

range (מחרוזת, נדרש) הוא טווח הטקסט המסודר בפורמט startOffset:endOffset,startOffset:endOffset{checksum}.

createdFromCommentId (מחרוזת, נדרש) הוא המזהה של התגובה שיזמה שיחה זו.

broadcastId (מחרוזת, נדרש) הוא UUID לסנכרון חי למניעת אפקטי הדהוד (echo).

תגובה

התגובה כוללת את סטטוס ה-API ואת המזהה של השיחה החדשה שנוצרה.

דוגמת בקשה

דוגמת בקשת 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"
  }'

דוגמת תגובה

דוגמת תגובת POST

Copy

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

מחיקת שיחה

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

נקודת קצה

נקודת קצה DELETE

Copy

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

פרמטרים

tenantId (פרמטר נתיב, נדרש) הוא מזהה ה-Tenant שלך ב-FastComments.

chatId (פרמטר נתיב, נדרש) הוא המזהה של השיחה שיש למחוק.

broadcastId (גוף הבקשה, נדרש) הוא UUID לסנכרון חי.

דוגמת בקשה

דוגמת בקשת 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"
  }'

דוגמת תגובה

דוגמת תגובת DELETE

Copy

{
  "status": "success"
}

הגבלת קצב (Rate Limiting)

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

תגובות שגיאה

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

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

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

Copy

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

מעקב שימוש

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

יש לכם שאלות?

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

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

שפה 🇮🇱 עברית

התחלה

תצורה

התאמה אישית

מתקדם

צ'אט שיתופי

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

התחלה

התחלה מהירה

התקנה

מימוש בסיסי

איך זה עובד

הדגמה חיה

הצעדים הבאים

ספריות Frontend

דוגמאות

דוגמה בסיסית

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

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

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

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

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

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

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

סקירה כללית

הגדרה נדרשת

tenantId

אפשרויות ייחודיות ל-Collab Chat

urlId

topBarTarget

hasDarkBackground

commentCountUpdated

אפשרויות הגדרה שהתקבלו בירושה

locale

readonly

sso and simpleSSO

maxReplyDepth

הגדרה פנימית

דוגמה מלאה

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

איך פועלת בחירת טקסט

השהיה בבחירה

מזהי שיחות ייחודיים

סימון חזותי

מיקום חלון הצ'אט

ממדי חלון הצ'אט

בחירות חוצות אלמנטים

תאימות דפדפנים

שמירת הבחירה

התאמה אישית

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

מצב כהה דינמי

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

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

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

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

לוקליזציה

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

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

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

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

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

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

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

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

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

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

אבטחה

תיעוד ה-API

סקירת API

כתובת בסיס (Base URL)

אימות

קבלת כל השיחות

נקודת קצה

פרמטרים

תגובה

דוגמת בקשה

דוגמת תגובה

יצירת שיחה

נקודת קצה