FastComments.com

Menu Icon

언어 🇰🇷 한국어
🇺🇸 English 🇧🇬 Български 🇨🇳 简体中文 🇹🇼 繁體中文 🇭🇷 Hrvatski 🇩🇰 Dansk 🇳🇱 Nederlands 🇫🇷 Français (France) 🇩🇪 Deutsch 🇬🇷 Ελληνικά 🇮🇱 עברית 🇮🇳 हिन्दी 🇮🇹 Italiano 🇯🇵 日本語 🇰🇷 한국어 🇵🇱 Polski 🇧🇷 Português (Brasil) 🇷🇺 Русский 🇷🇸 Srpski (Latinica) 🇷🇸 Српски 🇸🇮 Slovenščina 🇪🇸 Español 🇺🇦 Українська 🇹🇷 Türkçe

시작하기

시작하기
예제
온라인 도서에 실시간 댓글 추가

구성

구성 옵션
텍스트 선택 동작

맞춤화

맞춤화

고급

실시간 동기화
API 참조

콜랩 챗

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

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.

시작하기 Internal Link

빠른 시작

Collab Chat을 시작하는 것은 간단합니다. FastComments Collab Chat 스크립트, 주석을 달고자 하는 텍스트를 포함한 HTML 요소, 그리고 Tenant ID가 포함된 구성 객체가 필요합니다.

설치

페이지에 Collab Chat 스크립트를 추가하세요:

Collab Chat 스크립트 로드
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
3

기본 구현

간단한 예제는 다음과 같습니다:

기본 Collab Chat 구현
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat</title>
6</head>
7<body>
8 <!-- 콘텐츠 컨테이너 -->
9 <div id="article-content" style="min-height: 500px;">
10 <h1>My Article Title</h1>
11 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
12 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
13 </div>
14
15 <!-- Collab Chat 스크립트 로드 -->
16 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
17
18 <!-- Collab Chat 초기화 -->
19 <script>
20 FastCommentsCollabChat(document.getElementById('article-content'), {
21 tenantId: 'demo'
22 });
23 </script>
24</body>
25</html>
26

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

작동 방식

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

라이브 데모

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

다음 단계

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

프론트엔드 라이브러리

모든 FastComments 프론트엔드 라이브러리(react, vue, angular 등)는 Collab Chat을 포함하고 있습니다.

예제 Internal Link

기본 예제

Collab Chat을 사용하는 가장 간단한 방법은 단일 콘텐츠 컨테이너를 대상으로 하는 것입니다. 이 예제는 기사에 텍스트 주석 기능을 활성화하는 방법을 보여줍니다:

기본 Collab Chat 예제
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat</title>
6</head>
7<body>
8 <div id="article-content" style="min-height: 500px">
9 <h1>My Article Title</h1>
10 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
11 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
12 </div>
13
14 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
15 <script>
16 FastCommentsCollabChat(document.getElementById('article-content'), {
17 tenantId: 'demo'
18 });
19 </script>
20</body>
21</html>
22

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

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

Collab Chat with Custom URL ID
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
3<script>
4 FastCommentsCollabChat(document.getElementById('article-content'), {
5 tenantId: 'demo',
6 urlId: 'book-one-page-2'
7 });
8</script>
9

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

다크 모드 예제

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

Collab Chat with Dark Mode
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat - Dark Mode</title>
6 <style>
7 body {
8 background-color: #1a1a1a !important;
9 color: #e0e0e0 !important;
10 font-family: system-ui, -apple-system, sans-serif;
11 padding: 20px;
12 margin: 0;
13 }
14 #article-content {
15 max-width: 800px;
16 margin: 0 auto;
17 background-color: #2d2d2d;
18 padding: 20px;
19 border-radius: 8px;
20 }
21 h1 {
22 color: #ffffff !important;
23 }
24 p {
25 color: #e0e0e0 !important;
26 line-height: 1.6;
27 }
28 .fastcomments-collab-chat-top-bar {
29 background-color: #2d2d2d !important;
30 color: #e0e0e0 !important;
31 border-bottom: 1px solid #444 !important;
32 }
33 </style>
34</head>
35<body>
36 <div id="article-content" style="min-height: 500px">
37 <h1>My Article Title</h1>
38 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
39 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
40 </div>
41
42 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
43 <script>
44 FastCommentsCollabChat(document.getElementById('article-content'), {
45 tenantId: 'demo',
46 hasDarkBackground: true
47 });
48 </script>
49</body>
50</html>
51

