Referencia del SDK

Shayan TaslimActualizado

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.

JavaScript
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

widget

true

true muestra el widget con los valores predeterminados. false lo desactiva. Un objeto permite configurarlo.

widget.launcher

true

false oculta el botón predeterminado. { selector } vincula el widget a tu propio elemento.

widget.whispers

true

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 false. Un modo explícito de notificación de actualizaciones anula este ajuste solo para los anuncios del registro de cambios. Consulta Controlar el widget.

widget.notifications.updates

'whisper', o 'none' cuando whispers: false

'whisper' anuncia las actualizaciones en una notificación emergente; 'full' abre la última entrada no vista en el lector del widget; 'none' suprime los anuncios de actualizaciones sin marcar las entradas como leídas. Los valores explícitos prevalecen sobre whispers solo para las actualizaciones.

widget.position

'right'

El lado de la pantalla en el que se abre el widget.

widget.offset

{ bottom: 20, side: 20 }

Distancia en píxeles entre el lanzador y los susurros, y los bordes de la ventana gráfica.

widget.theme

'auto'

Seguir la configuración del sistema o forzar el modo claro u oscuro.

locale

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 es-MX, se resuelven al idioma correspondiente.

pageContext

'origin'

Qué parte de la URL de la página actual se comparte con tu equipo en las conversaciones y en Live visitors. 'origin' envía solo el nombre de host, 'path' incluye la ruta (se eliminan las cadenas de consulta y #fragments), 'none' no envía nada.

onReady

Se llama cuando el SDK está listo.

onError

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.

JavaScript
const state = await uj.ready();

uj.identify(input)

Identifica al usuario actual. Devuelve una promesa con el resultado. Consulta Identificar usuarios y Identidad firmada.

JavaScript
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:

JavaScript
{
  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

field

Significado

RESERVED_TRAIT_KEY_IGNORED

La clave del atributo

La clave está reservada por UserJot y se descartó.

UNSIGNED_COMPANY_IGNORED

La empresa id

El espacio de trabajo requiere una pertenencia a la empresa firmada, y esta empresa no figuraba en el token.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar o email

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.

JavaScript
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.

JavaScript
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.

JavaScript
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:

JavaScript
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:

JavaScript
{
  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

ready

state

La carga ha finalizado. Se reproduce de inmediato si ya había finalizado.

statechange

state

Cualquier cambio de estado.

open

state

El widget se hizo visible.

close

state

El widget se ocultó.

identify

{ viewer, identityTrust }

La identidad cambió, incluido al cerrar la sesión.

unread

{ count }

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.

presence

{ availability }

La disponibilidad del equipo cambió entre 'online' y 'neutral'. Se reproduce de inmediato si el SDK ya está listo.

error

error

Cualquier error del SDK.

destroy

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:

JavaScript
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

data-userjot-capture-ignore

Excluye por completo el elemento de la captura de pantalla.

data-userjot-capture-mask

Oculta el contenido visible del elemento en la captura de pantalla.

data-userjot-sensitive

Enmascara automáticamente los campos sensibles <textarea>.

Errores

Los errores tienen la estructura { code, message, recoverable, cause? }.

Código

Significado

INVALID_PROJECT_ID

Se llamó a init con un ID de proyecto vacío.

INVALID_OPTIONS

init, setLocale o setTheme recibió opciones no válidas.

INVALID_NAVIGATION

open recibió un destino desconocido o no válido.

INVALID_IDENTIFY

A la entrada de identify le faltan tanto token como user.id.

IDENTIFY_FAILED

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 409, un límite de solicitudes o un miembro eliminado).

BOOTSTRAP_FAILED

No se pudo cargar el SDK. Comprueba el ID del proyecto, las reglas de CSP y la conexión de red.

NOT_READY

Se ejecutó una llamada mientras el SDK se encontraba en estado de error.

WIDGET_DISABLED

Se llamó a open cuando el widget estaba desactivado.

CONVERSATIONS_DISABLED

Los mensajes están desactivados para este espacio de trabajo. En su lugar, el widget abre Inicio.

HELP_DISABLED

El Centro de ayuda no está publicado para este espacio de trabajo. En su lugar, el widget abre Inicio.

LAUNCHER_NOT_FOUND

El elemento launcher.selector no existe.

SIDEBAR_LOAD_FAILED

No se pudo cargar la interfaz del widget.

EMBED_CONTAINER_NOT_FOUND

El contenedor de inserción no existe.

DESTROYED

Se ejecutó una llamada después de destroy().

UNKNOWN

Cualquier otra cosa.

¿Respondió esto a tu pregunta?