Image Chat | FastComments Docs

FastComments Image Chat는 사용자가 이미지의 아무 곳이나 클릭하여 토론 지점을 만들 수 있도록 하여 이미지에 대한 대화형 토론을 가능하게 합니다. 사용자는 이미지의 특정 부분을 클릭하여 해당 영역에 대한 대화를 시작할 수 있으며, 토론이 위치한 곳을 보여주는 시각적 마커를 생성합니다.

이 기능은 디자인 피드백, 제품 리뷰, 다이어그램이 포함된 교육 자료, 주석이 달린 사진 갤러리 및 특정 이미지 위치에 고정된 맥락적 토론을 원하는 모든 시나리오에 적합합니다.

시작하기

사용 사례

Image Chat는 팀이 목업이나 스크린샷의 특정 요소에 대해 논의해야 할 때 디자인 피드백에 매우 적합합니다. 제품 리뷰 사이트에서는 고객이 제품 사진에서 보이는 특정 기능에 대해 토론할 수 있습니다. 교육 플랫폼은 다이어그램, 지도 또는 과학 이미지에 대해 토론하는 데 사용할 수 있습니다. 사진 갤러리는 위치별 주석으로 인터랙티브해질 수 있습니다. 부동산 사이트에서는 방문자가 부동산 사진에서 보이는 특정 특징에 대해 논의할 수 있습니다.

빠른 시작

Image Chat 시작은 간단합니다. FastComments Image Chat 스크립트, 이미지가 포함된 이미지 요소나 컨테이너, 그리고 Tenant ID가 포함된 구성 객체가 필요합니다.

설치

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

Image Chat 스크립트 로드

Copy

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

기본 구현

Here's a minimal example:

