Referencia del SDK
El SDK se expone como window.uj. Las llamadas sin espera realizadas mediante el proxy en línea de precarga (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) se ponen en cola y se reproducen cuando se carga uj.js. Las llamadas que devuelven valores o promesas (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) requieren que el script del SDK se haya cargado primero.
uj.version
La cadena de versión del SDK, por ejemplo 1.0.0.
uj.init(projectId, options?)
Inicializa el SDK. Devuelve una promesa que se resuelve con el estado del SDK cuando termina la carga.
const state = await uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: true, // boolean or { selector: string }
whispers: true, // default whisper behavior
notifications: { updates: 'whisper' }, // 'whisper', 'full', or 'none'
position: 'right', // 'left' or 'right'
offset: { bottom: 20 }, // corner distance in pixels: { bottom, side }
theme: 'auto' // 'auto', 'light', or 'dark'
},
locale: 'es-MX', // optional language override
pageContext: 'origin', // 'origin', 'path', or 'none'
onReady: () => {},
onError: (error) => {}
});Opción | Predeterminado | Descripción |
|---|---|---|
|
|
|
|
|
|
|
| Notificaciones efímeras que aparecen en la esquina del widget. Son independientes del botón de apertura: siguen apareciendo cuando el botón está oculto, a menos que se establezcan en |
|
|
|
|
| El lado de la pantalla en el que se abre el widget. |
|
| Distancia en píxeles entre el lanzador y los susurros, y los bordes de la ventana gráfica. |
|
| Seguir la configuración del sistema o forzar el modo claro u oscuro. |
| navegador → valor predeterminado del espacio de trabajo | Anulación del idioma. Si se omite, se compara el idioma del navegador del visitante con los idiomas habilitados en el espacio de trabajo y, si no hay coincidencia, se usa el idioma predeterminado del espacio de trabajo. Admite los 14 idiomas de UserJot; las etiquetas regionales, como |
|
| Qué parte de la URL de la página actual se comparte con tu equipo en las conversaciones y en Live visitors. |
| Se llama cuando el SDK está listo. | |
| Se llama cuando ocurre cualquier error del SDK. |
La promesa devuelta no se rechaza por problemas de red (consulta state.status === 'ready'). Solo se rechaza por errores de programación, como un ID de proyecto vacío o unas opciones con formato incorrecto (INVALID_OPTIONS, recoverable: false).
El modo de actualización completa funciona sin lanzador, susurros ni suscripciones del sitio anfitrión. Consulta Anuncios de actualizaciones para conocer las reglas exactas de visibilidad, enfoque y almacenamiento de las entradas vistas.
uj.ready()
Devuelve la misma promesa que init. Es útil cuando el código que necesita el SDK está separado de la inicialización.
const state = await uj.ready();uj.identify(input)
Identifica al usuario actual. Devuelve una promesa con el resultado. Consulta Identificar usuarios y Identidad firmada.
const result = await uj.identify({
token: 'OPTIONAL_JWT_FROM_YOUR_SERVER',
user: {
id: 'user-123', // required if no token is given
email: 'ada@example.com',
firstName: 'Ada',
lastName: 'Lovelace',
avatar: 'https://example.com/avatar.jpg',
traits: { plan: 'pro' }
},
companies: [
{
id: 'acme',
name: 'ACME Inc.',
domain: 'acme.com',
logo: 'https://acme.com/logo.png',
traits: { plan: 'enterprise' }
}
]
});
result.viewer; // the identified user, or null
result.identityTrust; // 'signed', 'unsigned', or null
result.warnings; // [{ code, message, field? }]viewer tiene esta estructura:
{
id: 'mem_...', // UserJot's member ID, not the user.id you sent
firstName: 'Ada', // string or null
lastName: 'Lovelace', // string or null
avatar: { url: 'https://...', blurhash: '...' } // or null; blurhash optional
}Advertencias y claves de atributos reservadas
Código |
| Significado |
|---|---|---|
| La clave del atributo | La clave está reservada por UserJot y se descartó. |
| La empresa | El espacio de trabajo requiere una pertenencia a la empresa firmada, y esta empresa no figuraba en el token. |
|
| El usuario es administrador o propietario de un espacio de trabajo. Se aplican sus atributos y empresas; su nombre, avatar y correo electrónico se gestionan en el dashboard. |
Las siguientes claves de atributos están reservadas y se ignoran (lo que genera RESERVED_TRAIT_KEY_IGNORED): id, externalId, external_id, email, name, firstName, first_name, lastName, last_name, avatar, avatarUrl, avatar_url, role, type, companies, company, companyId, company_id, createdAt, created_at, updatedAt, updated_at, deletedAt, deleted_at y __proto__.
Se requiere al menos uno de token o user.id. Volver a llamar a identify con la misma entrada no hace nada mientras la sesión siga activa; una vez que haya caducado, la misma entrada envía una nueva solicitud. Si se llama con una entrada distinta, cambia la sesión. Si se superponen varias llamadas, prevalece la última. identify es el único método que devuelve un rechazo ante errores en tiempo de ejecución (IDENTIFY_FAILED), y aplica un período de espera local tras respuestas HTTP 429 (respeta Retry-After, con un límite de entre 1 segundo y 1 hora, y un valor predeterminado de 60 segundos).
uj.logout()
Borra la identidad actual y devuelve la sesión al estado anónimo.
await uj.logout();uj.open(target?)
Abre el widget. Si no se proporciona ningún argumento, lo abre donde el usuario lo dejó. Se resuelve cuando el widget está visible.
await uj.open();
await uj.open({ to: 'home' });
await uj.open({ to: 'feedback' });
await uj.open({ to: 'feedback', compose: true });
await uj.open({ to: 'feedback', submissionId: 'POST_ID' });
await uj.open({ to: 'roadmap' });
await uj.open({ to: 'updates' });
await uj.open({ to: 'updates', updateId: 'UPDATE_ID' });
await uj.open({ to: 'messages' });
await uj.open({ to: 'messages', compose: { text: 'Prefilled message' } });
await uj.open({ to: 'notifications' });
await uj.open({ to: 'help' });
await uj.open({ to: 'help', article: 'ARTICLE_SLUG' });
await uj.open({ to: 'help', collection: 'COLLECTION_SLUG' });
await uj.open({ to: 'help', query: 'Search text' });El destino de help acepta como máximo uno de article, collection o query. article y collection reciben el slug de la URL; los slugs antiguos redirigen a la página reubicada. Se rechaza con INVALID_NAVIGATION si el destino es desconocido o la combinación no es válida.
uj.close()
Oculta el widget. Es síncrono y se puede llamar en cualquier momento de forma segura.
uj.toggle()
Abre el widget si está cerrado y lo cierra si está abierto.
uj.createEmbed(options?)
Muestra una página de UserJot dentro de un contenedor de tu página. Devuelve un controlador. Consulta Insertar páginas en línea.
const embed = uj.createEmbed({
container: '[data-userjot-embed]',
path: '/',
basePath: '/feedback',
theme: 'auto',
onReady: () => {},
onError: (error) => {}
});
embed.navigate('/roadmap');
embed.destroy();uj.setLocale(locale)
Cambia el idioma del widget durante la ejecución:
await uj.setLocale('pt-BR');uj.setTheme(theme)
Cambia el tema del widget de forma síncrona ('auto', 'light' o 'dark'). Los valores no válidos generan INVALID_OPTIONS mediante el evento error. Como init siempre aplica su propio tema (de forma predeterminada, 'auto'), pasa el tema inicial en init en lugar de llamar a setTheme antes de init.
uj.getState()
Devuelve una instantánea de solo lectura del estado del SDK:
{
status: 'ready', // 'idle' | 'initializing' | 'ready' | 'error' | 'destroyed'
projectId: 'proj_...',
locale: 'en-US',
unreadCount: 3, // number, or null before the first fetch
presence: 'online', // 'online' | 'neutral'
lastError: null,
widget: {
enabled: true,
open: false,
position: 'right',
theme: 'auto'
},
session: {
status: 'identified', // 'anonymous' | 'identifying' | 'identified'
identityTrust: 'signed',
viewer: { id: 'mem_...', firstName: 'Ada', lastName: 'Lovelace', avatar: null }
}
}uj.on(event, listener)
Se suscribe a un evento y devuelve una función para cancelar la suscripción. Los oyentes permanecen activos después de destroy().
Evento | Carga útil | Cuándo se activa |
|---|---|---|
| state | La carga ha finalizado. Se reproduce de inmediato si ya había finalizado. |
| state | Cualquier cambio de estado. |
| state | El widget se hizo visible. |
| state | El widget se ocultó. |
|
| La identidad cambió, incluido al cerrar la sesión. |
|
| El recuento de elementos no leídos ha cambiado. Se reproduce de inmediato si el SDK ya está listo y se han obtenido los datos. |
|
| La disponibilidad del equipo cambió entre |
| error | Cualquier error del SDK. |
| state | Se destruyó el SDK. |
Suscribirse a unread o presence mantiene ambos valores actualizados en segundo plano, aunque el lanzador predeterminado esté oculto.
uj.destroy(options?)
Elimina el widget, todas las inserciones y la sesión de la página:
uj.destroy();
uj.destroy({ clearConversationData: true });clearConversationData también borra las autorizaciones locales de conversaciones anónimas, los borradores y los datos de contacto guardados (útil en dispositivos compartidos).
Atributos DOM para la captura de capturas de pantalla
Cuando un usuario captura una captura de pantalla de la página desde el compositor de comentarios del widget (alternativa de captura del DOM), UserJot oculta automáticamente las superficies del widget y enmascara input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] y input[name*="secret" i]. También puedes controlar la captura en elementos específicos con atributos HTML:
Atributo | Efecto durante la captura de una captura de pantalla de la página |
|---|---|
| Excluye por completo el elemento de la captura de pantalla. |
| Oculta el contenido visible del elemento en la captura de pantalla. |
| Enmascara automáticamente los campos sensibles |
Errores
Los errores tienen la estructura { code, message, recoverable, cause? }.
Código | Significado |
|---|---|
| Se llamó a |
|
|
|
|
| A la entrada de |
| El servidor rechazó la llamada a identify (por ejemplo, por un token no válido, la falta de una firma en modo estricto, un conflicto de |
| No se pudo cargar el SDK. Comprueba el ID del proyecto, las reglas de CSP y la conexión de red. |
| Se ejecutó una llamada mientras el SDK se encontraba en estado de error. |
| Se llamó a |
| Los mensajes están desactivados para este espacio de trabajo. En su lugar, el widget abre Inicio. |
| El Centro de ayuda no está publicado para este espacio de trabajo. En su lugar, el widget abre Inicio. |
| El elemento |
| No se pudo cargar la interfaz del widget. |
| El contenedor de inserción no existe. |
| Se ejecutó una llamada después de |
| Cualquier otra cosa. |