FastComments Image Chat consente discussioni interattive sulle immagini permettendo agli utenti di fare clic in qualsiasi punto di un'immagine per creare punti di discussione. Gli utenti possono fare clic su parti specifiche delle immagini per avviare conversazioni su quelle aree, creando indicatori visivi che mostrano dove si trovano le discussioni.
Questa funzione è perfetta per feedback sul design, recensioni di prodotti, materiali didattici con diagrammi, gallerie fotografiche con commenti e qualsiasi scenario in cui si desiderino discussioni contestuali ancorate a posizioni specifiche dell'immagine.
Primi Passi 
Casi d'uso
Image Chat è ideale per il feedback di design quando i team devono discutere elementi specifici in mockup o screenshot. I siti di recensioni di prodotti possono permettere ai clienti di discutere caratteristiche specifiche visibili nelle foto dei prodotti. Le piattaforme educative possono usarlo per discutere diagrammi, mappe o immagini scientifiche. Le gallerie fotografiche possono diventare interattive con commenti legati a posizioni specifiche. I siti immobiliari possono permettere ai visitatori di discutere caratteristiche specifiche visibili nelle foto delle proprietà.
Quick Start
Per iniziare con Image Chat è semplice. Hai bisogno dello script FastComments Image Chat, di un elemento immagine o di un contenitore con un'immagine e di un oggetto di configurazione con il tuo Tenant ID.
Installazione
Aggiungi lo script Image Chat alla tua pagina:
Implementazione di base
Ecco un esempio minimo:
Run 
Sostituisci 'demo' con il tuo reale FastComments Tenant ID se non lo è già, che puoi trovare nel tuo dashboard di FastComments.
Come funziona
Una volta inizializzato, gli utenti possono cliccare in qualsiasi punto dell'immagine. Quando avviene un clic, un marcatore quadrato visivo appare in quella posizione e si apre una finestra di chat. Altri utenti possono vedere tutti i marcatori e cliccarli per visualizzare o partecipare a quelle discussioni. Tutte le discussioni si sincronizzano in tempo reale tra tutti i visitatori.
Il widget utilizza un posizionamento basato su percentuali, quindi i marcatori rimangono nella posizione corretta anche quando l'immagine viene ridimensionata o viene visualizzata su schermi di dimensioni diverse.
Demo dal vivo
Puoi vedere Image Chat in azione nella nostra pagina demo dal vivo.
Prossimi passi
Ora che hai le basi funzionanti, puoi personalizzare l'aspetto e il comportamento nella guida alle Opzioni di Configurazione. Consulta la guida al Design Responsivo per capire come funziona il posizionamento basato su percentuali. Scopri lo styling e il supporto per la modalità scura nella guida alla Personalizzazione. Per integrazioni avanzate, esplora il Riferimento API.
Librerie Frontend
Tutte le librerie frontend di FastComments (react, vue, angular, ecc.) includono Image Chat.
Esempi
Esempio base
Il modo più semplice per utilizzare Image Chat è puntare a un singolo elemento immagine. Questo esempio mostra come abilitare discussioni interattive su un'immagine:
Run Esempio con elemento contenitore
Puoi anche passare un elemento contenitore che al suo interno contiene un'immagine:
Run Esempio con URL ID personalizzato
Per impostazione predefinita, Image Chat utilizza l'URL della pagina combinato con la sorgente dell'immagine e le coordinate per identificare le conversazioni. Puoi fornire un urlId personalizzato:
Run Questo è utile se la struttura degli URL cambia ma vuoi mantenere le stesse conversazioni, oppure se vuoi condividere gli stessi punti di discussione su più pagine.
Esempio con modalità scura
Se il tuo sito ha uno sfondo scuro e il widget non lo rileva automaticamente come dovrebbe, possiamo abilitare manualmente il supporto per la modalità scura:
Run Esempio con dimensione personalizzata dei quadrati di chat
Puoi regolare la dimensione dei quadrati cliccabili che appaiono sull'immagine. La dimensione è specificata come percentuale della larghezza dell'immagine:
Run Esempio con callback per il conteggio dei commenti
Monitora quando i commenti vengono aggiunti o aggiornati utilizzando la callback commentCountUpdated:
Esempio con immagini multiple
Puoi inizializzare Image Chat su più immagini. Ogni immagine avrà i propri punti di discussione indipendenti:
Run Opzioni di Configurazione
Panoramica
FastComments Image Chat estende il widget di commenti standard di FastComments, quindi eredita tutte le opzioni di configurazione dal widget base aggiungendo alcune opzioni specifiche per le annotazioni sulle immagini.
Configurazione richiesta
tenantId
Il tuo FastComments Tenant ID è obbligatorio. Puoi trovarlo nella tua FastComments dashboard.
FastCommentsImageChat(imageElement, {
tenantId: 'demo'
});Opzioni specifiche di Image Chat
urlId
Per impostazione predefinita, Image Chat genera un identificatore univoco per ogni conversazione basato sull'URL della pagina, sulla sorgente dell'immagine e sulle coordinate X/Y. Puoi sovrascriverlo con un urlId personalizzato.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
urlId: 'my-custom-image-id'
});Questo è utile quando la struttura degli URL potrebbe cambiare ma vuoi mantenere le stesse conversazioni, o quando vuoi condividere le annotazioni su più pagine.
chatSquarePercentage
Controlla la dimensione dei marker cliccabili come percentuale della larghezza dell'immagine. Il valore predefinito è 5%, il che significa che ogni marker è il 5% della larghezza dell'immagine.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 8 // Più grandi, marcatori più visibili
});Valori più piccoli creano marker meno invasivi, più adatti per immagini dettagliate. Valori più grandi rendono i marker più facili da vedere e cliccare su immagini affollate o per utenti su dispositivi mobili.
hasDarkBackground
Abilita lo stile in modalità scura quando la tua pagina ha uno sfondo scuro.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});commentCountUpdated
Una funzione di callback che viene eseguita ogni volta che il conteggio dei commenti cambia. Questo è utile per aggiornare elementi dell'interfaccia come badge o titoli della pagina.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
commentCountUpdated: function(count) {
console.log('Total comments:', count);
document.getElementById('badge').textContent = count;
}
});Opzioni di configurazione ereditate
Poiché Image Chat estende il widget di commenti standard, puoi usare qualsiasi opzione di configurazione del widget base di FastComments. Ecco alcune opzioni comunemente usate:
locale
Imposta la lingua per l'interfaccia del widget. FastComments supporta decine di lingue.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'es' // Spagnolo
});readonly
Rendi tutte le conversazioni in sola lettura. Gli utenti possono visualizzare i marker e le discussioni esistenti ma non possono crearne di nuovi o rispondere.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
readonly: true
});sso e simpleSSO
Integra il tuo sistema di autenticazione utilizzando il Single Sign-On.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
sso: {
// Configurazione SSO
}
});Vedi la documentazione SSO per i dettagli completi sulle opzioni di autenticazione.
maxReplyDepth
Controlla quanti livelli di profondità possono avere le risposte. Per impostazione predefinita, Image Chat imposta questo valore a 0, il che significa che tutti i commenti sono piatti (nessuna risposta nidificata). Puoi modificarlo se desideri conversazioni threaded.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
maxReplyDepth: 3 // Consenti 3 livelli di annidamento
});Configurazione interna
Queste opzioni sono impostate automaticamente da Image Chat e non dovrebbero essere sovrascritte:
Il productId è impostato automaticamente su 2 per Image Chat. L'estensione floating-chat viene caricata automaticamente per fornire la funzionalità della finestra di chat. Il widget rileva automaticamente i dispositivi mobili (schermi sotto i 768px di larghezza) e adatta l'interfaccia di conseguenza con finestre di chat a schermo intero.
Flessibilità dell'elemento di destinazione
Il primo parametro di FastCommentsImageChat può essere sia un elemento <img> direttamente sia un elemento contenitore con un'immagine al suo interno:
// Elemento immagine diretto
FastCommentsImageChat(document.getElementById('my-image'), config);
// Contenitore con immagine all'interno
FastCommentsImageChat(document.querySelector('.image-wrapper'), config);Il widget troverà automaticamente l'immagine se passi un elemento contenitore.
Esempio completo
Ecco un esempio che mostra più opzioni di configurazione insieme:
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: {
// La tua configurazione SSO
},
maxReplyDepth: 1
});Per un elenco completo di tutte le opzioni di configurazione disponibili ereditate dal widget base, vedi la documentazione principale di configurazione di FastComments.
Design Reattivo
Posizionamento Basato su Percentuali
Image Chat usa coordinate basate su percentuali invece di coordinate in pixel per posizionare i marker di chat sulle immagini. Quando un utente clicca su un'immagine, il widget converte le coordinate in pixel del clic in percentuali della larghezza e dell'altezza dell'immagine. Questo approccio garantisce che i marker rimangano nella posizione corretta indipendentemente da come l'immagine viene visualizzata.
Ad esempio, se un utente clicca a 250 pixel dal bordo sinistro di un'immagine larga 1000px, il widget memorizza questo come 25% dal bordo sinistro. Quando un altro utente visualizza la stessa immagine a 500px di larghezza su un dispositivo mobile, il marker appare a 125 pixel dal bordo sinistro, che è ancora il 25% della larghezza.
Vantaggi per layout responsive
Questo sistema basato su percentuali fa sì che Image Chat funzioni senza problemi su tutte le dimensioni e orientamenti dei dispositivi. Le tue immagini potrebbero essere visualizzate a dimensioni diverse a seconda della larghezza dello schermo, delle regole CSS o dei vincoli del contenitore, ma i marker si allineano sempre correttamente con le posizioni previste.
Gli utenti su computer desktop con monitor grandi vedono i marker nelle stesse posizioni relative degli utenti su smartphone con schermi piccoli. I marker si ridimensionano proporzionalmente all'immagine stessa.
Ridimensionamento dell'Immagine e Rapporto d'Aspetto
Finché la tua immagine mantiene il rapporto d'aspetto durante il ridimensionamento (che è il comportamento predefinito del browser), i marker basati su percentuali rimarranno perfettamente allineati. Il widget presuppone che le immagini si ridimensionino proporzionalmente e calcola le posizioni basandosi su questa assunzione.
Se applichi CSS che distorce il rapporto d'aspetto dell'immagine (ad esempio usando object-fit: cover con dimensioni specifiche), le posizioni dei marker potrebbero non allinearsi correttamente. Per risultati ottimali, lascia che le immagini si ridimensionino naturalmente oppure usa object-fit: contain per mantenere il rapporto d'aspetto.
Dimensionamento del quadrato di chat
La dimensione visiva dei marker di chat è anch'essa basata su percentuali. L'opzione di configurazione chatSquarePercentage ha valore predefinito 5%, il che significa che ogni quadrato corrisponde al 5% della larghezza dell'immagine. Questo garantisce un peso visivo coerente tra immagini di diverse dimensioni.
Su un'immagine larga 1000px con l'impostazione predefinita del 5%, i marker sono quadrati da 50px. Su un'immagine larga 500px, gli stessi marker sono quadrati da 25px. Rimangono proporzionali alla dimensione dell'immagine.
Comportamento su Mobile
Su schermi con larghezza inferiore a 768px, Image Chat passa a un layout ottimizzato per mobile. Le finestre di chat si aprono a schermo intero invece di fluttuare accanto al marker. Questo offre una migliore usabilità su schermi piccoli dove le finestre flottanti oscurerebbero troppo l'immagine.
I marker stessi restano visibili e cliccabili alle loro posizioni basate su percentuali. Gli utenti possono comunque vedere dove sono localizzate le discussioni e toccare i marker per aprire l'interfaccia di chat a schermo intero.
Caricamento Dinamico delle Immagini
Il sistema basato su percentuali funziona correttamente anche quando le immagini vengono caricate in modo asincrono o cambiano dimensione dopo il caricamento della pagina. Il widget monitora l'elemento immagine e ricalcola le posizioni dei marker ogni volta che cambiano le dimensioni dell'immagine.
Se stai usando il lazy-loading delle immagini o implementando immagini responsive con dimensioni diverse a differenti breakpoint, i marker si adattano automaticamente quando cambia la dimensione dell'immagine.
Coerenza tra Dispositivi
Poiché le coordinate vengono memorizzate come percentuali nel database, una discussione creata su un computer desktop appare esattamente nella stessa posizione relativa quando viene visualizzata su un tablet o uno smartphone. Gli utenti possono collaborare tra dispositivi senza incongruenze nel posizionamento.
Questo funziona in entrambe le direzioni. Una discussione creata toccando un punto specifico su un dispositivo mobile appare nella stessa posizione relativa quando viene visualizzata su un grande monitor desktop.
Considerazioni sul Viewport
Il widget calcola le percentuali rispetto all'elemento immagine stesso, non rispetto al viewport. Ciò significa che lo scorrimento della pagina o la modifica delle dimensioni della finestra del browser non influiscono sulle posizioni dei marker. I marker restano ancorati alle loro posizioni sull'immagine indipendentemente dai cambiamenti del viewport.
Protezione futura dei contenuti
L'approccio basato su percentuali rende le tue discussioni sulle immagini resilienti ai cambiamenti di layout, design o ecosistema di dispositivi. Con l'emergere di nuove dimensioni di schermo e dispositivi, le discussioni esistenti continueranno a essere visualizzate correttamente senza richiedere aggiornamenti o migrazioni.
Personalizzazione
Supporto per la Modalità Scura
Image Chat include il supporto integrato per la modalità scura. Quando imposti hasDarkBackground: true nella tua configurazione, le finestre della chat e gli elementi dell'interfaccia si adattano automaticamente per funzionare bene su sfondi scuri.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});Lo stile per la modalità scura si applica alle finestre della chat, ai quadrati dei marker e a tutti gli elementi interattivi. Se il tuo sito dispone di un interruttore per la modalità scura, puoi reinizializzare il widget quando la modalità cambia, oppure usare l'approccio della classe sul body descritto più avanti.
Modalità Scura Dinamica
Se la modalità scura del tuo sito è controllata aggiungendo la classe .dark all'elemento body, l'interfaccia di Image Chat la rispetterà automaticamente senza necessità di reinizializzazione. Gli stili del widget sono progettati per rispondere alla presenza di questa classe.
/* Il tuo CSS per la modalità scura */
body.dark {
background: #1a1a1a;
color: #ffffff;
}Personalizzazione con CSS
Puoi personalizzare l'aspetto dei marker, delle finestre della chat e di altri elementi utilizzando il CSS. Il widget aggiunge classi specifiche che puoi prendere di mira nel tuo foglio di stile.
I quadrati e le finestre della chat utilizzano il sistema di stile delle bolle di commento di FastComments, quindi qualsiasi personalizzazione che hai applicato al widget di commenti standard influenzerà anche Image Chat.
Dimensione dei Quadrati della Chat
L'opzione chatSquarePercentage controlla la dimensione dei marker cliccabili. Il valore predefinito è il 5% della larghezza dell'immagine:
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 7 // Quadrati più grandi e più visibili
});Valori più piccoli creano marker più discreti che si fondono con l'immagine. Valori più grandi rendono i marker più evidenti e più facili da cliccare, specialmente sui dispositivi mobili o per motivi di accessibilità.
Comportamento sui dispositivi mobili
Su schermi con larghezza inferiore a 768px, Image Chat passa automaticamente a un layout ottimizzato per dispositivi mobili. Le finestre della chat appaiono a schermo intero invece di fluttuare accanto ai marker, offrendo una migliore usabilità su schermi piccoli.
I marker rimangono visibili nelle loro posizioni responsive sull'immagine. Gli utenti possono toccare un qualsiasi marker per aprire l'interfaccia della chat a schermo intero. Questo comportamento è integrato e non richiede configurazione.
Aspetto delle Finestre della Chat
Le finestre della chat sono larghe 300px su desktop con una freccia di 16px che punta al marker. Le finestre si posizionano automaticamente in base allo spazio disponibile nella viewport, utilizzando classi di posizionamento come to-right, to-left, to-top e to-bottom.
Puoi aggiungere CSS personalizzato per regolare colori, font, spaziatura o altre proprietà visive di queste finestre. Le finestre della chat usano la stessa struttura di componenti del widget standard di FastComments, quindi ereditano qualsiasi personalizzazione globale che hai applicato.
Inizializzazione ritardata
Le finestre della chat si inizializzano al passaggio del mouse per gli utenti desktop o immediatamente quando vengono create. Questo riduce il carico iniziale renderizzando l'interfaccia della chat solo quando gli utenti interagiscono effettivamente con un marker.
L'inizializzazione ritardata avviene in modo trasparente. Gli utenti non notano alcun ritardo, ma il browser non deve renderizzare dozzine di finestre della chat nascoste se hai molti marker su un'immagine.
Localizzazione
Image Chat supporta tutte le stesse opzioni di localizzazione del widget standard di FastComments. Imposta l'opzione locale per visualizzare il testo dell'interfaccia in lingue diverse:
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'fr' // Francese
});FastComments supporta decine di lingue. L'impostazione della locale influisce su tutto il testo dell'interfaccia, inclusi prompt, pulsanti e testo segnaposto.
Opzioni di Personalizzazione Ereditate
Poiché Image Chat estende il widget di commenti standard, eredita tutte le opzioni di personalizzazione del widget base. Questo include classi CSS personalizzate, traduzioni personalizzate, personalizzazione degli avatar, formattazione delle date e molto altro.
Consulta la documentazione principale di personalizzazione di FastComments per l'elenco completo delle opzioni di personalizzazione disponibili.
Uso di Font Personalizzati
Se il tuo sito usa font personalizzati, l'interfaccia di Image Chat erediterà quei font dal CSS della tua pagina. Le finestre della chat vengono renderizzate all'interno del DOM della tua pagina e rispettano le impostazioni tipografiche esistenti.
Per risultati ottimali, assicurati che i tuoi font personalizzati siano caricati prima di inizializzare Image Chat, oppure accetta che possa esserci un breve flash di testo non stilizzato mentre i font vengono caricati.
Design Visivo dei Marker
I marker quadrati hanno un design visivo sottile che li rende visibili senza sovrastare l'immagine. Puoi personalizzare il loro aspetto con il CSS se desideri un trattamento visivo diverso.
I marker includono stati al passaggio del mouse che forniscono un feedback quando gli utenti ci passano sopra con il mouse. Su dispositivi touch, l'interazione tap fornisce un feedback immediato aprendo la finestra della chat.
Sincronizzazione in Tempo Reale
Aggiornamenti in tempo reale
Image Chat usa connessioni WebSocket per sincronizzare tutte le conversazioni in tempo reale tra tutti gli utenti connessi. Quando qualcuno crea un nuovo marcatore, aggiunge un commento o elimina una discussione, tutti gli altri utenti che visualizzano la stessa immagine vedono l'aggiornamento immediatamente senza ricaricare.
Come funziona la sincronizzazione via WebSocket
Quando inizializzi Image Chat, il widget stabilisce una connessione WebSocket ai server FastComments. Questa connessione rimane aperta per tutta la durata della sessione dell'utente e ascolta gli aggiornamenti relativi all'immagine corrente.
Il sistema WebSocket utilizza tre tipi di messaggi broadcast per Image Chat. L'evento new-image-chat viene attivato quando qualcuno crea un nuovo marcatore sull'immagine. L'evento image-chat-updated viene attivato quando qualcuno aggiorna una conversazione esistente. L'evento deleted-image-chat viene attivato quando qualcuno elimina un marcatore.
Sistema di Broadcast ID
Per evitare effetti di eco in cui gli utenti vedono le proprie azioni ritrasmesse, ogni aggiornamento include un broadcastId univoco. Quando un utente crea o aggiorna un marcatore, il suo client genera un UUID per quell'operazione. Quando il WebSocket ritrasmette l'aggiornamento a tutti i client, il client di origine ignora l'aggiornamento perché corrisponde al proprio broadcastId.
Questo assicura un'interazione fluida in cui gli utenti vedono immediatamente le proprie modifiche nell'interfaccia senza attendere il round-trip attraverso il server, pur garantendo che tutti gli altri utenti ricevano l'aggiornamento.
Resilienza della connessione
Se la connessione WebSocket cade a causa di problemi di rete o manutenzione del server, il widget tenta automaticamente di riconnettersi. Durante il periodo di riconnessione, gli utenti possono comunque interagire con i marcatori esistenti, ma non vedranno aggiornamenti in tempo reale da altri utenti fino a quando la connessione non sarà ristabilita.
Una volta riconnesso, il widget risincronizza per assicurarsi che non siano stati persi aggiornamenti. Questo avviene in modo trasparente senza richiedere l'intervento dell'utente.
Considerazioni sulla larghezza di banda
I messaggi WebSocket sono leggeri e contengono solo le informazioni essenziali necessarie per sincronizzare lo stato. La creazione di un nuovo marcatore solitamente usa meno di 1KB di larghezza di banda. Il sistema include anche un batching intelligente per ridurre la frequenza dei messaggi durante i periodi di alta attività.
Le metriche di utilizzo nella dashboard di FastComments tracciano pubSubMessageCount e pubSubBandwidth in modo da poter monitorare l'attività di sincronizzazione in tempo reale sui tuoi siti.
Sincronizzazione tra schede
Se un utente ha la stessa pagina aperta in più schede del browser, gli aggiornamenti in una scheda appaiono immediatamente nelle altre. Questo funziona tramite lo stesso meccanismo di sincronizzazione WebSocket e non richiede alcuna configurazione aggiuntiva.
Gli utenti possono avere il tuo sito aperto su più dispositivi contemporaneamente e tutti resteranno sincronizzati. Un marcatore creato su un computer desktop appare istantaneamente sul tablet dell'utente se entrambi i dispositivi stanno visualizzando la stessa immagine.
Sicurezza
I messaggi WebSocket vengono trasmessi su connessioni sicure (WSS) e includono la validazione del tenant per assicurare che gli utenti ricevano solo gli aggiornamenti delle conversazioni per le quali sono autorizzati. Il server valida tutte le operazioni prima di trasmetterle per prevenire accessi o manipolazioni non autorizzate.
Comportamento offline
Quando gli utenti sono completamente offline, possono ancora visualizzare i marcatori esistenti ma non possono crearne di nuovi né vedere gli aggiornamenti degli altri. Il widget rileva lo stato offline e visualizza messaggi appropriati.
Se un utente tenta di creare un marcatore mentre è offline e poi torna online, l'operazione fallirà anziché essere messa in coda, garantendo la coerenza dei dati. Gli utenti devono riprovare l'operazione una volta ripristinata la connessione.
Impatto sulle prestazioni
La connessione WebSocket ha un impatto minimo sulle prestazioni. La connessione rimane inattiva quando non si verificano aggiornamenti e processa messaggi solo quando c'è attività. Su un'immagine tipica con attività moderata di marcatori, il WebSocket usa meno CPU rispetto al rendering dell'immagine stessa.
Per pagine con centinaia di utenti simultanei e alta attività di creazione marcatori, il sistema scala orizzontalmente per mantenere le prestazioni senza influire sulle singole connessioni client.
Casi d'uso collaborativi
La sincronizzazione in tempo reale rende Image Chat particolarmente potente per flussi di lavoro collaborativi. I team di design possono rivedere insieme i mockup con tutti che vedono le posizioni dei marcatori in tempo reale. I team di supporto clienti possono annotare collaborativamente screenshot per identificare problemi. I gruppi educativi possono discutere diagrammi con tutti i partecipanti che vedono i marcatori degli altri mentre vengono creati.
Il feedback immediato crea un'esperienza collaborativa più coinvolgente e produttiva rispetto ai sistemi di commento tradizionali in cui gli utenti devono aggiornare la pagina per vedere gli aggiornamenti.
Riferimento API
Panoramica API
Image Chat fornisce tre endpoint REST API per gestire le conversazioni sulle immagini in modo programmatico. Questi endpoint consentono di recuperare, creare ed eliminare i marcatori senza utilizzare il widget del browser.
Tutti gli endpoint API richiedono l'autenticazione e seguono i modelli standard dell'API FastComments. Si tratta di endpoint pubblici che autenticano tramite cookie del browser, non con API key.
URL base
Tutti gli endpoint Image Chat API si trovano sotto:
https://fastcomments.com/comment-image-chatsAutenticazione
Questi endpoint autenticano gli utenti tramite cookie del browser. Non usano API key. Gli utenti devono essere autenticati su FastComments nel loro browser per accedere a questi endpoint.
Recupera tutte le conversazioni
Recupera tutte le conversazioni per una specifica immagine.
Endpoint
GET /comment-image-chats/:tenantId?urlId=<urlId>Parametri
tenantId (parametro di percorso, obbligatorio) è il tuo Tenant ID di FastComments.
urlId (parametro di query, obbligatorio) è l'identificatore dell'immagine per cui vuoi recuperare le conversazioni.
Risposta
La risposta include lo stato dell'API, le informazioni sulla sessione dell'utente corrente se autenticato, un array di conversazioni con i loro ID, URL e coordinate X/Y, un identificatore URL pulito, un flag che indica se l'utente corrente è amministratore del sito o moderatore, e i dettagli di connessione WebSocket per la sincronizzazione in tempo reale inclusi tenantIdWS, urlIdWS e userIdWS.
Esempio di richiesta
curl "https://fastcomments.com/comment-image-chats/demo?urlId=my-product-image" \
--cookie "your-session-cookie"Esempio di risposta
{
"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"
}Crea conversazione
Crea una nuova conversazione sull'immagine in una posizione specifica.
Endpoint
POST /comment-image-chats/:tenantIdParametri
tenantId (parametro di percorso, obbligatorio) è il tuo Tenant ID di FastComments.
Il corpo della richiesta deve essere in JSON e includere i seguenti campi obbligatori.
urlId (stringa, obbligatorio) è l'identificatore base della pagina.
windowUrlId (stringa, obbligatorio) è l'URL combinato con la sorgente dell'immagine e le coordinate, per esempio my-page:/images/photo.jpg:25.5:30.2.
pageTitle (stringa, obbligatorio) è il titolo della pagina.
src (stringa, obbligatorio) è l'URL della sorgente dell'immagine.
x (numero, obbligatorio) è la coordinata X come percentuale (0-100).
y (numero, obbligatorio) è la coordinata Y come percentuale (0-100).
createdFromCommentId (stringa, obbligatorio) è l'ID del commento che ha avviato questa chat.
broadcastId (stringa, obbligatorio) è un UUID per la sincronizzazione in tempo reale per prevenire effetti di eco.
Risposta
La risposta include lo stato dell'API e l'ID della conversazione appena creata.
Esempio di richiesta
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"
}'Esempio di risposta
{
"status": "success",
"createdChatId": "conv789"
}Elimina conversazione
Elimina una conversazione esistente sull'immagine. Questo endpoint richiede permessi di amministratore o moderatore, oppure la conversazione deve essere stata creata dall'utente autenticato.
Endpoint
DELETE /comment-image-chats/:tenantId/:chatIdParametri
tenantId (parametro di percorso, obbligatorio) è il tuo Tenant ID di FastComments.
chatId (parametro di percorso, obbligatorio) è l'ID della conversazione da eliminare.
broadcastId (corpo della richiesta, obbligatorio) è un UUID per la sincronizzazione in tempo reale.
Esempio di richiesta
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"
}'Esempio di risposta
{
"status": "success"
}Sistema di coordinate
Le coordinate X e Y sono memorizzate come percentuali rispetto alle dimensioni dell'immagine. X rappresenta la posizione orizzontale a partire dal bordo sinistro (0 = bordo sinistro, 100 = bordo destro). Y rappresenta la posizione verticale a partire dal bordo superiore (0 = bordo superiore, 100 = bordo inferiore).
Questi valori percentuali possono includere decimali per una maggiore precisione. Ad esempio, x: 25.5 significa 25.5% dal bordo sinistro dell'immagine.
Limitazione delle richieste
Questi endpoint sono soggetti alla limitazione della frequenza standard dell'API FastComments. Il middleware per il rate limit si applica per tenant per prevenire abusi consentendo al contempo schemi di utilizzo normali.
Risposte di errore
Tutti gli endpoint restituiscono i codici di stato HTTP standard. Una risposta 400 indica parametri di richiesta non validi. Una risposta 401 significa che l'autenticazione è fallita. Una risposta 403 indica permessi insufficienti. Una risposta 404 significa che la conversazione non è stata trovata. Una risposta 429 indica che è stato superato il limite di richieste.
Le risposte di errore includono un body JSON con i dettagli:
{
"status": "error",
"message": "Conversation not found"
}Monitoraggio dell'utilizzo
La creazione di conversazioni incrementa la tua metrica di utilizzo conversationCreateCount. Tutta l'attività di sincronizzazione WebSocket incrementa pubSubMessageCount e pubSubBandwidth. Puoi monitorare queste metriche nella tua dashboard FastComments nella sezione analytics di utilizzo.
Hai domande?
Questo è tutto per FastComments Image Chat! Se hai domande, hai bisogno di aiuto con l'implementazione o vuoi suggerire funzionalità, faccelo sapere qui sotto oppure contatta il nostro team di supporto.
Guarda la demo live sulla nostra pagina demo per vedere Image Chat in azione.