상단 바 비활성화 예제

기본적으로 Collab Chat은 사용자 수 및 토론 수가 표시된 상단 바를 표시합니다. 이를 비활성화할 수 있습니다:

Collab Chat with Top Bar Disabled
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Article with Collab Chat - No Top Bar</title>
6</head>
7<body>
8 <div id="article-content" style="min-height: 500px">
9 <h1>My Article Title</h1>
10 <p>This is a paragraph that users can annotate. Simply highlight any text to start a discussion!</p>
11 <p>You can have multiple paragraphs, and users can highlight text across any of them.</p>
12 </div>
13
14 <script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
15 <script>
16 FastCommentsCollabChat(document.getElementById('article-content'), {
17 tenantId: 'demo',
18 topBarTarget: null
19 });
20 </script>
21</body>
22</html>
23

댓글 수 콜백 예제

commentCountUpdated 콜백을 사용하여 댓글이 추가되거나 업데이트될 때를 추적할 수 있습니다:

Collab Chat with Comment Count Callback
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
3<script>
4 FastCommentsCollabChat(document.getElementById('article-content'), {
5 tenantId: 'demo',
6 commentCountUpdated: function(count) {
7 console.log('Total comments:', count);
8 document.getElementById('comment-badge').textContent = count;
9 }
10 });
11</script>
12

여러 섹션 예제

페이지의 여러 개별 섹션에서 Collab Chat을 초기화할 수 있습니다. 각 섹션은 자체적인 독립된 주석을 가집니다:

Collab Chat on Multiple Sections
Copy Copy
1
2<div id="intro-section">
3 <h2>Introduction</h2>
4 <p>Content for the introduction...</p>
5</div>
6
7<div id="main-section">
8 <h2>Main Content</h2>
9 <p>Content for the main article...</p>
10</div>
11
12<script src="https://cdn.fastcomments.com/js/embed-collab-chat.min.js"></script>
13<script>
14 // 소개 섹션에서 초기화
15 FastCommentsCollabChat(document.getElementById('intro-section'), {
16 tenantId: 'demo',
17 urlId: 'my-article-intro'
18 });
19
20 // 본문 섹션에서 초기화
21 FastCommentsCollabChat(document.getElementById('main-section'), {
22 tenantId: 'demo',
23 urlId: 'my-article-main'
24 });
25</script>
26

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

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

구성 옵션 Internal Link

개요

FastComments Collab Chat은 표준 FastComments 댓글 위젯을 확장한 것이므로, 기본 위젯의 모든 설정 옵션을 상속하면서 텍스트 주석(Annotation)에 특화된 몇 가지 옵션을 추가합니다.

필수 설정

tenantId

FastComments Tenant ID가 필요합니다. FastComments 대시보드에서 확인할 수 있습니다.

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo'
4});
5

Collab Chat 전용 옵션

urlId

기본적으로 Collab Chat은 페이지 URL, 요소의 DOM 경로, 선택된 텍스트 범위를 기반으로 각 대화에 대한 고유 식별자를 생성합니다. 사용자 지정 urlId로 이를 재정의할 수 있습니다.

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 urlId: 'my-custom-page-id'
5});
6

URL 구조가 변경될 수 있지만 동일한 대화를 유지하고 싶거나, 여러 페이지에서 주석을 공유하고 싶을 때 유용합니다.

topBarTarget

사용자 수와 토론 수를 표시하는 상단 바의 표시를 제어합니다. null로 설정하면 상단 바를 완전히 비활성화하고, DOM 요소를 제공하면 특정 위치에 렌더링합니다.

설정 예시
Copy Copy
1
2// Disable top bar
3FastCommentsCollabChat(element, {
4 tenantId: 'demo',
5 topBarTarget: null
6});
7
8// Render top bar in custom location
9FastCommentsCollabChat(element, {
10 tenantId: 'demo',
11 topBarTarget: document.getElementById('custom-header')
12});
13

