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 <!-- Your image -->
9 <img id="my-image" src="https://fastcomments.com/images/image-chat-demo-1.jpg" alt="Pretty Trail" />
10
11 <!-- Load the Image Chat script -->
12 <script src="https://cdn.fastcomments.com/js/embed-image-chat.min.js"></script>
13
14 <!-- Initialize Image Chat -->
15 <script>
16 FastCommentsImageChat(document.getElementById('my-image'), {
17 tenantId: 'demo'
18 });
19 </script>
20</body>
21</html>
22

Замініть 'demo' на свій фактичний Tenant ID FastComments, якщо це ще не зроблено. Ви можете знайти його у своїй панелі керування 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.

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'  // 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, тобто всі коментарі плоскі (без вкладених відповідей). Ви можете змінити це, якщо хочете ниткоподібні (threaded) розмови.

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    maxReplyDepth: 3  // Дозволити 3 рівні вкладеності
});

Внутрішня конфігурація

Ці параметри автоматично встановлюються 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.

Гнучкість цільового елемента

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

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

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

Віджет автоматично знайде зображення, якщо ви передасте контейнерний елемент.

Повний приклад

Ось приклад, що показує кілька параметрів конфігурації разом:

FastCommentsImageChat(document.getElementById('product-image'), {
    tenantId: 'demo',
    urlId: 'product-v2-main',
    chatSquarePercentage: 6,
    hasDarkBackground: false,
    locale: 'en',
    commentCountUpdated: function(count) {
        document.title = count > 0 ? `(${count}) Product Photo` : 'Product Photo';
    },
    sso: {
        // Ваша конфігурація SSO
    },
    maxReplyDepth: 1
});

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

Адаптивний дизайн 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, UI Image Chat автоматично врахує це без потреби у перевініалізації. Стилі віджета розроблені так, щоб реагувати на наявність цього класу.

/* Ваш CSS для темного режиму */
body.dark {
    background: #1a1a1a;
    color: #ffffff;
}

Користувацьке стилювання за допомогою CSS

Ви можете налаштувати зовнішній вигляд маркерів, вікон чату та інших елементів за допомогою CSS. Віджет додає певні класи, які можна націлювати у вашому стилі.

Квадрати чату та вікна використовують систему стилізації бульбашок коментарів FastComments, тому будь-які налаштування, які ви застосували до стандартного віджету коментування, також впливатимуть на Image Chat.

Розмір маркерів (Chat Square Sizing)

Опція chatSquarePercentage контролює розмір клікабельних маркерів. За замовчуванням це 5% ширини зображення:

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    chatSquarePercentage: 7  // Більші, більш помітні квадрати
});

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

Поведінка на мобільних пристроях

На екранах шириною менше 768px Image Chat автоматично переходить у макет, оптимізований для мобільних пристроїв. Вікна чату відкриваються на весь екран замість того, щоб плавати поруч з маркерами, що забезпечує кращу зручність роботи на маленьких екранах.

Маркерні позиції залишаються видимими на відповідних позиціях на зображенні. Користувачі можуть тапнути будь-який маркер, щоб відкрити інтерфейс чату на весь екран. Ця поведінка вбудована і не потребує додаткової конфігурації.

Зовнішній вигляд вікна чату

Вікна чату мають ширину 300px на десктопі з 16px стрілкою, що вказує на маркер. Вікна позиціонуються автоматично залежно від доступного простору у вікні перегляду, використовуючи класи позиціонування як to-right, to-left, to-top та to-bottom.

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

Лінива ініціалізація

Вікна чату ініціалізуються при hover для десктопних користувачів або відразу при створенні. Це зменшує початкове навантаження, рендерячи інтерфейс чату лише тоді, коли користувачі фактично взаємодіють з маркером.

Лінива ініціалізація відбувається прозоро. Користувачі не помічають затримки, але браузеру не потрібно рендерити десятки прихованих вікон чату, якщо на зображенні багато маркерів.

Локалізація

Image Chat підтримує всі ті ж опції локалізації, що й стандартний віджет FastComments. Встановіть опцію locale, щоб відобразити текст інтерфейсу різними мовами:

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

FastComments підтримує десятки мов. Налаштування locale впливає на весь текст інтерфейсу користувача, включаючи підказки, кнопки та текст заповнювачів.

Успадковані опції налаштування

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

Дивіться основну документацію FastComments щодо налаштувань для повного переліку доступних опцій.

Робота з кастомними шрифтами

Якщо на вашому сайті використовуються кастомні шрифти, UI Image Chat успадковує ці шрифти з CSS вашої сторінки. Вікна чату відображаються у DOM вашої сторінки і враховують існуючі налаштування типографіки.

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

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

