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 <!-- 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'  // Іспанська
});

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>, або контейнерним елементом із зображенням всередині:

// Безпосередньо елемент зображення
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, 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 для синхронізації всіх розмов у реальному часі між усіма підключеними користувачами. Коли хтось створює новий маркер, додає коментар або видаляє обговорення, всі інші користувачі, які переглядають те саме зображення, бачать оновлення одразу, без перезавантаження.

Як працює синхронізація 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 ендпоінти вимагають автентифікації та дотримуються стандартних шаблонів API FastComments. Це публічні ендпоінти, які автентифікуються через cookie браузера, а не через API-ключі.

Базова URL-адреса

Усі ендпоінти Image Chat API знаходяться за адресою:

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

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

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

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

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

Ендпоінт

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

Параметри

tenantId (параметр шляху, обов'язковий) — це ваш FastComments Tenant ID.

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

Відповідь

Відповідь містить статус API, інформацію про поточну сесію користувача (якщо автентифіковано), масив розмов з їхніми ідентифікаторами, 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 (рядок, обов'язковий) — це ідентифікатор коментаря, який ініціював цю розмову.

broadcastId (рядок, обов'язковий) — це UUID для синхронізації в реальному часі, щоб запобігти ефекту луни.

Відповідь

Відповідь містить статус API та ідентифікатор новоствореної розмови.

Приклад запиту

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 (параметр шляху, обов'язковий) — це ідентифікатор розмови, яку потрібно видалити.

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% від лівого краю зображення.

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

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

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

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

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

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

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

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

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

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

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

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