기본 Image Chat 구현

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>My Image Gallery with Image Chat</title>
</head>
<body>
    <!-- 이미지 -->
    <img id="my-image" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Pretty Trail" />
    <!-- Image Chat 스크립트 로드 -->
    <script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
    <!-- Image Chat 초기화 -->
    <script>
        FastCommentsImageChat(document.getElementById('my-image'), {
            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 대시보드.

작동 방식

초기화되면 사용자는 이미지의 아무 곳이나 클릭할 수 있습니다. 클릭이 발생하면 해당 위치에 시각적 정사각형 마커가 나타나고 채팅 창이 열립니다. 다른 사용자들도 모든 마커를 보고 클릭하여 해당 토론을 보거나 참여할 수 있습니다. 모든 토론은 방문자 전체에 걸쳐 실시간으로 동기화됩니다.

위젯은 백분율 기반 위치 지정을 사용하므로 이미지 크기가 조정되거나 다른 화면 크기에서 보더라도 마커는 올바른 위치에 유지됩니다.

라이브 데모

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

다음 단계

기본 기능이 작동하면 구성 옵션 가이드에서 모양과 동작을 사용자 지정할 수 있습니다. 반응형 디자인 가이드를 확인하여 백분율 기반 위치 지정이 어떻게 작동하는지 이해하세요. 맞춤 설정 가이드에서 스타일링 및 다크 모드 지원에 대해 알아보세요. 고급 통합은 API 레퍼런스를 참조하세요.

프런트엔드 라이브러리

모든 FastComments 프런트엔드 라이브러리(react, vue, angular 등)에 Image Chat이 포함되어 있습니다.

예제

기본 예제

Image Chat를 사용하는 가장 간단한 방법은 단일 이미지 요소를 대상으로 하는 것입니다. 이 예제는 이미지에서 인터랙티브한 토론을 활성화하는 방법을 보여줍니다:

기본 이미지 채팅 예제

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>Product Image with Chat</title>
</head>
<body>
    <img id="product-image" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Product Photo" />
    <script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
    <script>
        FastCommentsImageChat(document.getElementById('product-image'), {
            tenantId: 'demo'
        });
    </script>
</body>
</html>

컨테이너 요소 예제

이미지가 포함된 컨테이너 요소를 전달할 수도 있습니다:

컨테이너 포함 이미지 채팅

Copy

Run

<div id="image-container">
    <img src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="System Diagram" />
</div>
<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
<script>
    FastCommentsImageChat(document.getElementById('image-container'), {
        tenantId: 'demo'
    });
</script>

사용자 정의 URL ID 예제

기본적으로 Image Chat은 페이지 URL과 이미지 소스 및 좌표를 결합하여 대화를 식별합니다. 사용자 정의 urlId를 제공할 수 있습니다:

사용자 정의 URL ID 이미지 채팅

Copy

Run

<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
<script>
    FastCommentsImageChat(document.getElementById('product-image'), {
        tenantId: 'demo',
        urlId: 'product-v2-main-image'
    });
</script>

URL 구조가 변경되더라도 동일한 대화를 유지하거나 여러 페이지에서 동일한 토론 포인트를 공유하려는 경우 유용합니다.

다크 모드 예제

사이트에 어두운 배경이 있고 위젯이 자동으로 이를 감지하지 못하는 경우, 수동으로 다크 모드 지원을 활성화할 수 있습니다:

다크 모드 이미지 채팅

Copy

Run

<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
<script>
    FastCommentsImageChat(document.getElementById('product-image'), {
        tenantId: 'demo',
        hasDarkBackground: true
    });
</script>

사용자 지정 채팅 사각형 크기 예제

이미지에 표시되는 클릭 가능한 사각형의 크기를 조정할 수 있습니다. 크기는 이미지 너비의 백분율로 지정됩니다:

사용자 지정 사각형 크기 이미지 채팅

Copy

Run

<!DOCTYPE html>
<html>
<head>
    <title>Image Chat with Custom Square Size</title>
</head>
<body>
    <img id="product-image" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Product Photo" />
    <script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
    <script>
        FastCommentsImageChat(document.getElementById('product-image'), {
            tenantId: 'demo',
            chatSquarePercentage: 2, // 더 작은 사각형 (기본값은 5)
        });
    </script>
</body>
</html>

댓글 수 콜백 예제

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

댓글 수 콜백 이미지 채팅

Copy

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

여러 이미지 예제

여러 이미지에 대해 Image Chat을 초기화할 수 있습니다. 각 이미지는 자체 독립된 토론 지점을 갖습니다:

여러 이미지에서 이미지 채팅

Copy

Run

<img id="image-1" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Photo 1" />
<img id="image-2" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Photo 2" />
<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
<script>
    // 첫 번째 이미지에서 초기화
    FastCommentsImageChat(document.getElementById('image-1'), {
        tenantId: 'demo',
        urlId: 'gallery-photo-1'
    });
    // 두 번째 이미지에서 초기화
    FastCommentsImageChat(document.getElementById('image-2'), {
        tenantId: 'demo',
        urlId: 'gallery-photo-2'
    });
</script>

구성 옵션

개요

FastComments Image Chat는 표준 FastComments 댓글 위젯을 확장하여 기본 위젯의 모든 구성 옵션을 상속받으면서 이미지 주석에 특화된 몇 가지 옵션을 추가합니다.

필수 구성

tenantId

FastComments 테넌트 ID가 필요합니다. FastComments 대시보드에서 찾을 수 있습니다.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo'
});

Image Chat 전용 옵션

urlId

기본적으로 Image Chat은 페이지 URL, 이미지 소스 및 X/Y 좌표를 기반으로 각 대화에 대한 고유 식별자를 생성합니다. 사용자 정의 urlId로 이를 재정의할 수 있습니다.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    urlId: 'my-custom-image-id'
});

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

chatSquarePercentage

클릭 가능한 채팅 마커의 크기를 이미지 너비의 백분율로 제어합니다. 기본값은 5%이며, 각 마커가 이미지 너비의 5%를 의미합니다.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    chatSquarePercentage: 8  // 더 크고 더 잘 보이는 마커
});

작은 값은 덜 눈에 띄는 마커를 만들어 상세한 이미지에 더 적합합니다. 큰 값은 복잡한 이미지나 모바일 사용자가 볼 때 마커를 더 쉽게 보고 클릭할 수 있도록 합니다.

hasDarkBackground

페이지에 어두운 배경이 있는 경우 다크 모드 스타일을 활성화합니다.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    hasDarkBackground: true
});

commentCountUpdated

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

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

