Riferimento SDK

Shayan TaslimAggiornato

L’SDK è esposto come window.uj. Le chiamate fire-and-forget effettuate tramite il proxy inline di pre-caricamento (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) vengono accodate e riprodotte una volta caricato uj.js. Le chiamate che restituiscono valori o promise (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) richiedono che lo script dell’SDK sia già stato caricato.

uj.version

La stringa della versione dell’SDK, ad esempio 1.0.0.

uj.init(projectId, options?)

Inizializza l’SDK. Restituisce una promise che si risolve con lo stato dell’SDK al termine del caricamento.

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) => {}
});

Opzione

Predefinito

Descrizione

widget

true

true mostra il widget con le impostazioni predefinite. false lo disattiva. Un oggetto consente di configurarlo.

widget.launcher

true

false nasconde il pulsante predefinito. { selector } collega il widget a un elemento personalizzato.

widget.whispers

true

Notifiche temporanee visualizzate nell’angolo del widget. Sono indipendenti dal pulsante di apertura: continuano a essere mostrate quando il pulsante è nascosto, a meno che non siano impostate su false. Una modalità di notifica degli aggiornamenti esplicita sostituisce questa impostazione solo per gli annunci del changelog. Vedi Controllare il widget.

widget.notifications.updates

'whisper', oppure 'none' quando whispers: false

'whisper' annuncia gli aggiornamenti in una notifica toast; 'full' apre l’ultima voce non ancora visualizzata nel lettore del widget; 'none' sopprime gli annunci degli aggiornamenti mantenendoli come non letti. I valori espliciti prevalgono su whispers solo per gli aggiornamenti.

widget.position

'right'

Il lato dello schermo da cui si apre il widget.

widget.offset

{ bottom: 20, side: 20 }

Distanza in pixel del launcher e dei messaggi sussurrati dai bordi dell’area visibile.

widget.theme

'auto'

Segui le impostazioni di sistema oppure forza la modalità chiara o scura.

locale

browser → impostazione predefinita dell’area di lavoro

Override della lingua. Se omesso, confronta la lingua del browser del visitatore con quelle abilitate nell’area di lavoro, quindi ripiega sulla lingua predefinita dell’area di lavoro. Supporta tutte le 14 lingue di UserJot; i tag regionali, come es-MX, vengono ricondotti alla rispettiva lingua.

pageContext

'origin'

Quanta parte dell’URL della pagina corrente viene condivisa con il tuo team nelle conversazioni e in Visitatori in tempo reale. 'origin' invia solo il nome host, 'path' include il percorso (senza stringhe di query né #fragments), 'none' non invia nulla.

onReady

Chiamato quando l’SDK è pronto.

onError

Chiamato in caso di qualsiasi errore dell’SDK.

La promise restituita non viene rifiutata in caso di problemi di rete (controlla state.status === 'ready'). Viene rifiutata solo in caso di errori di programmazione, ad esempio un ID progetto vuoto o opzioni non valide (INVALID_OPTIONS, recoverable: false).

La modalità di aggiornamento completa funziona senza launcher, messaggi sussurrati o sottoscrizioni dell’host. Per le regole esatte relative a visibilità, focus e memorizzazione delle voci visualizzate, consulta Annunci degli aggiornamenti.

uj.ready()

Restituisce la stessa promise di init. Utile quando il codice che necessita dell’SDK è separato da quello di inizializzazione.

JavaScript
const state = await uj.ready();

uj.identify(input)

Identifica l’utente corrente. Restituisce una promise con il risultato. Vedi Identificare gli utenti e Identità firmata.

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 ha questa struttura:

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
}

Avvisi e chiavi di trait riservate

Codice

field

Significato

RESERVED_TRAIT_KEY_IGNORED

La chiave dell’attributo

La chiave è riservata da UserJot ed è stata ignorata.

UNSIGNED_COMPANY_IGNORED

L’azienda id

L’area di lavoro richiede l’appartenenza firmata all’azienda e questa azienda non era inclusa nel token.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar o email

L’utente è un amministratore o proprietario dell’area di lavoro. I suoi attributi e le aziende si applicano; il nome, l’avatar e l’indirizzo email sono gestiti nella dashboard.

Le seguenti chiavi di trait sono riservate e ignorate (generano 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 e __proto__.

È necessario specificare almeno uno tra token e user.id. Chiamare di nuovo identify con lo stesso input non produce effetti finché la sessione è attiva; una volta scaduta, lo stesso input invia una nuova richiesta. Chiamarlo con un nuovo input cambia sessione. Se più chiamate si sovrappongono, prevale l’ultima. identify è l’unico metodo che restituisce un rifiuto in caso di errori di runtime (IDENTIFY_FAILED); inoltre, applica un periodo di backoff locale dopo le risposte HTTP 429 (rispettando Retry-After, con un intervallo limitato da 1 secondo a 1 ora e un valore predefinito di 60 secondi).

uj.logout()

Cancella l’identità corrente e riporta la sessione allo stato anonimo.

JavaScript
await uj.logout();

uj.open(target?)

Apre il widget. Se non viene specificato alcun argomento, lo apre nella posizione in cui l’utente si era fermato. La promise viene risolta quando il widget è visibile.

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' });

Il target help accetta al massimo uno tra article, collection e query. article e collection accettano lo slug dell’URL e gli slug precedenti reindirizzano alla pagina a cui sono stati spostati. Viene rifiutato con INVALID_NAVIGATION se il target è sconosciuto o la combinazione non è valida.

uj.close()

Nasconde il widget. È sincrono e può essere chiamato in qualsiasi momento senza rischi.

uj.toggle()

Apre il widget se è chiuso e lo chiude se è aperto.

uj.createEmbed(options?)

Visualizza una pagina UserJot all’interno di un contenitore nella tua pagina. Restituisce un controller. Consulta Incorporare pagine in linea.

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)

