FastComments.com
Menu Icon

Язык 🇺🇦 Русский (Украина)
🇺🇸 English 🇧🇬 Български 🇨🇳 简体中文 🇹🇼 繁體中文 🇭🇷 Hrvatski 🇩🇰 Dansk 🇳🇱 Nederlands 🇺🇸 English (US) 🇨🇦 Français (Canada) 🇫🇷 Français (France) 🇩🇪 Deutsch 🇨🇾 Ελληνικά (Κύπρος) 🇬🇷 Ελληνικά 🇮🇱 עברית 🇮🇹 Italiano 🇯🇵 日本語 🇰🇷 한국어 🇵🇱 Polski 🇧🇷 Português (Brasil) 🇷🇺 Русский 🇺🇦 Русский (Украина) 🇧🇦 Српски (БиХ) 🇷🇸 Srpski (Latinica) 🇲🇪 Српски (Црна Гора) 🇷🇸 Српски 🇸🇮 Slovenščina 🇪🇸 Español 🇺🇦 Українська 🇹🇷 Türkçe

Начало работы

Начало работы
Примеры

Конфигурация

Параметры конфигурации
Адаптивный дизайн

Кастомизация

Кастомизация

Продвинутые

Синхронизация в реальном времени
Справочник API

FastComments Image Chat обеспечивает интерактивные обсуждения изображений, позволяя пользователям кликать в любое место изображения для создания точек обсуждения. Пользователи могут кликать по конкретным частям изображений, чтобы начать разговоры об этих областях, создавая визуальные метки, которые показывают, где находятся обсуждения.

Эта функция отлично подходит для отзывов по дизайну, обзоров продуктов, образовательных материалов с диаграммами, фото-галерей с комментариями и любых сценариев, где нужны контекстные обсуждения, привязанные к конкретным местам на изображении.

Начало работы Internal Link

Использующие сценарии

Image Chat отлично подходит для обратной связи по дизайну, когда командам нужно обсуждать конкретные элементы макетов или скриншотов. Сайты с обзорами продуктов могут позволять клиентам обсуждать конкретные функции, видимые на фотографиях товаров. Образовательные платформы могут использовать его для обсуждения диаграмм, карт или научных изображений. Фотогалереи могут стать интерактивными благодаря комментариям, привязанным к местоположению. Сайты недвижимости могут позволить зрителям обсуждать конкретные детали, видимые на фото объектов.

Быстрый старт

Начать работу с Image Chat просто. Вам нужен скрипт FastComments Image Chat, элемент изображения или контейнер с изображением и объект конфигурации с вашим Tenant ID.

Установка

Добавьте скрипт Image Chat на вашу страницу:

Загрузка скрипта Image Chat
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
3

Базовая реализация

Вот минимальный пример:

Базовая реализация Image Chat
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>My Image Gallery with Image Chat</title>
6</head>
7<body>
8 <!-- Ваше изображение -->
9 <img id="my-image" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Pretty Trail" />
10
11 <!-- Загрузить скрипт Image Chat -->
12 <script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
13
14 <!-- Инициализация Image Chat -->
15 <script>
16 FastCommentsImageChat(document.getElementById('my-image'), {
17 tenantId: 'demo'
18 });
19 </script>
20</body>
21</html>
22

Замените 'demo' на ваш реальный FastComments Tenant ID, если он другой — вы можете найти его в вашей панели управления FastComments.

Как это работает

После инициализации пользователи могут кликать в любом месте изображения. При клике на этом месте появляется визуальный квадратный маркер, и открывается окно чата. Другие пользователи видят все маркеры и могут кликнуть по ним, чтобы просмотреть или присоединиться к обсуждению. Все обсуждения синхронизируются в реальном времени у всех посетителей.

Виджет использует позиционирование в процентах, поэтому маркеры остаются в правильном месте даже при изменении размера изображения или просмотре на разных размерах экрана.

Живая демонстрация

Вы можете увидеть Image Chat в действии на нашей демо-странице.