hasDarkBackground

페이지에 어두운 배경이 있을 때 다크 모드 스타일을 활성화합니다. 이 감지는 자동으로 이루어지지만, 필요에 따라 재정의할 수 있습니다.

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 hasDarkBackground: true
5});
6

commentCountUpdated

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

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 commentCountUpdated: function(count) {
5 console.log('Total comments:', count);
6 document.getElementById('badge').textContent = count;
7 }
8});
9

상속된 설정 옵션

Collab Chat은 표준 댓글 위젯을 확장한 것이므로, 기본 FastComments 위젯의 모든 설정 옵션을 사용할 수 있습니다. 자주 사용되는 옵션은 다음과 같습니다:

locale

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

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // Spanish
5});
6

readonly

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

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 readonly: true
5});
6

sso and simpleSSO

Single Sign-On을 사용하여 인증 시스템과 통합합니다.

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 sso: {
5 // SSO configuration
6 }
7});
8

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

maxReplyDepth

답글이 몇 단계까지 중첩될 수 있는지 제어합니다. 기본적으로 Collab Chat은 이 값을 0으로 설정하여 모든 댓글이 평면적(중첩된 답글 없음)이 되도록 합니다. 스레드 형태의 대화를 원하면 이 값을 변경할 수 있습니다.

설정 예시
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 maxReplyDepth: 3 // Allow 3 levels of nesting
5});
6

내부 설정

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

productId는 Collab Chat을 위해 자동으로 3으로 설정됩니다. 채팅 창 기능을 제공하기 위해 floating-chat 확장이 자동으로 로드됩니다. 위젯은 모바일 기기(너비 768px 미만 화면)를 자동으로 감지하여 그에 맞게 UI를 조정합니다.

전체 예시

여러 설정 옵션을 함께 사용하는 예시입니다:

설정 예시
Copy Copy
1
2FastCommentsCollabChat(document.getElementById('article'), {
3 tenantId: 'demo',
4 urlId: 'my-article-v2',
5 hasDarkBackground: false,
6 locale: 'en',
7 topBarTarget: document.getElementById('custom-header'),
8 commentCountUpdated: function(count) {
9 document.title = count > 0 ? `(${count}) My Article` : 'My Article';
10 },
11 sso: {
12 // Your SSO config
13 },
14 maxReplyDepth: 1
15});
16

기본 위젯에서 상속된 사용 가능한 모든 설정 옵션의 전체 목록은 FastComments 기본 설정 문서를 참조하세요.

텍스트 선택 동작 Internal Link

텍스트 선택 작동 방식

사용자가 Collab Chat 컨테이너 내에서 텍스트를 선택하면, 위젯이 해당 선택을 캡처하여 토론을 시작할 수 있도록 합니다. 선택 범위는 단일 단어만큼 작을 수도 있고, 서로 다른 요소에 걸친 여러 문단만큼 클 수도 있습니다.

선택 지연

데스크톱 기기에서는 사용자가 텍스트를 선택한 후 토론 프롬프트가 나타나기까지 3.5초의 지연이 있습니다. 이는 사용자가 단순히 복사하거나 읽기 위해 텍스트를 강조할 때 UI가 깜빡이는 것을 방지합니다. 모바일 기기에서는 터치 스크린에서 텍스트 선택이 더 신중하게 이루어지기 때문에 프롬프트가 즉시 나타납니다.

고유 대화 ID

각 대화에는 페이지 URL, DOM 요소 경로, 직렬화된 텍스트 범위를 결합한 고유한 urlId가 부여됩니다. 이를 통해 각 텍스트 선택이 나중에 다시 찾을 수 있는 별개의 대화를 생성합니다.

설정에서 사용자 지정 urlId를 제공하면, 요소 경로 및 텍스트 범위와 결합되어 최종 식별자가 생성됩니다.

시각적 하이라이트

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

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

채팅 창 위치 지정

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

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

채팅 창 크기

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

요소 간 선택

사용자는 여러 HTML 요소에 걸친 텍스트를 선택할 수 있습니다. 예를 들어 한 문단의 중간부터 다른 문단의 시작 부분까지 강조하는 경우입니다. 범위 직렬화 시스템이 이를 올바르게 처리하며, 요소 경계를 넘어서도 선택된 모든 텍스트를 하이라이트합니다.