상속된 구성 옵션

Image Chat이 표준 댓글 위젯을 확장하므로 기본 FastComments 위젯의 모든 구성 옵션을 사용할 수 있습니다. 다음은 자주 사용하는 몇 가지 옵션입니다:

locale

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

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

readonly

모든 대화를 읽기 전용으로 만듭니다. 사용자는 기존 마커와 토론을 볼 수는 있지만 새로 생성하거나 답글을 달 수 없습니다.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    readonly: true
});

sso and simpleSSO

싱글 사인온(SSO)을 사용해 인증 시스템과 통합합니다.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    sso: {
        // SSO 구성
    }
});

인증 옵션에 대한 자세한 내용은 SSO 문서를 참조하세요.

maxReplyDepth

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

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    maxReplyDepth: 3  // 중첩을 3단계 허용
});

내부 구성

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

productId는 Image Chat용으로 자동으로 2로 설정됩니다. 채팅 창 기능을 제공하기 위해 floating-chat 확장이 자동으로 로드됩니다. 위젯은 모바일 기기(폭이 768px 미만인 화면)를 자동으로 감지하여 전체화면 채팅 창으로 UI를 조정합니다.

대상 요소 유연성

FastCommentsImageChat의 첫 번째 매개변수는 직접적인 <img> 요소이거나 그 안에 이미지가 있는 컨테이너 요소일 수 있습니다:

// 직접 이미지 요소
FastCommentsImageChat(document.getElementById('my-image'), config);

// 이미지가 포함된 컨테이너
FastCommentsImageChat(document.querySelector('.image-wrapper'), config);

컨테이너 요소를 전달하면 위젯이 자동으로 이미지를 찾아줍니다.

전체 예제

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

FastCommentsImageChat(document.getElementById('product-image'), {
    tenantId: 'demo',
    urlId: 'product-v2-main',
    chatSquarePercentage: 6,
    hasDarkBackground: false,
    locale: 'en',
    commentCountUpdated: function(count) {
        document.title = count > 0 ? `(${count}) Product Photo` : 'Product Photo';
    },
    sso: {
        // SSO 구성
    },
    maxReplyDepth: 1
});

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

반응형 디자인

백분율 기반 위치 지정

Image Chat는 이미지 위의 채팅 마커를 위치시키기 위해 픽셀 좌표 대신 백분율 기반 좌표를 사용합니다. 사용자가 이미지에서 클릭하면 위젯은 클릭의 픽셀 좌표를 이미지 너비와 높이의 백분율로 변환합니다. 이 방식은 이미지가 어떻게 표시되든 마커가 올바른 위치에 유지되도록 보장합니다.

예를 들어, 사용자가 너비가 1000px인 이미지의 왼쪽 가장자리에서 250픽셀 지점을 클릭하면 위젯은 이를 왼쪽에서 25%로 저장합니다. 다른 사용자가 모바일 기기에서 동일한 이미지를 너비 500px로 볼 때, 마커는 왼쪽에서 125픽셀 지점에 나타나며, 이는 여전히 너비의 25%입니다.

반응형 레이아웃에 대한 이점

이 백분율 시스템은 모든 기기 크기와 방향에서 Image Chat이 원활하게 작동하도록 합니다. 화면 너비, CSS 규칙, 또는 컨테이너 제약에 따라 이미지가 서로 다른 크기로 표시될 수 있지만, 마커는 항상 의도된 위치에 정확히 정렬됩니다.

대형 모니터를 사용하는 데스크톱 사용자는 소형 화면의 스마트폰 사용자가 보는 것과 동일한 상대적 위치에 마커를 봅니다. 마커는 이미지 자체와 비례하여 크기가 조정됩니다.

이미지 스케일링 및 종횡비

이미지가 스케일될 때 종횡비를 유지하는 한(이는 브라우저의 기본 동작입니다) 백분율 기반 마커는 완벽하게 정렬된 상태를 유지합니다. 위젯은 이미지가 비례적으로 스케일된다고 가정하고 이 가정에 기반해 위치를 계산합니다.