Следующие шаги

Теперь, когда у вас есть базовая настройка, вы можете настроить внешний вид и поведение в руководстве по параметрам конфигурации. Ознакомьтесь с руководством по адаптивному дизайну, чтобы понять, как работает позиционирование на основе процентов. Узнайте о стилизации и поддержке тёмной темы в руководстве по настройке. Для продвинутой интеграции изучите справочник API.

Фронтенд-библиотеки

Во всех фронтенд-библиотеках FastComments (react, vue, angular и т. д.) есть Image Chat.

Примеры Internal Link

Базовый пример

Самый простой способ использовать Image Chat — нацелиться на один элемент изображения. Этот пример показывает, как включить интерактивные обсуждения на изображении:

Базовый пример Image Chat
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>Product Image with Chat</title>
6</head>
7<body>
8 <img id="product-image" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Product Photo" />
9
10 <script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
11 <script>
12 FastCommentsImageChat(document.getElementById('product-image'), {
13 tenantId: 'demo'
14 });
15 </script>
16</body>
17</html>
18

Пример с контейнером

Вы также можете передать элемент-контейнер, внутри которого находится изображение:

Image Chat с контейнером
Copy CopyRun External Link
1
2<div id="image-container">
3 <img src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="System Diagram" />
4</div>
5
6<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
7<script>
8 FastCommentsImageChat(document.getElementById('image-container'), {
9 tenantId: 'demo'
10 });
11</script>
12

Пример с пользовательским URL ID

По умолчанию Image Chat использует URL страницы в сочетании с источником изображения и координатами для идентификации бесед. Вы можете указать пользовательский urlId:

Image Chat с пользовательским URL ID
Copy CopyRun External Link
1
2<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
3<script>
4 FastCommentsImageChat(document.getElementById('product-image'), {
5 tenantId: 'demo',
6 urlId: 'product-v2-main-image'
7 });
8</script>
9

Это полезно, если структура ваших URL изменяется, но вы хотите сохранить те же беседы, или если вы хотите распространять одни и те же точки обсуждения на нескольких страницах.

Пример с тёмным режимом

Если на вашем сайте тёмный фон и виджет не определяет это автоматически, как должен, мы можем вручную включить поддержку тёмного режима:

Image Chat в тёмном режиме
Copy CopyRun External Link
1
2<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
3<script>
4 FastCommentsImageChat(document.getElementById('product-image'), {
5 tenantId: 'demo',
6 hasDarkBackground: true
7 });
8</script>
9

Пример с пользовательским размером квадрата чата

Вы можете настроить размер кликабельных квадратиков, которые появляются на изображении. Размер задаётся в процентах от ширины изображения:

Image Chat с пользовательским размером квадрата
Copy CopyRun External Link
1
2<!DOCTYPE html>
3<html>
4<head>
5 <title>Image Chat with Custom Square Size</title>
6</head>
7<body>
8 <img id="product-image" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Product Photo" />
9
10 <script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
11 <script>
12 FastCommentsImageChat(document.getElementById('product-image'), {
13 tenantId: 'demo',
14 chatSquarePercentage: 2, // Меньшие квадраты (по умолчанию 5)
15 });
16 </script>
17</body>
18</html>
19

Пример с обратным вызовом количества комментариев

Отслеживайте добавление или обновление комментариев с помощью обратного вызова commentCountUpdated:

Image Chat с обратным вызовом при обновлении количества комментариев
Copy Copy
1
2<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
3<script>
4 FastCommentsImageChat(document.getElementById('product-image'), {
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

Пример с несколькими изображениями

Вы можете инициализировать Image Chat на нескольких изображениях. У каждого изображения будут свои независимые точки обсуждения:

Image Chat на нескольких изображениях
Copy CopyRun External Link
1
2<img id="image-1" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Photo 1" />
3<img id="image-2" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Photo 2" />
4
5<script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
6<script>
7 // Инициализация для первого изображения
8 FastCommentsImageChat(document.getElementById('image-1'), {
9 tenantId: 'demo',
10 urlId: 'gallery-photo-1'
11 });
12
13 // Инициализация для второго изображения
14 FastCommentsImageChat(document.getElementById('image-2'), {
15 tenantId: 'demo',
16 urlId: 'gallery-photo-2'
17 });
18</script>
19

Параметры конфигурации Internal Link

Overview

FastComments Image Chat расширяет стандартный виджет комментариев FastComments, поэтому он наследует все параметры конфигурации от базового виджета и добавляет несколько, специфичных для аннотаций изображений.

Required Configuration

tenantId

Требуется ваш FastComments Tenant ID. Вы можете найти его в вашей FastComments dashboard.

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

Image Chat Specific Options

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

Функция-обратного вызова, которая срабатывает при каждом изменении количества комментариев. Это полезно для обновления элементов интерфейса, таких как бейджи или заголовки страницы.

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

Inherited Configuration Options

Поскольку Image Chat расширяет стандартный виджет комментариев, вы можете использовать любые параметры конфигурации из базового виджета FastComments. Ниже приведены некоторые часто используемые опции:

locale

Установите язык для интерфейса виджета. FastComments поддерживает десятки языков.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    locale: 'es'  // Spanish
});

readonly

Сделать все беседы доступными только для чтения. Пользователи смогут просматривать существующие маркеры и обсуждения, но не смогут создавать новые или отвечать.

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

sso and simpleSSO

Интегрируйте с вашей системой аутентификации, используя Single Sign-On.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    sso: {
        // Конфигурация SSO
    }
});

Смотрите документацию по SSO для полного описания вариантов аутентификации.

maxReplyDepth

Контролируйте, насколько глубоко могут быть вложены ответы. По умолчанию Image Chat устанавливает это значение в 0, что означает, что все комментарии плоские (без вложенных ответов). Вы можете изменить это, если хотите иметь древовидные беседы.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    maxReplyDepth: 3  // Разрешить 3 уровня вложенности
});

Internal Configuration

Эти параметры автоматически задаются Image Chat и не должны переопределяться:

The productId is automatically set to 2 for Image 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 with fullscreen chat windows.

Target Element Flexibility

Первый параметр для FastCommentsImageChat может быть либо элементом <img> напрямую, либо контейнером с изображением внутри:

// Прямой элемент изображения
FastCommentsImageChat(document.getElementById('my-image'), config);

// Контейнер с изображением внутри
FastCommentsImageChat(document.querySelector('.image-wrapper'), config);

Виджет автоматически найдёт изображение, если вы передадите элемент-контейнер.

Complete Example

Ниже пример, показывающий несколько опций конфигурации вместе:

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.

Адаптивный дизайн Internal Link

Процентное позиционирование

Image Chat использует координаты на основе процентов вместо пиксельных координат для расположения маркеров чата на изображениях. Когда пользователь кликает по изображению, виджет преобразует пиксельные координаты клика в проценты от ширины и высоты изображения. Такой подход гарантирует, что маркеры остаются в правильном месте независимо от того, как отображается изображение.

Например, если пользователь кликнул в 250 пикселях от левого края изображения шириной 1000px, виджет сохраняет это как 25% от левого края. Когда другой пользователь просматривает то же изображение шириной 500px на мобильном устройстве, маркер появляется в 125 пикселях от левого края, что по-прежнему составляет 25% от ширины.

Преимущества для адаптивной верстки

Эта процентная система позволяет Image Chat корректно работать на всех размерах устройств и ориентациях. Ваши изображения могут отображаться в разных размерах в зависимости от ширины экрана, CSS-правил или ограничений контейнера, но маркеры всегда будут правильно совпадать с задуманными местами.

Пользователи на настольных компьютерах с большими мониторами видят маркеры в тех же относительных позициях, что и пользователи на смартфонах с маленькими экранами. Маркеры масштабируются пропорционально самому изображению.

Масштабирование изображения и соотношение сторон

