Percentage-Based Positioning

Image Chat używa współrzędnych opartych na procentach zamiast współrzędnych w pikselach do pozycjonowania znaczników czatu na obrazach. Gdy użytkownik kliknie obraz, widget konwertuje współrzędne pikselowe kliknięcia na procenty szerokości i wysokości obrazu. Takie podejście zapewnia, że znaczniki pozostają na właściwym miejscu niezależnie od sposobu wyświetlania obrazu.

Na przykład, jeśli użytkownik kliknie 250 pikseli od lewej krawędzi obrazu o szerokości 1000px, widget zapisuje to jako 25% od lewej. Gdy inny użytkownik zobaczy ten sam obraz o szerokości 500px na urządzeniu mobilnym, znacznik pojawi się 125 pikseli od lewej, co wciąż stanowi 25% szerokości.

Benefits for Responsive Layouts

Ten system oparty na procentach sprawia, że Image Chat działa bezproblemowo na wszystkich rozmiarach urządzeń i orientacjach. Twoje obrazy mogą być wyświetlane w różnych rozmiarach w zależności od szerokości ekranu, reguł CSS lub ograniczeń kontenera, ale znaczniki zawsze wyrównują się prawidłowo z zamierzonymi miejscami.

Użytkownicy na komputerach stacjonarnych z dużymi monitorami widzą znaczniki w tych samych względnych pozycjach co użytkownicy na smartfonach z małymi ekranami. Znaczniki skalują się proporcjonalnie wraz z obrazem.

Image Scaling and Aspect Ratio

O ile obraz zachowuje swój współczynnik proporcji podczas skalowania (co jest domyślnym zachowaniem przeglądarki), znaczniki oparte na procentach pozostaną idealnie wyrównane. Widget zakłada, że obrazy skalują się proporcjonalnie i oblicza pozycje na tej podstawie.

Jeśli zastosujesz CSS, które zniekształca proporcje obrazu (na przykład używając object-fit: cover z określonymi wymiarami), pozycje znaczników mogą nie być wyrównane prawidłowo. Dla najlepszych rezultatów pozwól obrazom skalować się naturalnie lub użyj object-fit: contain, aby zachować współczynnik proporcji.

Chat Square Sizing

Wizualny rozmiar znaczników czatu jest również oparty na procentach. Opcja konfiguracji chatSquarePercentage ma domyślną wartość 5%, co oznacza, że każdy kwadrat ma 5% szerokości obrazu. Zapewnia to spójny wygląd wizualny niezależnie od rozmiaru obrazu.

Na obrazie o szerokości 1000px przy domyślnym ustawieniu 5% znaczniki mają 50px kwadrat. Na obrazie o szerokości 500px te same znaczniki mają 25px kwadrat. Pozostają proporcjonalne do rozmiaru obrazu.

Mobile Behavior

Na ekranach o szerokości poniżej 768px Image Chat przełącza się na układ zoptymalizowany pod kątem urządzeń mobilnych. Okna czatu otwierają się na pełnym ekranie zamiast unosić się obok znacznika. Zapewnia to lepszą użyteczność na małych ekranach, gdzie unoszące się okna zasłaniałyby zbyt dużą część obrazu.

Same znaczniki pozostają widoczne i klikalne w swoich pozycjach opartych na procentach. Użytkownicy nadal mogą zobaczyć, gdzie znajdują się wszystkie dyskusje i stuknąć znaczniki, aby otworzyć interfejs czatu na pełnym ekranie.

Dynamic Image Loading

System oparty na procentach działa poprawnie nawet wtedy, gdy obrazy ładują się asynchronicznie lub zmieniają rozmiar po załadowaniu strony. Widget monitoruje element obrazu i ponownie oblicza pozycje znaczników za każdym razem, gdy zmieniają się wymiary obrazu.

Jeśli stosujesz lazy-loading obrazów lub implementujesz obrazy responsywne o różnych rozmiarach na różnych punktach przerwania, znaczniki automatycznie dostosowują się, gdy zmienia się rozmiar obrazu.

Cross-Device Consistency

Ponieważ współrzędne są przechowywane w bazie danych jako procenty, dyskusja utworzona na komputerze stacjonarnym pojawia się w dokładnie tym samym względnym miejscu po wyświetleniu na tablecie lub telefonie. Użytkownicy mogą współpracować na różnych urządzeniach bez problemów z pozycjonowaniem.

Działa to w obie strony. Dyskusja utworzona przez stuknięcie konkretnego miejsca na urządzeniu mobilnym pojawia się w tej samej względnej pozycji po wyświetleniu na dużym monitorze stacjonarnym.

Viewport Considerations

Widget oblicza procenty względem samego elementu obrazu, a nie widoku (viewport). Oznacza to, że przewijanie strony lub zmiana rozmiaru okna przeglądarki nie wpływa na pozycje znaczników. Znaczniki pozostają zakotwiczone w swoich pozycjach na obrazie niezależnie od zmian widoku.

Future-Proofing Content