특정 치수와 함께 object-fit: cover와 같이 이미지 종횡비를 왜곡하는 CSS를 적용하면 마커 위치가 올바르게 정렬되지 않을 수 있습니다. 최상의 결과를 위해 이미지를 자연스럽게 스케일하도록 허용하거나 종횡비를 유지하기 위해 object-fit: contain을 사용하십시오.

채팅 사각형 크기

채팅 마커의 시각적 크기도 백분율 기반입니다. chatSquarePercentage 구성 옵션은 기본값이 5%이며, 이는 각 사각형이 이미지 너비의 5%임을 의미합니다. 이는 서로 다른 이미지 크기에서도 시각적 비중을 일관되게 유지합니다.

기본 5% 설정을 적용한 너비 1000px 이미지에서는 마커가 50px 정사각형입니다. 너비 500px 이미지에서는 동일한 마커가 25px 정사각형이 됩니다. 마커는 이미지 크기에 비례합니다.

모바일 동작

너비가 768px 미만인 화면에서는 Image Chat이 모바일 최적화 레이아웃으로 전환됩니다. 채팅 창은 마커 옆에 떠 있는 대신 전체 화면으로 열립니다. 이는 작은 화면에서 떠 있는 창이 이미지의 많은 부분을 가리는 문제를 줄여 더 나은 사용성을 제공합니다.

마커 자체는 여전히 백분율 기반 위치에 표시되고 클릭할 수 있습니다. 사용자는 모든 토론이 어디에 위치하는지 확인하고 마커를 탭하여 전체 화면 채팅 인터페이스를 열 수 있습니다.

동적 이미지 로딩

이미지가 비동기적으로 로드되거나 페이지 로드 후 크기가 변경되더라도 백분율 기반 시스템은 올바르게 작동합니다. 위젯은 이미지 요소를 감시하고 이미지 치수가 변경될 때마다 마커 위치를 재계산합니다.

이미지를 지연 로드하거나 서로 다른 브레이크포인트에서 다른 크기의 반응형 이미지를 구현하는 경우에도 이미지 크기가 변경되면 마커가 자동으로 조정됩니다.

기기 간 일관성

좌표가 데이터베이스에 백분율로 저장되므로 데스크톱에서 생성된 토론은 태블릿이나 휴대폰에서 볼 때도 정확히 동일한 상대적 위치에 나타납니다. 사용자는 위치 불일치 없이 여러 기기에서 협업할 수 있습니다.

이 동작은 양방향으로 작동합니다. 모바일 기기에서 특정 지점을 탭하여 생성한 토론은 대형 데스크톱 모니터에서 볼 때도 동일한 상대적 위치에 나타납니다.

뷰포트 고려사항

위젯은 뷰포트가 아니라 이미지 요소 자체를 기준으로 백분율을 계산합니다. 이는 페이지를 스크롤하거나 브라우저 창 크기를 변경해도 마커 위치에 영향을 주지 않음을 의미합니다. 마커는 뷰포트 변경과 무관하게 이미지상의 위치에 고정됩니다.

미래 대비 콘텐츠

백분율 기반 접근 방식은 레이아웃, 디자인 또는 기기 생태계의 변경에 대해 이미지 토론을 탄력적으로 만듭니다. 새로운 화면 크기와 기기가 등장하더라도 기존 토론은 업데이트나 마이그레이션 없이도 계속 올바르게 표시됩니다.

맞춤화

다크 모드 지원

Image Chat은 내장된 다크 모드 지원을 포함합니다. 구성에서 hasDarkBackground: true를 설정하면 채팅 창과 UI 요소가 자동으로 어두운 배경에 잘 어울리도록 조정됩니다.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    hasDarkBackground: true
});

다크 모드 스타일링은 채팅 창, 마커 사각형, 그리고 모든 인터랙티브 요소에 적용됩니다. 사이트에 다크 모드 토글이 있는 경우 모드가 변경될 때 위젯을 재초기화하거나 아래에 설명된 body 클래스 방식을 사용할 수 있습니다.

동적 다크 모드

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

/* 다크 모드 CSS */
body.dark {
    background: #1a1a1a;
    color: #ffffff;
}

CSS로 사용자 지정 스타일

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

