Collab Chat | FastComments Docs

문서, 책 등에서 인라인 실시간 댓글 추가하기

FastComments Collab Chat은 사용자가 웹사이트의 모든 텍스트 콘텐츠를 강조하고 주석을 달 수 있게 해, 특정 텍스트 선택에 연결된 스레드형 토론을 생성합니다. 사용자는 단어, 문장 또는 전체 단락을 선택하여 콘텐츠 내에서 직접 협업 대화를 시작할 수 있습니다.

이 기능은 편집 피드백, 협업 읽기 환경, 교육 플랫폼, 문서 검토 및 특정 텍스트에 고정된 맥락적 토론이 필요한 모든 상황에 적합합니다.

Note that these docs are specific to the Collab Chat functionality. You can add commenting for content with lots of pages, like Books, with thread-per-page, without using collab chat. FastComments also does not charge per-page or per-thread. Collab Chat is specifically when you want to allow users to select text and comment on the highlighted section of text.

You can see an example here.

시작하기

빠른 시작

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>
    <!-- 콘텐츠 컨테이너 -->
    <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>
    <!-- Collab Chat 스크립트 로드 -->
    <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>

실제 FastComments Tenant ID로 'demo'를 바꾸세요(이미 설정되어 있지 않은 경우). Tenant ID는 FastComments 대시보드에서 찾을 수 있습니다.

작동 방식

초기화되면 사용자는 대상 요소 내의 임의의 텍스트를 선택할 수 있습니다. 짧은 지연 후(데스크탑에서는 3.5초), 토론을 시작할 수 있는 프롬프트가 나타납니다. 토론이 생성되면 텍스트에 시각적 하이라이트가 표시됩니다. 다른 사용자는 하이라이트에 마우스를 올리거나 클릭하여 토론을 보고 참여할 수 있습니다. 모든 토론은 모든 방문자에게 실시간으로 동기화됩니다.

라이브 데모

Collab Chat의 동작을 라이브 데모 페이지에서 확인할 수 있습니다.

다음 단계

기본 기능이 작동하면 구성 옵션 가이드에서 외관과 동작을 사용자화할 수 있습니다. 텍스트 선택 동작 가이드를 확인하여 텍스트 선택 방식에 대해 이해하세요. 커스터마이제이션 가이드에서 스타일링 및 다크 모드 지원에 대해 알아보세요. 고급 통합의 경우 API 레퍼런스를 살펴보세요.

프론트엔드 라이브러리

모든 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 ID 예제 (책 페이지, 기사 등)

기본적으로 Collab Chat은 페이지 URL과 요소 경로 및 텍스트 범위를 결합하여 대화를 식별합니다. 대화 그룹화 방법을 보다 세밀하게 제어하려면 맞춤 urlId를 제공할 수 있습니다:

Collab Chat with Custom URL ID

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 구조가 변경되더라도 동일한 대화를 유지하려는 경우나 여러 페이지에 동일한 대화 주석을 공유하려는 경우에 유용합니다.

다크 모드 예제

사이트 배경이 어두운 경우 다크 모드 지원을 활성화하여 채팅 UI가 올바르게 표시되도록 하세요:

Collab Chat with Dark Mode

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 with Top Bar Disabled

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 with Comment Count Callback

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 on Multiple Sections

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>
    // 소개 섹션에서 초기화
    FastCommentsCollabChat(document.getElementById('intro-section'), {
        tenantId: 'demo',
        urlId: 'my-article-intro'
    });
    // 본문 섹션에서 초기화
    FastCommentsCollabChat(document.getElementById('main-section'), {
        tenantId: 'demo',
        urlId: 'my-article-main'
    });
</script>

온라인 도서에 실시간 댓글 추가

원하면 페이지별로 Collab Chat을 초기화하고 페이지별로 별도의 스레드를 가질 수 있습니다. 간단히 urlId 매개변수 에 book-one-page1과 같은 값을 전달하세요. 이 구성은 일반 댓글 위젯에서도 작동합니다.

구성 옵션

개요

FastComments Collab Chat은 표준 FastComments 댓글 위젯을 확장하여 기본 위젯의 모든 구성 옵션을 상속하면서 텍스트 주석에 특화된 몇 가지 옵션을 추가합니다.

필수 구성

tenantId

FastComments Tenant ID가 필요합니다. 이 값은 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

// 상단 바 비활성화
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: null
});
// 상단 바를 사용자 지정 위치에 렌더링
FastCommentsCollabChat(element, {
    tenantId: 'demo',
    topBarTarget: document.getElementById('custom-header')
});