Podejście oparte na procentach sprawia, że Twoje dyskusje na obrazach są odporne na zmiany układu, projektu czy ekosystemu urządzeń. W miarę pojawiania się nowych rozmiarów ekranu i urządzeń istniejące dyskusje będą nadal wyświetlane poprawnie bez potrzeby aktualizacji lub migracji.

Dark Mode Support

Image Chat includes built-in dark mode support. When you set hasDarkBackground: true in your configuration, the chat windows and UI elements automatically adjust to work well on dark backgrounds.

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

The dark mode styling applies to chat windows, marker squares, and all interactive elements. If your site has a dark mode toggle, you can reinitialize the widget when the mode changes, or use the body class approach described below.

Dynamic Dark Mode

If your site's dark mode is controlled by adding a .dark class to the body element, the Image Chat UI will automatically respect this without requiring reinitialization. The widget's styles are designed to respond to the presence of this class.

/* Twoje CSS trybu ciemnego */
body.dark {
    background: #1a1a1a;
    color: #ffffff;
}

Custom Styling with CSS

You can customize the appearance of markers, chat windows, and other elements using CSS. The widget adds specific classes that you can target in your stylesheet.

The chat squares and windows use the FastComments comment bubble styling system, so any customizations you've applied to the standard commenting widget will also affect Image Chat.

Chat Square Sizing

The chatSquarePercentage option controls the size of the clickable markers. The default is 5% of the image width:

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    chatSquarePercentage: 7  // Większe, bardziej widoczne kwadraty
});

Smaller values create more subtle markers that blend into the image. Larger values make markers more prominent and easier to click, especially on mobile devices or for accessibility purposes.

Mobile Behavior

On screens under 768px wide, Image Chat automatically switches to a mobile-optimized layout. Chat windows appear fullscreen instead of floating next to the markers, providing better usability on small screens.

The markers remain visible at their responsive positions on the image. Users can tap any marker to open the fullscreen chat interface. This behavior is built-in and doesn't require any configuration.

Chat Window Appearance

Chat windows are 300px wide on desktop with a 16px arrow pointing to the marker. The windows position themselves automatically based on available viewport space, using positioning classes like to-right, to-left, to-top, and to-bottom.

You can add custom CSS to adjust colors, fonts, spacing, or other visual properties of these windows. The chat windows use the same component structure as the standard FastComments widget, so they inherit any global customizations you've applied.

Lazy Initialization

Chat windows initialize on hover for desktop users or immediately when created. This reduces the initial load overhead by only rendering the chat interface when users actually interact with a marker.

The lazy initialization happens transparently. Users don't notice any delay, but the browser doesn't need to render dozens of hidden chat windows if you have many markers on an image.

Localization

Image Chat supports all the same localization options as the standard FastComments widget. Set the locale option to display UI text in different languages:

FastCommentsImageChat(imageElement, {
    tenantId: 'demo',
    locale: 'fr'  // Francuski
});

FastComments supports dozens of languages. The locale setting affects all UI text including prompts, buttons, and placeholder text.

Inherited Customization Options

Since Image Chat extends the standard commenting widget, it inherits all customization options from the base widget. This includes custom CSS classes, custom translations, avatar customization, date formatting, and much more.

See the main FastComments customization documentation for the complete list of customization options available.

Working with Custom Fonts

If your site uses custom fonts, the Image Chat UI will inherit those fonts from your page's CSS. The chat windows render inside your page's DOM and respect your existing typography settings.

For best results, ensure your custom fonts are loaded before initializing Image Chat, or accept that there may be a brief flash of unstyled text while fonts load.

Marker Visual Design

The square markers have a subtle visual design that makes them noticeable without overwhelming the image. You can customize their appearance with CSS if you want a different visual treatment.

The markers include hover states that provide feedback when users move their mouse over them. On touch devices, the tap interaction provides immediate feedback by opening the chat window.

Aktualizacje w czasie rzeczywistym

Image Chat używa połączeń WebSocket do synchronizacji wszystkich konwersacji w czasie rzeczywistym między wszystkimi podłączonymi użytkownikami. Gdy ktoś tworzy nowy znacznik, dodaje komentarz lub usuwa dyskusję, wszyscy inni użytkownicy oglądający ten sam obraz widzą aktualizację natychmiast, bez odświeżania.

Jak działa synchronizacja przez WebSocket

Gdy inicjujesz Image Chat, widget nawiązuje połączenie WebSocket z serwerami FastComments. Połączenie to pozostaje otwarte przez cały czas trwania sesji użytkownika i nasłuchuje aktualizacji związanych z bieżącym obrazem.

System WebSocket używa trzech typów komunikatów rozgłoszeniowych dla Image Chat. Zdarzenie new-image-chat wywoływane jest, gdy ktoś tworzy nowy znacznik na obrazie. Zdarzenie image-chat-updated wywoływane jest, gdy ktoś aktualizuje istniejącą konwersację. Zdarzenie deleted-image-chat wywoływane jest, gdy ktoś usuwa znacznik.

System identyfikatorów broadcast