Modifica la lingua del widget durante l’esecuzione:

JavaScript
await uj.setLocale('pt-BR');

uj.setTheme(theme)

Modifica il tema del widget in modo sincrono ('auto', 'light' o 'dark'). I valori non validi generano INVALID_OPTIONS tramite l’evento error. Poiché init applica sempre il proprio tema (che per impostazione predefinita è 'auto'), specifica il tema iniziale in init invece di chiamare setTheme prima di init.

uj.getState()

Restituisce un’istantanea di sola lettura dello stato dell’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)

Si sottoscrive a un evento e restituisce una funzione per annullare la sottoscrizione. I listener rimangono attivi dopo destroy().

Evento

Payload

Quando viene generato

ready

stato

Caricamento completato. Se il caricamento è già stato completato, l’evento viene riprodotto immediatamente.

statechange

stato

A ogni modifica dello stato.

open

stato

Il widget è diventato visibile.

close

stato

Il widget è stato nascosto.

identify

{ viewer, identityTrust }

L’identità è cambiata, anche in caso di disconnessione.

unread

{ count }

Il conteggio dei non letti è cambiato. Se il widget è già pronto e i dati sono stati recuperati, l’evento viene riprodotto immediatamente.

presence

{ availability }

La disponibilità del team è passata da 'online' a 'neutral' o viceversa. Se il widget è già pronto, l’evento viene riprodotto immediatamente.

error

errore

Qualsiasi errore dell’SDK.

destroy

stato

L’SDK è stato distrutto.

La sottoscrizione a unread o presence mantiene aggiornati entrambi i valori in background, anche quando il launcher predefinito è nascosto.

uj.destroy(options?)

Rimuove dalla pagina il widget, tutti gli embed e la sessione:

JavaScript
uj.destroy();
uj.destroy({ clearConversationData: true });

clearConversationData cancella anche le autorizzazioni locali per le conversazioni anonime, le bozze e i dati di contatto salvati (utile sui dispositivi condivisi).

Attributi DOM per l’acquisizione di screenshot

Quando un utente acquisisce uno screenshot della pagina dal compositore di feedback del widget (fallback di acquisizione del DOM), UserJot nasconde automaticamente le superfici del widget e maschera input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] e input[name*="secret" i]. Puoi anche controllare l’acquisizione su elementi specifici con attributi HTML:

Attributo

Effetto durante l’acquisizione di screenshot della pagina

data-userjot-capture-ignore

Esclude completamente l’elemento dallo screenshot acquisito.

data-userjot-capture-mask

Oscura il contenuto visibile dell’elemento nello screenshot acquisito.

data-userjot-sensitive

Maschera automaticamente i campi <textarea> sensibili.

Errori

Gli errori hanno la forma { code, message, recoverable, cause? }.

Codice

Significato

INVALID_PROJECT_ID

init è stato chiamato con un ID progetto vuoto.

INVALID_OPTIONS

init, setLocale o setTheme hanno ricevuto opzioni non valide.

INVALID_NAVIGATION

open ha ricevuto una destinazione sconosciuta o non valida.

INVALID_IDENTIFY

Nell'input di identify mancano sia token sia user.id.

IDENTIFY_FAILED

Il server ha rifiutato la chiamata identify (ad esempio, token non valido, firma mancante in modalità strict, conflitto 409, limite di richieste raggiunto o membro cancellato).

BOOTSTRAP_FAILED

Impossibile caricare l’SDK. Controlla l’ID progetto, le regole CSP e la rete.

NOT_READY

È stata eseguita una chiamata mentre l'SDK si trovava in uno stato di errore.

WIDGET_DISABLED

open è stato chiamato mentre il widget è disabilitato.

CONVERSATIONS_DISABLED

I messaggi sono disabilitati per questa area di lavoro. Il widget apre invece Home.

HELP_DISABLED

Il Centro assistenza non è attivo per questa area di lavoro. Il widget apre invece Home.

LAUNCHER_NOT_FOUND

L'elemento launcher.selector non esiste.

SIDEBAR_LOAD_FAILED

Impossibile caricare l'interfaccia del widget.

EMBED_CONTAINER_NOT_FOUND

Il contenitore dell'embed non esiste.

DESTROYED

È stata eseguita una chiamata dopo destroy().

UNKNOWN

Qualsiasi altra cosa.

Ha risposto alla tua domanda?