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 Reference.

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

Во всех фронтенд-библиотеках 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

Обзор

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

Обязательная конфигурация

tenantId

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

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

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

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

Унаследованные параметры конфигурации

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

locale

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

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    locale: 'es'  // Испанский
});

readonly

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

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

sso и simpleSSO

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

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

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

maxReplyDepth

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

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

Внутренняя конфигурация

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

Значение productId автоматически устанавливается в 2 для Image Chat. Расширение floating-chat автоматически загружается для обеспечения функциональности окна чата. Виджет автоматически обнаруживает мобильные устройства (экраны шириной менее 768px) и соответственно подстраивает интерфейс с полноэкранными окнами чата.

Гибкость целевого элемента

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

// Прямой элемент <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.

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

Percentage-Based Positioning

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

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

Benefits for Responsive Layouts

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

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

Image Scaling and Aspect Ratio

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

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

Chat Square Sizing

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

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

Mobile Behavior

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

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

Dynamic Image Loading

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

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

Cross-Device Consistency

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

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

Viewport Considerations

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

Future-Proofing Content

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

Настройка Internal Link

Поддержка тёмного режима

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

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

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

Динамический тёмный режим

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

/* Ваш 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 для полного списка доступных параметров настройки.

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

Если на вашем сайте используются пользовательские шрифты, интерфейс 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.

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

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 Internal Link

API Overview

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

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

Base URL

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

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

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