채팅 사각형과 창은 FastComments의 댓글 버블 스타일 시스템을 사용하므로, 표준 댓글 위젯에 적용한 사용자 지정이 Image Chat에도 동일하게 영향을 미칩니다.

채팅 사각형 크기

chatSquarePercentage 옵션은 클릭 가능한 마커의 크기를 제어합니다. 기본값은 이미지 너비의 5%입니다:

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    chatSquarePercentage: 7  // 더 크고 더 눈에 띄는 사각형들
});

값이 작을수록 이미지에 더 은은하게 녹아드는 마커가 생성됩니다. 값이 클수록 특히 모바일 기기나 접근성 측면에서 마커가 더 눈에 띄고 클릭하기 쉬워집니다.

모바일 동작

가로 폭이 768px 미만인 화면에서는 Image Chat이 자동으로 모바일 최적화 레이아웃으로 전환됩니다. 채팅 창은 마커 옆에 떠 있는 대신 전체 화면으로 표시되어 작은 화면에서 더 나은 사용성을 제공합니다.

마커는 이미지에서 반응형 위치에 그대로 표시됩니다. 사용자는 어떤 마커든 탭하여 전체 화면 채팅 인터페이스를 열 수 있습니다. 이 동작은 내장되어 있으며 별도의 구성은 필요하지 않습니다.

채팅 창 모양

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

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

지연 초기화

채팅 창은 데스크톱 사용자의 경우 호버 시 또는 생성될 때 즉시 초기화됩니다. 이는 사용자가 실제로 마커와 상호작용할 때만 채팅 인터페이스를 렌더링함으로써 초기 로드 오버헤드를 줄여줍니다.

지연 초기화는 투명하게 발생합니다. 사용자는 지연을 느끼지 않지만, 이미지에 마커가 많은 경우 브라우저가 수십 개의 숨겨진 채팅 창을 렌더링할 필요가 없습니다.

지역화

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

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    locale: 'fr'  // 프랑스어
});

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

상속된 사용자 지정 옵션

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

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

사용자 정의 폰트 사용

사이트에서 사용자 정의 폰트를 사용하는 경우, Image Chat UI는 페이지의 CSS에서 해당 폰트를 상속합니다. 채팅 창은 페이지의 DOM 안에서 렌더링되며 기존 타이포그래피 설정을 준수합니다.

최상의 결과를 위해 Image Chat을 초기화하기 전에 사용자 정의 폰트가 로드되었는지 확인하거나, 폰트 로드 동안 스타일이 적용되지 않은 텍스트가 잠깐 보일 수 있음을 수용하세요.

마커 시각 디자인

사각형 마커는 이미지를 압도하지 않으면서 눈에 띄도록 미묘한 시각 디자인을 가지고 있습니다. 원하는 경우 CSS로 그들의 외관을 사용자 지정하여 다른 시각적 처리를 적용할 수 있습니다.

마커에는 사용자가 마우스를 올릴 때 피드백을 제공하는 호버 상태가 포함되어 있습니다. 터치 장치에서는 탭 상호작용이 채팅 창을 열어 즉각적인 피드백을 제공합니다.

실시간 동기화

Real-Time Updates

Image Chat은 모든 연결된 사용자 간에 모든 대화를 실시간으로 동기화하기 위해 WebSocket 연결을 사용합니다. 누군가 새로운 마커를 생성하거나 댓글을 추가하거나 토론을 삭제하면 동일한 이미지를 보고 있는 다른 모든 사용자는 새로 고침 없이 즉시 업데이트를 확인합니다.

How WebSocket Sync Works

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

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

Broadcast ID System

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

이렇게 하면 사용자는 서버를 통한 왕복을 기다리지 않고도 UI에서 변경 사항을 즉시 볼 수 있으면서 다른 모든 사용자에게는 업데이트가 전달되도록 하여 원활한 상호작용을 보장합니다.

Connection Resilience

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

재연결이 완료되면 위젯은 누락된 업데이트가 없도록 다시 동기화합니다. 이 작업은 사용자의 개입 없이 투명하게 발생합니다.

Bandwidth Considerations

