Collab Chat | FastComments Docs

ドキュメント、書籍などにインラインのライブコメントを追加する

FastComments Collab Chat により、ユーザーはウェブサイト上の任意のテキストをハイライトして注釈を付けることができ、特定のテキスト選択に紐づいたスレッド形式の議論を作成できます。ユーザーは単語、文、または段落全体を選択して、コンテンツ内で直接協働的な会話を開始できます。

この機能は、編集上のフィードバック、協働読書環境、教育プラットフォーム、ドキュメントレビュー、特定のテキストに紐づいた文脈的な議論を行いたいあらゆるシナリオに最適です。

これらのドキュメントは Collab Chat 機能に特化していることに注意してください。ページ数の多いコンテンツ（Books など）に対しては、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>
    <!-- コンテンツコンテナ -->
    <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 に置き換えてください。Tenant ID は FastComments ダッシュボードで確認できます。

仕組み

初期化が完了すると、ユーザーはターゲット要素内の任意のテキストを選択できます。短い遅延の後（デスクトップでは約 3.5 秒）、ディスカッションを開始できるプロンプトが表示されます。ディスカッションが作成されると、選択したテキストに視覚的なハイライトが表示されます。他のユーザーはそのハイライトにカーソルを合わせるかクリックしてディスカッションを表示・参加できます。すべてのディスカッションはすべての訪問者間でリアルタイムに同期されます。

ライブデモ

Collab Chat の動作は当社のライブデモページでご覧いただけます。

次のステップ

基本が動作するようになったら、Configuration Options ガイドで外観や動作をカスタマイズできます。Text Selection Behavior ガイドでテキスト選択の仕組みを確認してください。カスタマイズとダークモードのサポートについては Customization ガイドをご覧ください。高度な統合については API Reference を参照してください。

フロントエンドライブラリ

すべての 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 を指定できます:

カスタム URL ID を使用した Collab Chat

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

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>
    // intro セクションを初期化
    FastCommentsCollabChat(document.getElementById('intro-section'), {
        tenantId: 'demo',
        urlId: 'my-article-intro'
    });
    // main セクションを初期化
    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
});

For a complete list of all available configuration options inherited from the base widget, see the main FastComments configuration documentation.

テキスト選択の動作

テキスト選択の仕組み

ユーザーが Collab Chat コンテナ内でテキストを選択すると、ウィジェットはその選択を取得し、ディスカッションを開始できるようにします。選択は単語1つほどの小さなものから、複数の要素にまたがる段落全体のような大きなものまで可能です。

選択遅延

デスクトップでは、ユーザーがテキストを選択してからディスカッションのプロンプトが表示されるまでに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 にフォールバックします。

選択の永続性

テキスト選択に対して会話が作成されると、その注釈はページをリロードしても持続します。シリアライズされた範囲と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 によってフォントを読み込む必要があるかもしれません。

ライブ同期

リアルタイム更新

Collab Chat は WebSocket 接続を使用して、接続されているすべてのユーザー間で会話をリアルタイムに同期します。誰かが新しい注釈を作成したり、コメントを追加したり、ディスカッションを削除したりすると、同じページを表示している他のユーザーはページを再読み込みすることなく即座にその更新を確認できます。

WebSocket 同期の仕組み

Collab Chat を初期化すると、ウィジェットは FastComments サーバーへの WebSocket 接続を確立します。この接続はユーザーのセッションの間開いたままになり、現在のページに関連する更新を監視します。

WebSocket システムは Collab Chat 用に3種類のブロードキャストメッセージを使用します。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 リファレンス

APIの概要

Collab Chat は、テキスト会話をプログラムで管理するための3つのREST APIエンドポイントを提供します。これらのエンドポイントを使用すると、ブラウザウィジェットを使わずにアノテーションの取得、作成、削除が可能です。

これらはブラウザのCookieでユーザーを認証する公開エンドポイントです。APIキーは使用しません。これらのエンドポイントにアクセスするには、ユーザーがブラウザでFastCommentsにログインしている必要があります。

ベースURL

すべての Collab Chat API エンドポイントは以下の下にあります。

ベースURL

Copy

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

認証

これらのエンドポイントはブラウザのCookieでユーザーを認証します。APIキーは使用しません。これらのエンドポイントにアクセスするには、ユーザーがブラウザでFastCommentsにログインしている必要があります。

すべての会話を取得

特定のページに対するすべてのテキスト会話を取得します。

エンドポイント

GETエンドポイント

Copy

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

パラメータ

tenantId (パスパラメータ、必須) はあなたの FastComments テナント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 テナント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 テナント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

内部設定

完全な例

テキスト選択の動作

テキスト選択の仕組み

選択遅延

一意の会話ID

視覚的ハイライト

チャットウィンドウの位置決め

チャットウィンドウの寸法

複数要素にまたがる選択

ブラウザ互換性

選択の永続性

カスタマイズ

ダークモード対応

動的ダークモード

CSSによるカスタムスタイル

トップバーのカスタマイズ

モバイルでの挙動

チャットウィンドウの外観

ローカリゼーション

継承されるカスタマイズオプション

カスタムフォントの利用

ライブ同期

リアルタイム更新

WebSocket 同期の仕組み

ブロードキャストIDシステム

ライブユーザー数

接続の回復性

帯域幅に関する考慮

タブ間同期

セキュリティ

API リファレンス

APIの概要

ベースURL

認証

すべての会話を取得

エンドポイント

パラメータ

レスポンス

リクエスト例

レスポンス例

会話を作成

エンドポイント

パラメータ