hasDarkBackground

페이지에 어두운 배경이 있을 때 다크 모드 스타일을 활성화합니다. 이 감지는 자동으로 이루어지지만 수동으로 덮어쓰는 것이 바람직할 수 있습니다.

구성 예제

Copy

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

commentCountUpdated

댓글 수가 변경될 때마다 호출되는 콜백 함수입니다. 배지나 페이지 제목과 같은 UI 요소를 업데이트하는 데 유용합니다.

구성 예제

Copy

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

상속된 구성 옵션

Collab Chat은 표준 댓글 위젯을 확장하므로, 기본 FastComments 위젯의 모든 구성 옵션을 사용할 수 있습니다. 다음은 일반적으로 사용되는 옵션들입니다:

locale

위젯 UI의 언어를 설정합니다. FastComments는 수십 개의 언어를 지원합니다.

구성 예제

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // 스페인어
});

readonly

모든 대화를 읽기 전용으로 만듭니다. 사용자는 기존 주석을 볼 수는 있지만 새로 만들거나 답글을 달 수는 없습니다.

구성 예제

Copy

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

sso and simpleSSO

싱글 사인온을 사용하여 인증 시스템과 통합합니다.

구성 예제

Copy

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

인증 옵션에 대한 전체 세부사항은 SSO 문서를 참조하세요.

maxReplyDepth

답글의 중첩 수준을 제어합니다. 기본적으로 Collab Chat은 이를 0으로 설정하여 모든 댓글이 플랫(중첩 답글 없음)합니다. 스레드 대화를 원하면 이 값을 변경할 수 있습니다.

구성 예제

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    maxReplyDepth: 3  // 3단계 중첩 허용
});

내부 구성

이 옵션들은 Collab Chat에 의해 자동으로 설정되며 재정의해서는 안 됩니다:

The productId is automatically set to 3 for Collab Chat. The floating-chat extension is automatically loaded to provide the chat window functionality. The widget automatically detects mobile devices (screens under 768px wide) and adjusts the UI accordingly.

전체 예제

다음은 여러 구성 옵션을 함께 보여주는 예제입니다:

구성 예제

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초의 지연이 있습니다. 이는 사용자가 단순히 텍스트를 복사하거나 읽기 위해 강조 표시할 때 UI가 깜빡이는 것을 방지합니다. 모바일 기기에서는 터치 스크린에서의 텍스트 선택이 더 의도적이므로 프롬프트가 즉시 나타납니다.

Unique Conversation IDs

각 대화는 페이지 URL, DOM 요소 경로 및 직렬화된 텍스트 범위를 결합한 고유한 urlId를 부여받습니다. 이는 각 텍스트 선택이 나중에 다시 찾을 수 있는 별도의 대화를 생성하도록 보장합니다.

구성에서 사용자 지정 urlId를 제공하면, 최종 식별자를 만들기 위해 요소 경로 및 텍스트 범위와 결합됩니다.

Visual Highlights

특정 텍스트 선택에 대한 토론이 존재하면 해당 텍스트에 시각적 하이라이트가 적용됩니다. 하이라이트는 배경색을 사용하여 구현되며, 마우스를 올리거나 연결된 채팅 창이 열려 있을 때 나타납니다.

하이라이트 시스템은 선택된 텍스트를 스타일을 적용할 수 있는 특수 요소로 래핑하여 작동합니다. 이 접근 방식은 기본 HTML 구조가 복잡하더라도 하이라이트가 정확하게 유지되도록 보장합니다.

Chat Window Positioning

사용자가 하이라이트를 클릭하거나 새 주석을 생성하면 선택된 텍스트 근처에 채팅 창이 나타납니다. 위젯은 사용 가능한 뷰포트 공간을 기준으로 이 창의 최적 위치를 자동으로 계산합니다.

위치 지정 시스템은 채팅 창이 하이라이트에서 어느 방향으로 확장되어야 하는지를 나타내기 위해 to-right, to-left, to-top, to-bottom과 같은 CSS 클래스를 사용합니다. 모바일 기기(너비가 768px 미만인 화면)에서는 더 나은 사용성을 위해 채팅 창이 항상 전체 화면으로 표시됩니다.

Chat Window Dimensions