Aby zapobiec efektom echa, w których użytkownicy widzą własne działania rozgłaszane z powrotem do nich, każda aktualizacja zawiera unikalny broadcastId. Gdy użytkownik tworzy lub aktualizuje znacznik, jego klient generuje UUID dla tej operacji. Gdy WebSocket rozgłasza aktualizację z powrotem do wszystkich klientów, klient źródłowy ignoruje tę aktualizację, ponieważ pasuje ona do jego własnego broadcastId.

Zapewnia to płynną interakcję, w której użytkownicy widzą swoje zmiany natychmiast w interfejsie użytkownika bez oczekiwania na pełną podróż przez serwer, jednocześnie zapewniając, że wszyscy inni użytkownicy otrzymają aktualizację.

Odporność połączenia

Jeśli połączenie WebSocket zostanie przerwane z powodu problemów sieciowych lub konserwacji serwera, widget automatycznie próbuje ponownie nawiązać połączenie. W okresie ponownego łączenia użytkownicy nadal mogą wchodzić w interakcje z istniejącymi znacznikami, ale nie będą widzieć aktualizacji w czasie rzeczywistym od innych użytkowników, dopóki połączenie nie zostanie przywrócone.

Po ponownym połączeniu widget ponownie synchronizuje stan, aby upewnić się, że nie pominął żadnych aktualizacji. Dzieje się to w sposób przezroczysty, bez potrzeby interwencji użytkownika.

Uwagi dotyczące przepustowości

Komunikaty WebSocket są lekkie i zawierają tylko niezbędne informacje potrzebne do synchronizacji stanu. Utworzenie nowego znacznika zwykle zużywa mniej niż 1KB przepustowości. System zawiera również inteligentne grupowanie, aby zmniejszyć częstotliwość komunikatów w okresach dużej aktywności.

Twoje metryki użycia w panelu FastComments śledzą pubSubMessageCount i pubSubBandwidth, dzięki czemu możesz monitorować aktywność synchronizacji w czasie rzeczywistym na swoich witrynach.

Synchronizacja między kartami

Jeśli użytkownik ma tę samą stronę otwartą w wielu kartach przeglądarki, aktualizacje w jednej karcie pojawiają się natychmiast w pozostałych kartach. Działa to przez ten sam mechanizm synchronizacji WebSocket i nie wymaga żadnej dodatkowej konfiguracji.

Użytkownicy mogą mieć Twoją witrynę otwartą na wielu urządzeniach jednocześnie, i wszystkie będą pozostawać zsynchronizowane. Znacznik utworzony na komputerze stacjonarnym pojawi się natychmiast na tablecie użytkownika, jeśli oba urządzenia wyświetlają ten sam obraz.

Bezpieczeństwo

Komunikaty WebSocket są przesyłane przez bezpieczne połączenia (WSS) i zawierają walidację najemcy, aby upewnić się, że użytkownicy otrzymują tylko aktualizacje do rozmów, do których są uprawnieni. Serwer weryfikuje wszystkie operacje przed ich rozgłoszeniem, aby zapobiec nieautoryzowanemu dostępowi lub manipulacji.

Zachowanie w trybie offline

Gdy użytkownicy są całkowicie offline, nadal mogą przeglądać istniejące znaczniki, ale nie mogą tworzyć nowych ani zobaczyć aktualizacji od innych. Widget wykrywa stan offline i wyświetla odpowiednie komunikaty.

Jeśli użytkownik spróbuje utworzyć znacznik będąc offline, a następnie wróci online, operacja zakończy się niepowodzeniem zamiast być kolejkowana, co zapewnia spójność danych. Użytkownicy powinni ponowić próbę operacji po przywróceniu połączenia.

Wpływ na wydajność

Połączenie WebSocket ma minimalny wpływ na wydajność. Połączenie pozostaje bezczynne, gdy nie występują żadne aktualizacje i przetwarza komunikaty tylko wtedy, gdy pojawia się aktywność. Dla typowego obrazu przy umiarkowanej aktywności znaczników, WebSocket zużywa mniej CPU niż samo renderowanie obrazu.

Dla stron z setkami jednoczesnych użytkowników i wysoką aktywnością tworzenia znaczników, system skaluje się horyzontalnie, aby utrzymać wydajność bez wpływu na pojedyncze połączenia klientów.

Zastosowania w pracy zespołowej

Synchronizacja w czasie rzeczywistym czyni Image Chat szczególnie przydatnym w przepływach pracy wymagających współpracy. Zespoły projektowe mogą wspólnie przeglądać makiety, a wszyscy widzą rozmieszczenie znaczników w czasie rzeczywistym. Zespoły wsparcia klienta mogą wspólnie adnotować zrzuty ekranu, aby zidentyfikować problemy. Grupy edukacyjne mogą omawiać diagramy, a wszyscy uczestnicy widzą znaczniki dodawane przez innych w miarę ich tworzenia.

Natychmiastowa informacja zwrotna tworzy bardziej angażujące i produktywne doświadczenie współpracy w porównaniu z tradycyjnymi systemami komentarzy, gdzie użytkownicy muszą odświeżyć stronę, aby zobaczyć aktualizacje.