Пока ваше изображение сохраняет соотношение сторон при изменении размера (что является поведением браузера по умолчанию), процентные маркеры будут оставаться идеально выровненными. Виджет предполагает, что изображения масштабируются пропорционально и рассчитывает позиции на этом основании.

Если вы применяете CSS, которое искажает соотношение сторон изображения (например, используя object-fit: cover с заданными размерами), позиции маркеров могут не совпадать корректно. Для наилучших результатов позволяйте изображениям масштабироваться естественным образом или используйте object-fit: contain, чтобы сохранять соотношение сторон.

Размер чат-квадрата

Визуальный размер маркеров чата также основан на процентах. Опция конфигурации chatSquarePercentage по умолчанию равна 5%, что означает, что каждый квадрат составляет 5% от ширины изображения. Это обеспечивает согласованный визуальный вес на изображениях разного размера.

На изображении шириной 1000px с настройкой по умолчанию 5% маркеры имеют размеры 50px. На изображении шириной 500px те же маркеры имеют размеры 25px. Они остаются пропорциональными размеру изображения.

Поведение на мобильных устройствах

На экранах шириной меньше 768px Image Chat переключается на оптимизированную для мобильных устройств компоновку. Окна чата открываются во весь экран вместо плавающего окна рядом с маркером. Это обеспечивает лучшую удобочитаемость на маленьких экранах, где плавающие окна скрывали бы слишком большую часть изображения.

Сами маркеры остаются видимыми и кликабельными в своих процентных позициях. Пользователи по‑прежнему видят, где расположены все обсуждения, и могут нажимать на маркеры, чтобы открыть полноэкранный интерфейс чата.

Динамическая загрузка изображений

Процентная система работает корректно даже когда изображения загружаются асинхронно или меняют размер после загрузки страницы. Виджет отслеживает элемент изображения и пересчитывает позиции маркеров всякий раз, когда изменяются размеры изображения.

Если вы используете ленивую загрузку изображений или реализуете адаптивные изображения с разными размерами для разных точек преломления, маркеры автоматически подстраиваются при изменении размера изображения.

Согласованность между устройствами

Поскольку координаты сохраняются в базе данных в процентах, обсуждение, созданное на настольном компьютере, появляется в точно том же относительном месте при просмотре на планшете или телефоне. Пользователи могут совместно работать на разных устройствах без несоответствий в позиционировании.

Это работает в обоих направлениях. Обсуждение, созданное путём касания определённого места на мобильном устройстве, появляется в той же относительной позиции при просмотре на большом настольном мониторе.

Учет области просмотра

Виджет рассчитывает проценты относительно самого элемента изображения, а не относительно viewport. Это означает, что прокрутка страницы или изменение размера окна браузера не влияют на позиции маркеров. Маркеры остаются привязанными к своим местам на изображении независимо от изменений области просмотра.

Защита контента на будущее

Процентный подход делает ваши обсуждения изображений устойчивыми к изменениям в верстке, дизайне или экосистеме устройств. По мере появления новых размеров экранов и устройств существующие обсуждения будут продолжать отображаться корректно без необходимости обновлений или миграций.

Кастомизация Internal Link

Поддержка тёмной темы

Image Chat включает встроенную поддержку тёмной темы. Если вы установите hasDarkBackground: true в вашей конфигурации, окна чата и элементы интерфейса автоматически адаптируются для корректного отображения на тёмном фоне.

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

Стили тёмной темы применяются к окнам чата, маркерам-квадратам и всем интерактивным элементам. Если на вашем сайте есть переключатель тёмной темы, вы можете переинициализировать виджет при смене режима или использовать подход с классом body, описанный ниже.

Динамическая тёмная тема

Если тёмная тема на вашем сайте управляется добавлением класса .dark к элементу body, UI Image Chat автоматически учтёт это без необходимости переинициализации. Стили виджета разработаны так, чтобы реагировать на наличие этого класса.