WebSocket 메시지는 경량이며 상태 동기화에 필요한 핵심 정보만 포함합니다. 새 마커를 생성하는 데 일반적으로 1KB 미만의 대역폭이 사용됩니다. 시스템은 또한 활동이 많은 기간 동안 메시지 빈도를 줄이기 위해 지능형 배칭을 포함합니다.

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

Cross-Tab Synchronization

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

사용자는 여러 기기에서 동시에 사이트를 열어둘 수 있으며 모든 기기가 동기 상태를 유지합니다. 데스크탑에서 생성된 마커는 두 기기 모두 동일한 이미지를 보고 있는 경우 사용자의 태블릿에 즉시 표시됩니다.

Security

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

Offline Behavior

사용자가 완전히 오프라인인 경우 기존 마커는 여전히 볼 수 있지만 새 마커를 생성하거나 다른 사용자의 업데이트를 볼 수는 없습니다. 위젯은 오프라인 상태를 감지하고 적절한 메시지를 표시합니다.

사용자가 오프라인 상태에서 마커를 생성하려 시도한 후 온라인으로 돌아오면 해당 작업은 큐에 보관되는 대신 실패합니다. 이는 데이터 일관성을 보장하기 위함입니다. 사용자는 연결이 복원된 후 작업을 다시 시도해야 합니다.

Performance Impact

WebSocket 연결은 성능에 미치는 영향이 최소입니다. 업데이트가 발생하지 않을 때 연결은 유휴 상태를 유지하며 활동이 발생할 때만 메시지를 처리합니다. 중간 수준의 마커 활동이 있는 일반적인 이미지의 경우 WebSocket은 이미지 자체를 렌더링하는 것보다 적은 CPU를 사용합니다.

수백 명이 동시에 접속하고 마커 생성 활동이 많은 페이지의 경우 시스템은 개별 클라이언트 연결에 영향을 주지 않으면서 성능을 유지하도록 수평적으로 확장됩니다.

Collaborative Use Cases

실시간 동기화는 Image Chat을 공동 작업 워크플로에 특히 강력하게 만듭니다. 디자인 팀은 모두가 마커 배치를 실시간으로 보면서 목업을 함께 검토할 수 있습니다. 고객 지원 팀은 문제를 식별하기 위해 스크린샷에 공동으로 주석을 달 수 있습니다. 교육 그룹은 모든 참가자가 생성되는 각자의 마커를 보면서 다이어그램을 토론할 수 있습니다.

즉각적인 피드백은 사용자가 업데이트를 보기 위해 새로 고침해야 하는 전통적인 댓글 시스템에 비해 더 몰입감 있고 생산적인 협업 경험을 만듭니다.

API 참조

API 개요

Image Chat는 이미지 대화를 프로그래밍 방식으로 관리할 수 있는 세 가지 REST API 엔드포인트를 제공합니다. 이 엔드포인트를 사용하면 브라우저 위젯을 사용하지 않고도 마커를 검색, 생성 및 삭제할 수 있습니다.

모든 API 엔드포인트는 인증이 필요하며 표준 FastComments API 패턴을 따릅니다. 이러한 엔드포인트는 API 키가 아닌 브라우저 쿠키를 통해 인증되는 공개 엔드포인트입니다.

기본 URL

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

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

인증

이 엔드포인트들은 브라우저 쿠키를 통해 사용자를 인증합니다. API 키를 사용하지 않습니다. 사용자는 브라우저에서 FastComments에 로그인되어 있어야 이 엔드포인트에 접근할 수 있습니다.

모든 대화 가져오기

특정 이미지에 대한 모든 이미지 대화를 가져옵니다.

엔드포인트

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

매개변수

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

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

응답

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

예시 요청

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

예시 응답

{
  "status": "success",
  "user": {
    "id": "user123",
    "username": "john_doe"
  },
  "conversations": [
    {
      "_id": "conv123",
      "urlId": "my-product-image:/images/product.jpg:25:30",
      "x": 25.5,
      "y": 30.2
    },
    {
      "_id": "conv456",
      "urlId": "my-product-image:/images/product.jpg:60:45",
      "x": 60.8,
      "y": 45.1
    }
  ],
  "urlIdClean": "my-product-image",
  "isSiteAdmin": false,
  "tenantIdWS": "demo",
  "urlIdWS": "my-product-image",
  "userIdWS": "user123"
}

