FastComments.com
Menu Icon

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

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

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

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

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

Настройка

Настройка

Расширенные

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

Чат с изображениями

FastComments 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

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

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

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

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

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

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

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

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

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

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

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

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

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

Настройка 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

Обновления в реальном времени

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

Как работает синхронизация через WebSocket

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

Система WebSocket использует три типа широковещательных сообщений для Image Chat. Событие new-image-chat срабатывает, когда кто-то создаёт новый маркер на изображении. Событие image-chat-updated срабатывает, когда кто-то обновляет существующую беседу. Событие deleted-image-chat срабатывает, когда кто-то удаляет маркер.

Система broadcast ID

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

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

Устойчивость соединения

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

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

Вопросы пропускной способности

Сообщения WebSocket легковесны и содержат только необходимую информацию для синхронизации состояния. Создание нового маркера обычно занимает менее 1 КБ трафика. Система также включает интеллектуальную пакетную обработку для снижения частоты сообщений в периоды высокой активности.

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

Синхронизация между вкладками

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

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

Безопасность

Сообщения WebSocket передаются по защищённым соединениям (WSS) и включают проверку тенанта, чтобы пользователи получали обновления только для тех бесед, которые им разрешено видеть. Сервер проверяет все операции перед их рассылкой, чтобы предотвратить несанкционированный доступ или манипуляции.

Поведение в офлайн-режиме

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

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

Влияние на производительность

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

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

Сценарии совместной работы

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

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

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

Обзор API

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

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

Базовый URL

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

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

Аутентификация

Эти эндпоинты аутентифицируют пользователей через cookies браузера. Они не используют 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 (строка, обязательный) — это базовый идентификатор страницы.

windowUrlId (строка, обязательный) — это URL, объединённый с источником изображения и координатами, например my-page:/images/photo.jpg:25.5:30.2.

pageTitle (строка, обязательный) — это заголовок страницы.

src (строка, обязательный) — это URL источника изображения.

x (число, обязательный) — это координата X в процентах (0-100).

y (число, обязательный) — это координата Y в процентах (0-100).

createdFromCommentId (строка, обязательный) — это ID комментария, который инициировал этот диалог.

broadcastId (строка, обязательный) — это 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. Middleware ограничения частоты применяется для каждого tenant, чтобы предотвратить злоупотребления, при этом позволяя нормальные сценарии использования.

Ответы с ошибками

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

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

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

Учёт использования

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

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

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

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

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