/* Your dark mode 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. Установите опцию locale, чтобы отображать текст интерфейса на разных языках:

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    locale: 'fr'  // Французский
});

FastComments поддерживает десятки языков. Параметр locale влияет на весь текст интерфейса, включая подсказки, кнопки и текст-заполнитель.

Унаследованные опции кастомизации

Поскольку Image Chat расширяет стандартный виджет комментирования, он наследует все опции кастомизации базового виджета. Это включает пользовательские CSS-классы, собственные переводы, настройку аватаров, форматирование даты и многое другое.

См. основную документацию по кастомизации FastComments для полного списка доступных опций кастомизации.

Работа с пользовательскими шрифтами

Если на вашем сайте используются пользовательские шрифты, UI Image Chat унаследует эти шрифты из CSS вашей страницы. Окна чата рендерятся внутри DOM вашей страницы и уважительно используют существующие настройки типографики.

Для лучшего результата убедитесь, что пользовательские шрифты загружены до инициализации Image Chat, или примите возможность краткого мигания нестилизованного текста, пока шрифты подгружаются.

Визуальный дизайн маркеров

Квадратные маркеры имеют тонкий визуальный дизайн, который делает их заметными, не перегружая изображение. При желании вы можете настроить их внешний вид через CSS для другого визуального оформления.

Маркеры включают состояния при наведении, которые дают обратную связь при перемещении мыши по ним. На сенсорных устройствах взаимодействие по нажатию предоставляет мгновенную обратную связь, открывая окно чата.

Синхронизация в реальном времени Internal Link

Real-Time Updates

Image Chat использует WebSocket-соединения для синхронизации всех бесед в режиме реального времени между всеми подключенными пользователями. Когда кто-то создаёт новый маркер, добавляет комментарий или удаляет обсуждение, все остальные пользователи, просматривающие то же изображение, видят обновление мгновенно без перезагрузки.

How WebSocket Sync Works

Когда вы инициализируете Image Chat, виджет устанавливает WebSocket-соединение с серверами FastComments. Это соединение остаётся открытым на протяжении сессии пользователя и прослушивает обновления, связанные с текущим изображением.

Система 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) и включают проверку tenant, чтобы пользователи получали только те обновления, к которым они уполномочены иметь доступ. Сервер проверяет все операции перед их широковещательной отправкой, чтобы предотвратить несанкционированный доступ или манипуляции.

Offline Behavior

Когда пользователи полностью офлайн, они всё ещё могут просматривать существующие маркеры, но не могут создавать новые или видеть обновления от других. Виджет обнаруживает офлайн-состояние и отображает соответствующие сообщения.

Если пользователь пытается создать маркер в офлайне, а затем выходит в онлайн, операция завершится неудачей, а не будет поставлена в очередь, чтобы обеспечить согласованность данных. Пользователям следует повторить операцию, когда соединение будет восстановлено.

Performance Impact

WebSocket-соединение оказывает минимальное влияние на производительность. Соединение остаётся простаивающим, когда обновлений не происходит, и обрабатывает сообщения только при активности. На типичном изображении с умеренной активностью маркеров WebSocket использует меньше CPU, чем отрисовка самого изображения.

Для страниц со сотнями одновременных пользователей и высокой активностью по созданию маркеров система масштабируется горизонтально, чтобы поддерживать производительность, не влияя на отдельные клиентские соединения.

Collaborative Use Cases

Синхронизация в реальном времени делает Image Chat особенно полезным для совместных рабочих процессов. Команды дизайнеров могут вместе просматривать макеты, при этом все видят размещение маркеров в реальном времени. Команды поддержки клиентов могут совместно аннотировать скриншоты для выявления проблем. Образовательные группы могут обсуждать диаграммы, и все участники видят маркеры друг друга по мере их создания.

Немедленная обратная связь создаёт более вовлечённый и продуктивный совместный опыт по сравнению с традиционными системами комментариев, где пользователям приходится обновлять страницу, чтобы увидеть изменения.

Справочник API Internal Link

API Overview

Image Chat предоставляет три REST API-эндпойнта для программного управления обсуждениями изображений. Эти эндпойнты позволяют получать, создавать и удалять маркеры без использования браузерного виджета.

Все API-эндпойнты требуют аутентификации и следуют стандартным шаблонам FastComments API. Это публичные эндпойнты, которые аутентифицируются через cookie браузера, а не через API-ключи.

Base URL

Все эндпойнты Image Chat API находятся по адресу:

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

Authentication

Эти эндпойнты аутентифицируют пользователей через cookie браузера. Они не используют API-ключи. Пользователь должен быть вошедшим в FastComments в своем браузере, чтобы получить доступ к этим эндпойнтам.

Get All Conversations

Получить все обсуждения изображений для конкретного изображения.

Endpoint

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

Parameters

tenantId (параметр пути, обязательный) — ваш FastComments Tenant ID.

urlId (параметр запроса, обязательный) — идентификатор изображения, для которого вы хотите получить обсуждения.

Response

В ответ включены статус API, информация о текущей сессии пользователя, если он аутентифицирован, массив обсуждений с их идентификаторами, URL и координатами X/Y, очищенный идентификатор URL, флаг, указывающий, является ли текущий пользователь администратором сайта или модератором, и детали подключения WebSocket для синхронизации в реальном времени, включая tenantIdWS, urlIdWS и userIdWS.

Example Request

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

Example Response

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

Create Conversation

Создать новое обсуждение изображения для конкретного места на изображении.

Endpoint

POST /comment-image-chats/:tenantId

Parameters

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 для синхронизации в реальном времени, чтобы предотвратить эффект эхо.

Response

В ответ включены статус API и ID вновь созданного обсуждения.

Example Request

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

Example Response

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

Delete Conversation

Удалить существующее обсуждение изображения. Для этого эндпойнта требуются права администратора или модератора, либо обсуждение должно быть создано аутентифицированным пользователем.

Endpoint

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

Parameters

tenantId (параметр пути, обязательный) — ваш FastComments Tenant ID.

chatId (параметр пути, обязательный) — ID обсуждения, которое нужно удалить.

broadcastId (тело запроса, обязательный) — UUID для синхронизации в реальном времени.

Example Request

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

Example Response

{
  "status": "success"
}

Coordinate System

Координаты X и Y хранятся в виде процентов от размеров изображения. X представляет горизонтальное положение от левого края (0 = левый край, 100 = правый край). Y представляет вертикальное положение от верхнего края (0 = верхний край, 100 = нижний край).

Эти процентные значения могут содержать десятичные дроби для точности. Например, x: 25.5 означает 25.5% от левого края изображения.

Rate Limiting

Этим эндпойнтам применяются стандартные ограничения по частоте запросов FastComments. Middleware ограничения по частоте применяется на уровне каждого tenant, чтобы предотвратить злоупотребления и одновременно позволить нормальные модели использования.

Error Responses

Все эндпойнты возвращают стандартные HTTP-коды состояния. Ответ 400 указывает на неверные параметры запроса. Ответ 401 означает ошибку аутентификации. Ответ 403 указывает на недостаточные права. Ответ 404 означает, что обсуждение не найдено. Ответ 429 указывает на превышение лимита запросов.

Ответы об ошибках включают JSON-тело с деталями:

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

Usage Tracking

Создание обсуждений увеличивает ваш метрик использования conversationCreateCount. Вся активность синхронизации через WebSocket увеличивает pubSubMessageCount и pubSubBandwidth. Вы можете отслеживать эти метрики на панели FastComments в разделе аналитики использования.

Есть вопросы?

На этом всё для FastComments Image Chat! Если у вас есть вопросы, нужна помощь с реализацией или есть предложения по функционалу, пожалуйста, сообщите нам ниже или свяжитесь с нашей службой поддержки.

Посмотрите живую демонстрацию на нашей странице демо, чтобы увидеть Image Chat в действии.

Внести вклад в это руководство