Квадратні маркери мають витончене візуальне оформлення, яке робить їх помітними, не перевантажуючи зображення. Ви можете налаштувати їхній вигляд за допомогою CSS, якщо бажаєте іншу візуальну подачу.

Маркері включають hover-стани, які дають зворотний зв'язок, коли користувачі наводять на них мишу. На сенсорних пристроях взаємодія через тап дає миттєвий відгук шляхом відкриття вікна чату.

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

Оновлення в режимі реального часу

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

Offline Behavior

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

Якщо користувач намагається створити мітку в офлайн-режимі, а потім повертається в мережу, операція зазнає невдачі замість того, щоб поставитися в чергу, що забезпечує узгодженість даних. Користувачам слід повторити операцію після відновлення з’єднання.

Performance Impact

WebSocket-з’єднання має мінімальний вплив на продуктивність. З’єднання залишається в режимі простою, коли оновлень не відбувається, і обробляє повідомлення лише під час активності. На типовому зображенні з помірною активністю міток WebSocket використовує менше CPU, ніж рендеринг самого зображення.

Для сторінок з сотнями одночасних користувачів і високою активністю створення міток система масштабується по горизонталі, щоб підтримувати продуктивність без впливу на індивідуальні клієнтські з’єднання.

Collaborative Use Cases

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

Негайний зворотний зв’язок створює більш залучений і продуктивний досвід співпраці порівняно з традиційними системами коментарів, де користувачам потрібно оновлювати сторінку, щоб побачити оновлення.

Довідник API Internal Link

Огляд API

Image Chat надає три REST API кінцеві точки для програмного керування розмовами зображень. Ці кінцеві точки дозволяють отримувати, створювати та видаляти маркери без використання віджета у браузері.

Усі кінцеві точки API вимагають аутентифікацію і дотримуються стандартних шаблонів FastComments API. Це публічні кінцеві точки, які автентифікуються за допомогою cookie браузера, а не API-ключів.

Базовий URL

Усі кінцеві точки Image Chat API доступні за адресою:

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

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

Ці кінцеві точки автентифікують користувачів за допомогою cookie браузера. Вони не використовують API-ключі. Користувачі повинні бути увійшли в FastComments у своєму браузері, щоб отримати доступ до цих кінцевих точок.

Отримати всі розмови

Отримати всі розмови зображення для конкретного зображення.

Endpoint

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

Parameters

tenantId (path parameter, required) — ваш FastComments Tenant ID.

urlId (query parameter, required) — ідентифікатор зображення, для якого потрібно отримати розмови.

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

Створити розмову

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

Endpoint

POST /comment-image-chats/:tenantId

Parameters

tenantId (path parameter, required) — ваш FastComments Tenant ID.

Тіло запиту має бути у форматі JSON і містити наступні обов'язкові поля.

urlId (string, required) — базовий ідентифікатор сторінки.

windowUrlId (string, required) — URL, що поєднує сторінку з джерелом зображення та координатами, наприклад my-page:/images/photo.jpg:25.5:30.2.

pageTitle (string, required) — заголовок сторінки.

src (string, required) — URL джерела зображення.

x (number, required) — координата X у відсотках (0-100).

y (number, required) — координата Y у відсотках (0-100).

createdFromCommentId (string, required) — ID коментаря, який ініціював цю розмову.

broadcastId (string, required) — 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"
}

Видалити розмову

Видалити існуючу розмову зображення. Ця кінцева точка вимагає прав адміністратора або модератора, або розмова повинна була бути створена автентифікованим користувачем.

Endpoint

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

Parameters

tenantId (path parameter, required) — ваш FastComments Tenant ID.

chatId (path parameter, required) — ID розмови, яку потрібно видалити.

broadcastId (request body, required) — 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"
}

Система координат

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

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

Обмеження частоти запитів

Ці кінцеві точки підлягають стандартному лімітуванню FastComments API. Посередник для обмежень застосовується для кожного tenant, щоб запобігти зловживанням, при цьому дозволяючи нормальні сценарії використання.

Відповіді з помилками

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

Відповіді з помилками містять JSON-тіло з деталями:

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

Відстеження використання

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

Маєте запитання?

На цьому все щодо FastComments Image Chat! Якщо у вас є запитання, потрібна допомога з реалізацією або у вас є пропозиції щодо функцій, будь ласка, повідомте нам нижче або зверніться до нашої служби підтримки.

Перегляньте живу демонстрацію на нашій сторінці демо, щоб побачити Image Chat в дії.

Зробити внесок у цей посібник