브라우저 호환성

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

선택 영역 유지

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

이는 페이지 콘텐츠가 안정적으로 유지되는 한 신뢰할 수 있게 작동합니다. 텍스트 콘텐츠를 변경하거나 HTML 구조를 재구성하면 기존 주석이 텍스트와 더 이상 올바르게 정렬되지 않을 수 있습니다. 따라서 활성 주석이 있는 페이지에서는 주요 콘텐츠 변경을 피하거나, 콘텐츠 변경이 필요한 경우 주석 마이그레이션을 고려하는 것이 좋습니다.

맞춤화 Internal Link

다크 모드 지원

동적 다크 모드

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

다크 모드 CSS 예제
Copy Copy
1
2/* 다크 모드 CSS */
3body.dark {
4 background: #1a1a1a;
5 color: #ffffff;
6}
7

CSS로 사용자 지정 스타일

하이라이트, 채팅 창 및 기타 요소의 외형을 CSS로 사용자 지정할 수 있습니다. 위젯은 스타일시트에서 타겟팅할 수 있는 특정 클래스를 추가합니다.

텍스트 하이라이트는 FastComments의 댓글 버블 스타일링 시스템을 사용하므로, 표준 댓글 위젯에 적용한 모든 사용자 정의는 Collab Chat에도 영향을 미칩니다.

상단 바 사용자 지정

상단 바에는 온라인 사용자 수와 토론 수가 표시됩니다. topBarTarget으로 커스텀 요소를 제공하여 위치를 사용자 지정할 수 있습니다:

사용자 정의 상단 바 위치
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: document.getElementById('my-custom-header')
5});
6

또는 null로 설정하여 완전히 비활성화할 수 있습니다:

상단 바 비활성화
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 topBarTarget: null
5});
6

모바일 동작

화면 너비가 768px 미만인 경우 Collab Chat은 자동으로 모바일 최적화 레이아웃으로 전환합니다. 채팅 창은 텍스트 옆에 떠 있지 않고 전체 화면으로 표시되며, 더 즉각적인 상호작용을 위해 선택 지연이 제거됩니다.

이 동작은 내장되어 있으며 별도의 구성은 필요하지 않습니다. 위젯은 화면 크기를 자동으로 감지하고 그에 따라 조정합니다.

채팅 창 외형

채팅 창은 데스크톱에서 너비가 410px이고, 하이라이트된 텍스트를 가리키는 16px 화살표가 있습니다. 창은 뷰포트의 사용 가능한 공간에 따라 자동으로 위치를 지정하며, to-right, to-left, to-top, to-bottom 같은 위치 지정 클래스를 사용합니다.

이 창들의 색상, 글꼴, 간격 또는 기타 시각적 속성을 조정하기 위해 사용자 지정 CSS를 추가할 수 있습니다. 채팅 창은 표준 FastComments 위젯과 동일한 컴포넌트 구조를 사용하므로 전역 사용자 지정도 상속됩니다.

지역화

Collab Chat은 표준 FastComments 위젯과 동일한 모든 지역화 옵션을 지원합니다. UI 텍스트를 다른 언어로 표시하려면 locale 옵션을 설정하세요:

로케일 설정
Copy Copy
1
2FastCommentsCollabChat(element, {
3 tenantId: 'demo',
4 locale: 'es' // 스페인어
5});
6

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

상속된 사용자 지정 옵션

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

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

사용자 지정 폰트 사용

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

실시간 동기화 Internal Link

실시간 업데이트

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

WebSocket 동기화 작동 방식

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

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

브로드캐스트 ID 시스템

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

이를 통해 사용자는 서버를 왕복하는 것을 기다리지 않고 UI에서 자신의 변경 사항을 즉시 확인할 수 있으며, 동시에 다른 모든 사용자도 업데이트를 받을 수 있습니다.

실시간 사용자 수

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

연결 복원력

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

재연결되면 위젯이 재동기화하여 누락된 업데이트가 없도록 합니다. 이 과정은 사용자 개입 없이 투명하게 이루어집니다.