대화 생성

이미지의 특정 위치에 대한 새 이미지 대화를 생성합니다.

엔드포인트

POST /comment-image-chats/:tenantId

매개변수

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

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

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

windowUrlId (string, 필수)는 이미지 소스와 좌표가 결합된 URL로 예: my-page:/images/photo.jpg:25.5:30.2.

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

src (string, 필수)는 이미지 소스 URL입니다.

x (number, 필수)는 이미지 너비 대비 X 좌표의 백분율(0-100)입니다.

y (number, 필수)는 이미지 높이 대비 Y 좌표의 백분율(0-100)입니다.

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

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

응답

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

예시 요청

curl -X POST "https://fastcomments.com/comment-image-chats/demo" \
  --cookie "your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "urlId": "my-product-image",
    "windowUrlId": "my-product-image:/images/product.jpg:25.5:30.2",
    "pageTitle": "Product Gallery",
    "src": "/images/product.jpg",
    "x": 25.5,
    "y": 30.2,
    "createdFromCommentId": "comment789",
    "broadcastId": "550e8400-e29b-41d4-a716-446655440000"
  }'

예시 응답

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

대화 삭제

기존 이미지 대화를 삭제합니다. 이 엔드포인트는 관리자 또는 중재자 권한이 필요하거나, 인증된 사용자가 생성한 대화여야 합니다.

엔드포인트

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

매개변수

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

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

broadcastId (요청 본문, 필수)는 라이브 동기화용 UUID입니다.

예시 요청

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

예시 응답

{
  "status": "success"
}

좌표 시스템

X 및 Y 좌표는 이미지 치수에 대한 백분율로 저장됩니다. X는 왼쪽 가장자리에서의 수평 위치를 나타냅니다(0 = 왼쪽 가장자리, 100 = 오른쪽 가장자리). Y는 위쪽 가장자리에서의 수직 위치를 나타냅니다(0 = 위쪽 가장자리, 100 = 아래쪽 가장자리).

이러한 백분율 값은 정밀도를 위해 소수점을 포함할 수 있습니다. 예를 들어 x: 25.5는 이미지 왼쪽 가장자리로부터 25.5% 위치를 의미합니다.

속도 제한

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

오류 응답

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

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

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

사용량 추적

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

궁금한 점이 있으신가요?

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

실제 동작하는 Image Chat을 보려면 데모 페이지의 라이브 데모를 확인하세요.

언어 🇰🇷 한국어

시작하기

구성

맞춤화

고급

시작하기

사용 사례

빠른 시작

설치

기본 구현

작동 방식

라이브 데모

다음 단계

프런트엔드 라이브러리

예제

기본 예제

컨테이너 요소 예제

사용자 정의 URL ID 예제

다크 모드 예제

사용자 지정 채팅 사각형 크기 예제

댓글 수 콜백 예제

여러 이미지 예제

구성 옵션

개요

필수 구성

tenantId

Image Chat 전용 옵션

urlId

chatSquarePercentage

hasDarkBackground

commentCountUpdated

상속된 구성 옵션

locale

readonly

sso and simpleSSO

maxReplyDepth

내부 구성

대상 요소 유연성

전체 예제

반응형 디자인

백분율 기반 위치 지정

반응형 레이아웃에 대한 이점

이미지 스케일링 및 종횡비

채팅 사각형 크기

모바일 동작

동적 이미지 로딩

기기 간 일관성

뷰포트 고려사항

미래 대비 콘텐츠

맞춤화

다크 모드 지원

동적 다크 모드

CSS로 사용자 지정 스타일

채팅 사각형 크기

모바일 동작

채팅 창 모양

지연 초기화

지역화

상속된 사용자 지정 옵션

사용자 정의 폰트 사용

마커 시각 디자인

실시간 동기화

Real-Time Updates

How WebSocket Sync Works

Broadcast ID System

Connection Resilience

Bandwidth Considerations

Cross-Tab Synchronization

Security

Offline Behavior

Performance Impact

Collaborative Use Cases

API 참조

API 개요

기본 URL

인증

모든 대화 가져오기

엔드포인트

매개변수

응답