Controlar el widget
Puedes controlar el widget mediante programación desde tu propia interfaz: abrir secciones específicas, reaccionar a eventos, configurar los anuncios de novedades o reemplazar por completo el iniciador predeterminado.
Abrir el widget
Llamar a uj.open() sin argumentos abre el widget donde lo dejó el usuario:
uj.open();Pasa un destino para abrir una sección específica:
uj.open({ to: 'home' });
uj.open({ to: 'feedback' });
uj.open({ to: 'roadmap' });
uj.open({ to: 'updates' });
uj.open({ to: 'messages' });
uj.open({ to: 'notifications' });
uj.open({ to: 'help' });Opciones de enlace directo para destinos específicos:
// Open the feedback submission form directly
uj.open({ to: 'feedback', compose: true });
// Open a specific feedback post
uj.open({ to: 'feedback', submissionId: 'POST_ID' });
// Open a specific changelog update
uj.open({ to: 'updates', updateId: 'UPDATE_ID' });
// Start a message with prefilled text
uj.open({ to: 'messages', compose: { text: 'I need help with...' } });
// Open a help article, collection, or search results
uj.open({ to: 'help', article: 'reset-password' });
uj.open({ to: 'help', collection: 'billing' });
uj.open({ to: 'help', query: 'invoices' });Oculta o alterna el widget en cualquier momento:
uj.close();
uj.toggle();El destino messages requiere que Conversaciones esté habilitado; de lo contrario, informa CONVERSATIONS_DISABLED mediante el evento error y abre Inicio. El destino help requiere que tu Centro de ayuda esté publicado (article y collection usan el slug de la URL); de lo contrario, informa HELP_DISABLED y abre Inicio.
Escuchar eventos
Suscríbete con uj.on(event, listener), que devuelve una función para cancelar la suscripción:
const unsubscribe = uj.on('open', () => {
console.log('widget opened');
});
unsubscribe();Evento | Cuándo se activa |
|---|---|
| El SDK terminó de cargarse. Se activa inmediatamente si ya se había cargado. |
| El widget se hizo visible. |
| El widget se ocultó. |
| La identidad cambió, incluido el cierre de sesión. |
| El recuento de elementos sin leer cambió. La carga útil es |
| La disponibilidad del equipo cambió. La carga útil es |
| Cambió alguna parte del estado del widget. |
| Se produjo un error. La carga útil es el objeto de error. |
Leer el estado
uj.getState() devuelve una instantánea del estado actual del widget:
const state = uj.getState();
state.status; // 'ready' once the SDK is loaded
state.widget.open; // whether the widget is visible
state.unreadCount; // number, or null before the first fetch
state.presence; // 'online' or 'neutral'
state.session.status; // 'anonymous', 'identifying', or 'identified'
state.session.viewer; // the identified user, or nullCrear tu propio botón de inicio
Oculta el iniciador predeterminado para controlar el widget desde tu propio elemento de navegación o botón:
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false }
});Al ocultar el iniciador, se quita el botón predeterminado y se mantienen activos los susurros de notificación en la esquina (consulta la sección Susurros más abajo para cambiar su posición o desactivarlos).
Configura tu botón, el indicador de elementos sin leer y, opcionalmente, el indicador de disponibilidad del equipo:
const button = document.querySelector('#feedback-button');
const badge = document.querySelector('#feedback-badge');
const dot = document.querySelector('#feedback-online-dot');
button.addEventListener('click', () => uj.toggle());
uj.on('unread', ({ count }) => {
badge.textContent = count > 0 ? String(count) : '';
});
uj.on('presence', ({ availability }) => {
dot.hidden = availability !== 'online';
});'neutral' significa que el SDK no puede confirmar que haya un operador en línea, así que oculta el indicador en lugar de mostrar una etiqueta de desconectado. Cuando el widget está cerrado, la presencia se actualiza al cargar la página, al enfocar la pestaña y cada pocos minutos; cuando está abierto, se actualiza en tiempo real.
En el lanzador predeterminado, el indicador de elementos sin leer tiene prioridad sobre el punto verde de presencia en línea. El recuento de elementos sin leer incluye respuestas a conversaciones, publicaciones del registro de cambios y notificaciones de comentarios. Al hacer clic en el lanzador predeterminado mientras hay elementos sin leer pendientes, se accede a ellos en este orden de prioridad: Mensajes (respuestas sin leer a conversaciones), luego Notificaciones (notificaciones de comentarios sin ver) y, por último, la Actualización más reciente que no se haya visto.
Para vincular directamente el comportamiento del iniciador predeterminado a un elemento existente de tu página, pasa un selector CSS:
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: { selector: '#feedback-button' } }
});Avisos
Los avisos emergentes son notificaciones breves y en las que se puede hacer clic, que aparecen en una esquina para anunciar respuestas sin leer a conversaciones del equipo, notificaciones de comentarios y nuevas publicaciones del registro de cambios. La prioridad sigue este orden: primero, respuestas sin leer a conversaciones; luego, notificaciones de comentarios o respuestas; después, otras notificaciones; y, por último, actualizaciones del registro de cambios. Por privacidad, los avisos de conversaciones solo muestran el avatar del compañero de equipo y <Name> replied (nunca el texto del mensaje), y al hacer clic se abre Mensajes.
Vigencia y tiempos: Solo aparecen avisos de elementos creados o publicados en los últimos 14 días. El widget espera a que haya actividad real del usuario, 4 segundos en la página, 1,2 segundos sin actividad y al menos 30 segundos desde el aviso anterior. Los avisos nunca interrumpen mientras el usuario escribe en un campo de entrada, un área de texto, un selector o un campo editable, ni dentro de navegadores automatizados.
Límites de repetición y pausas: Cada elemento genera avisos como máximo 3 veces (se requieren 1,5 segundos de visibilidad con atención para que cuente como entregado), con intervalos crecientes de 30 minutos, 24 horas y 3 días para las actualizaciones, o de 30 minutos, 1 hora y 24 horas para las notificaciones y las respuestas a conversaciones.
Con o sin el lanzador predeterminado: Los avisos emergentes son independientes del lanzador. Con el lanzador predeterminado, se despliegan desde el botón; con
launcher: falseo un lanzador de selector, aparecen por sí solos en una esquina y, al agotarse el tiempo, se contraen en un círculo en el que se puede hacer clic. Permanecen así durante 60 segundos antes de ocultarse.
Desplaza los susurros para que no se superpongan con tu propia interfaz usando offset:
uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: false,
offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
}
});También puedes desactivar por completo los avisos emergentes (se suprimirán los avisos de conversaciones, comentarios y actualizaciones predeterminadas):
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false, whispers: false }
});Si ambas opciones están desactivadas y no se especifica un modo de actualización, el widget no muestra nada hasta que llames a uj.open(), mientras que las suscripciones unread y presence siguen actualizándose en segundo plano.
Anuncios de novedades
Controla cómo anuncia el widget la última entrada del registro de cambios que aún no se ha visto con widget.notifications.updates:
uj.init('YOUR_PROJECT_ID', {
widget: {
notifications: { updates: 'full' }
}
});Modo | Comportamiento |
|---|---|
| Anuncia la novedad en una notificación emergente en una esquina, con límites de repetición. |
| Abre la novedad directamente en el lector del widget, con su imagen de portada y el contenido completo. |
| Suprime los anuncios de novedades y mantiene activa la pestaña Actualizaciones y el indicador de elementos sin leer. |
Si se omite, las actualizaciones usan 'whisper' de forma predeterminada (o 'none' cuando whispers: false). Al establecer widget.notifications.updates explícitamente, se anula whispers solo para las actualizaciones del registro de cambios; los avisos de conversaciones y comentarios siguen usando whispers.
El modo completo funciona incluso con el iniciador oculto y sin detectores de eventos. En una primera visita, el modo completo puede abrir la última actualización publicada aunque sea antigua. El SDK intenta abrir el widget automáticamente como máximo una vez por visita de inicialización (una apertura manual, una alternancia, un cierre o un intento fallido consume esa oportunidad; volver a cargar la página o llamar a init() inicia una nueva visita, mientras que los cambios de identidad o la navegación de una SPA no lo hacen). La apertura automática requiere que la página esté visible y enfocada, y que el widget esté cerrado; además, se desactiva cuando widget: false.
Una actualización se marca como vista cuando su contenido se muestra en el widget, si la página está visible y enfocada. El estado de lectura se guarda localmente en el almacenamiento del navegador por proyecto y origen. Las actualizaciones se detectan durante la inicialización, al enfocar la pestaña y aproximadamente cada cinco minutos mientras el widget está cerrado.
Cambiar el idioma
Si se omite locale, el widget elige un idioma siguiendo este orden:
Una opción
localeexplícita pasada auj.init(...)ouj.setLocale(...).El idioma del navegador del visitante, si coincide con alguno de los idiomas habilitados de tu espacio de trabajo en Configuración → Idiomas.
El idioma predeterminado de tu espacio de trabajo.
El widget admite los 14 idiomas de UserJot (consulta Idiomas). Puedes cambiarlo al inicializar o durante la ejecución, sin volver a cargar la página:
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });
// Change later at runtime
await uj.setLocale('pt-BR');