Riferimento SDK
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.
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 |
|---|---|---|
|
|
|
|
|
|
|
| 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 |
|
|
|
|
| Il lato dello schermo da cui si apre il widget. |
|
| Distanza in pixel del launcher e dei messaggi sussurrati dai bordi dell’area visibile. |
|
| Segui le impostazioni di sistema oppure forza la modalità chiara o scura. |
| 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 |
|
| Quanta parte dell’URL della pagina corrente viene condivisa con il tuo team nelle conversazioni e in Visitatori in tempo reale. |
| Chiamato quando l’SDK è pronto. | |
| 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.
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.
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:
{
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 |
| Significato |
|---|---|---|
| La chiave dell’attributo | La chiave è riservata da UserJot ed è stata ignorata. |
| L’azienda | L’area di lavoro richiede l’appartenenza firmata all’azienda e questa azienda non era inclusa nel token. |
|
| 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.
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.
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.
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:
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:
{
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 |
|---|---|---|
| stato | Caricamento completato. Se il caricamento è già stato completato, l’evento viene riprodotto immediatamente. |
| stato | A ogni modifica dello stato. |
| stato | Il widget è diventato visibile. |
| stato | Il widget è stato nascosto. |
|
| L’identità è cambiata, anche in caso di disconnessione. |
|
| Il conteggio dei non letti è cambiato. Se il widget è già pronto e i dati sono stati recuperati, l’evento viene riprodotto immediatamente. |
|
| La disponibilità del team è passata da |
| errore | Qualsiasi errore dell’SDK. |
| 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:
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 |
|---|---|
| Esclude completamente l’elemento dallo screenshot acquisito. |
| Oscura il contenuto visibile dell’elemento nello screenshot acquisito. |
| Maschera automaticamente i campi |
Errori
Gli errori hanno la forma { code, message, recoverable, cause? }.
Codice | Significato |
|---|---|
|
|
|
|
|
|
| Nell'input di |
| Il server ha rifiutato la chiamata identify (ad esempio, token non valido, firma mancante in modalità strict, conflitto |
| Impossibile caricare l’SDK. Controlla l’ID progetto, le regole CSP e la rete. |
| È stata eseguita una chiamata mentre l'SDK si trovava in uno stato di errore. |
|
|
| I messaggi sono disabilitati per questa area di lavoro. Il widget apre invece Home. |
| Il Centro assistenza non è attivo per questa area di lavoro. Il widget apre invece Home. |
| L'elemento |
| Impossibile caricare l'interfaccia del widget. |
| Il contenitore dell'embed non esiste. |
| È stata eseguita una chiamata dopo |
| Qualsiasi altra cosa. |