대역폭 고려 사항

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

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

크로스 탭 동기화

사용자가 같은 페이지를 여러 브라우저 탭에서 열어 두면, 한 탭의 업데이트가 다른 탭에 즉시 나타납니다. 이는 동일한 WebSocket 동기화 메커니즘을 통해 작동하며 추가 설정이 필요하지 않습니다.

보안

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

API 참조 Internal Link

API 개요

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

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

기본 URL

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

기본 URL
Copy Copy
1
2https://fastcomments.com/comment-collab-chats
3

인증

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

모든 대화 가져오기

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

엔드포인트

GET 엔드포인트
Copy Copy
1
2GET /comment-collab-chats/:tenantId?urlId=<urlId>
3

매개변수

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

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

응답

응답에는 API 상태, 인증된 경우 현재 사용자 세션 정보, ID, URL 및 텍스트 범위가 포함된 대화 배열, 정리된 URL 식별자, 현재 사용자가 사이트 관리자 또는 중재자인지 여부를 나타내는 플래그, 그리고 실시간 동기화를 위한 WebSocket 연결 세부정보(tenantIdWS, urlIdWS, 및 userIdWS)가 포함됩니다.

예시 요청

GET 요청 예시
Copy Copy
1
2curl "https://fastcomments.com/comment-collab-chats/demo?urlId=my-article-page" \
3 --cookie "your-session-cookie"
4

예시 응답

GET 응답 예시
Copy Copy
1
2{
3 "status": "success",
4 "user": {
5 "id": "user123",
6 "username": "john_doe"
7 },
8 "conversations": [
9 {
10 "_id": "conv123",
11 "urlId": "my-article-page:p:0:15,0:45{abc123}",
12 "range": "0:15,0:45{abc123}"
13 },
14 {
15 "_id": "conv456",
16 "urlId": "my-article-page:h1:5:20,5:35{def456}",
17 "range": "5:20,5:35{def456}"
18 }
19 ],
20 "urlIdClean": "my-article-page",
21 "isSiteAdmin": false,
22 "tenantIdWS": "demo",
23 "urlIdWS": "my-article-page",
24 "userIdWS": "user123"
25}
26

대화 생성

특정 텍스트 선택에 대해 새 텍스트 대화를 생성합니다.

엔드포인트

POST 엔드포인트
Copy Copy
1
2POST /comment-collab-chats/:tenantId
3

매개변수

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 Copy
1
2curl -X POST "https://fastcomments.com/comment-collab-chats/demo" \
3 --cookie "your-session-cookie" \
4 -H "Content-Type: application/json" \
5 -d '{
6 "urlId": "my-article-page",
7 "urlIdWithRange": "my-article-page:p:0:15,0:45{abc123}",
8 "pageTitle": "My Article Title",
9 "selector": "div#article > p:nth-child(2)",
10 "range": "0:15,0:45{abc123}",
11 "createdFromCommentId": "comment789",
12 "broadcastId": "550e8400-e29b-41d4-a716-446655440000"
13 }'
14

예시 응답

POST 응답 예시
Copy Copy
1
2{
3 "status": "success",
4 "createdChatId": "conv789"
5}
6

대화 삭제

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

엔드포인트

DELETE 엔드포인트
Copy Copy
1
2DELETE /comment-collab-chats/:tenantId/:chatId
3

매개변수

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

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

broadcastId (요청 본문, 필수)는 실시간 동기화를 위한 UUID입니다.

예시 요청

DELETE 요청 예시
Copy Copy
1
2curl -X DELETE "https://fastcomments.com/comment-collab-chats/demo/conv789" \
3 --cookie "your-session-cookie" \
4 -H "Content-Type: application/json" \
5 -d '{
6 "broadcastId": "550e8400-e29b-41d4-a716-446655440001"
7 }'
8

예시 응답

DELETE 응답 예시
Copy Copy
1
2{
3 "status": "success"
4}
5

요청 제한

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

오류 응답

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

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

오류 응답 예시
Copy Copy
1
2{
3 "status": "error",
4 "message": "Conversation not found"
5}
6

사용량 추적

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

질문 있으신가요?

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

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

이 가이드에 기여하기