데스크톱에서는 채팅 창의 너비가 410px이고 20px 간격과 하이라이트된 텍스트를 가리키는 16px 크기의 시각적 화살표가 있습니다. 이러한 치수는 일관된 동작을 보장하기 위해 고정되어 있지만 CSS로 외형을 사용자화할 수 있습니다.

Cross-Element Selections

사용자는 하나의 단락 중간에서 다른 단락의 시작까지 하이라이트하는 등 여러 HTML 요소에 걸쳐 텍스트를 선택할 수 있습니다. 범위 직렬화 시스템은 이를 올바르게 처리하며 요소 경계를 넘는 모든 선택된 텍스트를 하이라이트합니다.

Browser Compatibility

텍스트 선택 시스템은 모든 최신 브라우저에서 지원되는 표준 window.getSelection() API를 사용합니다. 구형 Internet Explorer 버전에서는 호환성을 위해 document.selection으로 폴백됩니다.

Selection Persistence

텍스트 선택에 대한 대화가 생성되면 해당 주석은 페이지를 새로고침해도 지속됩니다. 직렬화된 범위와 DOM 경로를 통해 사용자가 페이지를 다시 방문했을 때 위젯이 정확히 동일한 위치에 하이라이트를 복원할 수 있습니다.

이 기능은 페이지 콘텐츠가 안정적으로 유지되는 한 신뢰할 수 있습니다. 텍스트 내용을 변경하거나 HTML을 재구성하면 기존 주석이 더 이상 텍스트와 정확히 일치하지 않을 수 있습니다. 이러한 이유로 활성 주석이 있는 페이지에서는 대규모 콘텐츠 변경을 피하거나, 콘텐츠 변경이 불가피한 경우 주석을 마이그레이션하는 방안을 고려하는 것이 좋습니다.

맞춤화

다크 모드 지원

동적 다크 모드

사이트의 다크 모드가 body 요소에 .dark 클래스를 추가하여 제어되는 경우, Collab Chat UI는 재초기화 없이 자동으로 이를 반영합니다. 위젯의 스타일은 이 클래스의 존재에 반응하도록 설계되어 있습니다.

다크 모드 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 위젯과 동일한 모든 지역화 옵션을 지원합니다. UI 텍스트를 다른 언어로 표시하려면 locale 옵션을 설정하세요:

로케일 설정

Copy

FastCommentsCollabChat(element, {
    tenantId: 'demo',
    locale: 'es'  // 스페인어
});

FastComments는 수십 개의 언어를 지원합니다. 로케일 설정은 프롬프트, 버튼 및 플레이스홀더 텍스트를 포함한 모든 UI 텍스트에 영향을 줍니다.

상속된 사용자 지정 옵션

Collab Chat은 표준 댓글 위젯을 확장하므로, 기본 위젯의 모든 사용자 지정 옵션을 상속합니다. 여기에는 사용자 지정 CSS 클래스, 사용자 지정 번역, 아바타 사용자 지정, 날짜 형식 지정 등 많은 항목이 포함됩니다.

사용 가능한 전체 사용자 지정 옵션 목록은 FastComments의 메인 사용자 지정 문서를 참조하세요.

사용자 지정 폰트 사용

사이트에서 사용자 지정 폰트를 사용하는 경우 Collab Chat UI는 페이지의 CSS에서 해당 폰트를 상속합니다. 플로팅 채팅 창이 동일한 폰트를 사용하도록 하려면 위젯 커스터마이제이션 규칙을 생성하고 해당 규칙의 커스텀 CSS에서 @import로 폰트를 포함해야 할 수 있습니다.

실시간 동기화

Real-Time Updates

Collab Chat는 WebSocket 연결을 사용하여 모든 대화를 실시간으로 동기화합니다. 누군가 새 주석을 작성하거나 댓글을 추가하거나 토론을 삭제하면 같은 페이지를 보고 있는 다른 모든 사용자는 새로고침 없이 즉시 업데이트를 확인합니다.

How WebSocket Sync Works

Collab Chat를 초기화하면 위젯은 FastComments 서버에 WebSocket 연결을 설정합니다. 이 연결은 사용자의 세션 동안 열려 있으며 현재 페이지와 관련된 업데이트를 수신 대기합니다.

WebSocket 시스템은 Collab Chat에 대해 세 가지 유형의 브로드캐스트 메시지를 사용합니다. new-text-chat 이벤트는 누군가 페이지에 새 주석을 작성할 때 발생합니다. updated-text-chat 이벤트는 누군가 기존 대화를 업데이트할 때 발생합니다. deleted-text-chat 이벤트는 누군가 주석을 삭제할 때 발생합니다.

Broadcast ID System

사용자가 자신의 동작이 다시 브로드캐스트되어 자신에게 되돌아오는 에코 효과를 방지하기 위해 각 업데이트에는 고유한 broadcastId가 포함됩니다. 사용자가 주석을 생성하거나 업데이트할 때 해당 클라이언트는 해당 작업에 대한 UUID를 생성합니다. WebSocket이 업데이트를 모든 클라이언트에 브로드캐스트하면, 원래 작업을 수행한 클라이언트는 자신의 broadcastId와 일치하기 때문에 해당 업데이트를 무시합니다.

이것은 사용자가 서버를 통한 왕복을 기다리지 않고도 UI에서 변경사항을 즉시 확인할 수 있도록 하면서도 다른 모든 사용자가 업데이트를 받도록 보장하여 원활한 상호작용을 제공합니다.

Live User Count

상단 바에는 현재 페이지를 보고 있는 사용자 수가 표시됩니다. 이 수치는 사용자가 들어오고 나감에 따라 실시간으로 업데이트됩니다. 사용자 수는 동일한 WebSocket 연결을 통해 제공되며 연결 및 연결 해제 이벤트에 따라 자동으로 증가/감소합니다.

Connection Resilience

네트워크 문제나 서버 유지 관리로 인해 WebSocket 연결이 끊어지면 위젯은 자동으로 다시 연결을 시도합니다. 재연결 기간 동안 사용자는 기존 주석과 상호작용할 수는 있지만 연결이 복구될 때까지 다른 사용자의 실시간 업데이트는 볼 수 없습니다.

다시 연결되면 위젯은 놓친 업데이트가 없는지 재동기화합니다. 이는 사용자의 개입 없이 투명하게 이루어집니다.

Bandwidth Considerations

WebSocket 메시지는 경량이며 상태를 동기화하는 데 필요한 최소한의 정보만 포함합니다. 새 주석을 만드는 데 일반적으로 1KB 미만의 대역폭이 사용됩니다. 시스템에는 활동이 많은 기간 동안 메시지 빈도를 줄이기 위한 지능형 배칭도 포함되어 있습니다.

FastComments 대시보드의 사용량 지표는 pubSubMessageCount 및 pubSubBandwidth를 추적하므로 사이트 전반의 실시간 동기화 활동을 모니터링할 수 있습니다.

Cross-Tab Synchronization

사용자가 동일한 페이지를 여러 브라우저 탭에서 열어둔 경우 한 탭에서의 업데이트는 다른 탭에 즉시 표시됩니다. 이는 동일한 WebSocket 동기화 메커니즘을 통해 작동하며 별도의 추가 구성은 필요하지 않습니다.

Security

WebSocket 메시지는 보안 연결(WSS)을 통해 전송되며 사용자가 권한이 있는 대화에 대한 업데이트만 수신하도록 테넌트 검증을 포함합니다. 서버는 무단 액세스나 조작을 방지하기 위해 브로드캐스트하기 전에 모든 작업을 검증합니다.

API 참조

API 개요

Collab Chat은 텍스트 대화를 프로그래밍 방식으로 관리하기 위한 세 개의 REST API 엔드포인트를 제공합니다. 이 엔드포인트를 사용하면 브라우저 위젯을 사용하지 않고도 주석을 검색, 생성 및 삭제할 수 있습니다.

이들은 브라우저 쿠키를 통해 사용자를 인증하는 공개 엔드포인트입니다. API 키를 사용하지 않습니다. 사용자는 이러한 엔드포인트에 액세스하려면 브라우저에서 FastComments에 로그인되어 있어야 합니다.

기본 URL

모든 Collab Chat API 엔드포인트는 다음 하위에 있습니다:

기본 URL

Copy

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

인증

이 엔드포인트들은 브라우저 쿠키를 통해 사용자를 인증합니다. API 키를 사용하지 않습니다. 사용자는 이러한 엔드포인트에 액세스하려면 브라우저에서 FastComments에 로그인되어 있어야 합니다.

모든 대화 가져오기

특정 페이지에 대한 모든 텍스트 대화를 검색합니다.

엔드포인트

GET 엔드포인트

Copy

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

매개변수

tenantId (경로 매개변수, 필수)는 귀하의 FastComments Tenant ID입니다.

urlId (쿼리 매개변수, 필수)는 대화를 검색하려는 페이지 식별자입니다.

응답

응답에는 API 상태, 인증된 경우 현재 사용자 세션 정보, ID, URL 및 텍스트 범위가 포함된 대화 배열, 정리된 URL 식별자, 현재 사용자가 사이트 관리자 또는 중재자인지 여부를 나타내는 플래그, 그리고 실시간 동기화를 위한 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 (경로 매개변수, 필수)는 귀하의 FastComments Tenant ID입니다.

요청 본문은 JSON이어야 하며 다음 필수 필드를 포함해야 합니다.

urlId (string, 필수)는 기본 페이지 식별자입니다.

urlIdWithRange (string, 필수)는 텍스트 범위가 결합된 URL로, 예를 들어 my-page:p:0:15,0:45{abc123}와 같습니다.

pageTitle (string, 필수)는 페이지 제목입니다.

selector (string, 필수)는 선택된 텍스트를 포함하는 요소의 DOM 경로입니다.

range (string, 필수)는 직렬화된 텍스트 범위로 형식은 startOffset:endOffset,startOffset:endOffset{checksum}입니다.

createdFromCommentId (string, 필수)는 이 채팅을 시작한 댓글의 ID입니다.

broadcastId (string, 필수)는 에코 효과를 방지하기 위한 실시간 동기화용 UUID입니다.

응답

응답에는 API 상태와 새로 생성된 대화의 ID가 포함됩니다.

예시 요청

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"
}

대화 삭제

기존 텍스트 대화를 삭제합니다. 이 엔드포인트는 관리자 또는 중재자 권한이 필요하거나 대화가 인증된 사용자가 생성한 경우에만 허용됩니다.

엔드포인트

DELETE 엔드포인트

Copy

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

매개변수

tenantId (경로 매개변수, 필수)는 귀하의 FastComments Tenant ID입니다.

chatId (경로 매개변수, 필수)는 삭제하려는 대화의 ID입니다.

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"
}

요청 제한

이들 엔드포인트는 표준 FastComments API 요청 제한의 적용을 받습니다. 요청 제한 미들웨어는 정상적인 사용 패턴을 허용하면서 남용을 방지하기 위해 테넌트별로 적용됩니다.

오류 응답

모든 엔드포인트는 표준 HTTP 상태 코드를 반환합니다. 400 응답은 잘못된 요청 매개변수를 나타냅니다. 401 응답은 인증 실패를 의미합니다. 403 응답은 권한 부족을 나타냅니다. 404 응답은 대화를 찾을 수 없음을 의미합니다. 429 응답은 요청 한도 초과를 나타냅니다.

오류 응답에는 세부 정보가 포함된 JSON 본문이 포함됩니다:

오류 응답 예시

Copy

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

사용량 추적

대화를 생성하면 conversationCreateCount 사용량 지표가 증가합니다. 모든 WebSocket 동기화 활동은 pubSubMessageCount 및 pubSubBandwidth를 증가시킵니다. 이러한 지표는 FastComments 대시보드의 사용량 분석에서 모니터링할 수 있습니다.

질문 있으신가요?

FastComments Collab Chat은 여기까지입니다! 질문이 있으시거나 구현에 대한 도움이 필요하시거나 기능 제안이 있으시면 아래에 알려주시거나 지원팀에 연락해 주세요.

실제 예제를 보려면 Collab Chat을 프로덕션에서 사용하는 Govscent.org를 확인해 보세요.

언어 🇰🇷 한국어

시작하기

구성

맞춤화

고급

문서, 책 등에서 인라인 실시간 댓글 추가하기

시작하기

빠른 시작

설치

기본 구현

작동 방식

라이브 데모

다음 단계

프론트엔드 라이브러리

예제

기본 예제

맞춤 URL ID 예제 (책 페이지, 기사 등)

다크 모드 예제

상단 바 비활성화 예제

댓글 수 콜백 예제

여러 섹션 예제

온라인 도서에 실시간 댓글 추가

구성 옵션

개요

필수 구성

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로 사용자 지정 스타일

상단 바 사용자 지정

모바일 동작

채팅 창 외형

지역화

상속된 사용자 지정 옵션

사용자 지정 폰트 사용

실시간 동기화

Real-Time Updates

How WebSocket Sync Works

Broadcast ID System

Live User Count

Connection Resilience

Bandwidth Considerations

Cross-Tab Synchronization

Security

API 참조

API 개요

기본 URL

인증

모든 대화 가져오기

엔드포인트

매개변수

응답

예시 요청

예시 응답

대화 생성

엔드포인트

매개변수