SDK-referentie
De SDK is beschikbaar als window.uj. Aanroepen zonder resultaat af te wachten via de inline proxy voor het laden (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) worden in de wachtrij gezet en opnieuw uitgevoerd zodra uj.js is geladen. Voor aanroepen die waarden of promises retourneren (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) moet het SDK-script eerst zijn geladen.
uj.version
De SDK-versietekst, bijvoorbeeld 1.0.0.
uj.init(projectId, options?)
Initialiseert de SDK. Geeft een promise terug die wordt opgelost met de SDK-status zodra het laden is voltooid.
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) => {}
});Optie | Standaard | Beschrijving |
|---|---|---|
|
|
|
|
|
|
|
| Tijdelijke notificatietoasts in de hoek van de widget. Ze werken onafhankelijk van de opener: ze blijven verschijnen als de knop verborgen is, tenzij dit is ingesteld op |
|
|
|
|
| Aan welke kant van het scherm de widget wordt geopend. |
|
| Afstand in pixels tussen de launcher en whispers en de randen van de viewport. |
|
| Volg de systeeminstelling of forceer de lichte of donkere modus. |
| browser → standaardinstelling van de workspace | Taaloverschrijving. Als deze ontbreekt, wordt de browsertaal van de bezoeker vergeleken met de ingeschakelde talen van je workspace. Als er geen overeenkomst is, wordt de standaardtaal van de workspace gebruikt. Ondersteunt alle 14 UserJot-talen; regionale tags zoals |
|
| Hoeveel van de URL van de huidige pagina met je team wordt gedeeld in gesprekken en Live bezoekers. |
| Wordt aangeroepen zodra de SDK klaar is. | |
| Wordt aangeroepen bij elke SDK-fout. |
De geretourneerde promise wordt niet afgewezen bij netwerkproblemen (controleer state.status === 'ready'). Afwijzing vindt alleen plaats bij programmeerfouten, zoals een lege project-ID of onjuist opgemaakte opties (INVALID_OPTIONS, recoverable: false).
De volledige updatemodus werkt zonder launcher, whispers of abonnementen op hostgebeurtenissen. Zie Updateaankondigingen voor de exacte regels voor zichtbaarheid, focus en opslag van de gelezen status.
uj.ready()
Retourneert dezelfde promise als init. Handig wanneer de code die de SDK nodig heeft losstaat van de initialisatie.
const state = await uj.ready();uj.identify(input)
Identificeert de huidige gebruiker. Geeft een promise met het resultaat terug. Zie Gebruikers identificeren en Ondertekende identiteit.
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 heeft deze vorm:
{
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
}Waarschuwingen en gereserveerde trait-sleutels
Code |
| Betekenis |
|---|---|---|
| De kenmerkensleutel | De sleutel is gereserveerd door UserJot en is genegeerd. |
| Het bedrijf | De werkruimte vereist ondertekend lidmaatschap van het bedrijf en dit bedrijf stond niet in het token. |
|
| De gebruiker is beheerder of eigenaar van een werkruimte. Hun kenmerken en bedrijven worden toegepast; hun naam, avatar en e-mailadres worden beheerd in het dashboard. |
De volgende trait-sleutels zijn gereserveerd en worden genegeerd (waarbij RESERVED_TRAIT_KEY_IGNORED wordt uitgezonden): 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 en __proto__.
Minstens één van token of user.id is vereist. Als je identify opnieuw aanroept met dezelfde invoer, gebeurt er niets zolang de sessie nog actief is; zodra deze is verlopen, verstuurt dezelfde invoer een nieuw verzoek. Bij nieuwe invoer wordt de sessie omgeschakeld. Als meerdere aanroepen elkaar overlappen, wint de laatste. identify is de enige methode die bij runtimefouten een foutmelding geeft (IDENTIFY_FAILED), en die een lokale wachttijd afdwingt na HTTP 429-reacties (met inachtneming van Retry-After, begrensd op minimaal 1 seconde en maximaal 1 uur, met een standaardwaarde van 60 seconden).
uj.logout()
Wist de huidige identiteit en zet de sessie terug naar anoniem.
await uj.logout();uj.open(target?)
Opent de widget. Zonder argument wordt de widget geopend op de plek waar de gebruiker is gebleven. Wordt voltooid zodra de widget zichtbaar is.
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' });Het doel van help mag maximaal één van article, collection of query bevatten. article en collection accepteren de URL-slug; oude slugs verwijzen door naar de verplaatste pagina. De promise wordt afgewezen met INVALID_NAVIGATION bij onbekende doelen of ongeldige combinaties.
uj.close()
Verbergt de widget. Dit gebeurt synchroon en je kunt dit op elk moment veilig aanroepen.
uj.toggle()
Opent de widget als deze gesloten is en sluit deze als hij geopend is.
uj.createEmbed(options?)
Geeft een UserJot-pagina weer in een container op je pagina. Retourneert een controller. Zie Pagina's inline insluiten.
const embed = uj.createEmbed({
container: '[data-userjot-embed]',
path: '/',
basePath: '/feedback',
theme: 'auto',
onReady: () => {},
onError: (error) => {}
});
embed.navigate('/roadmap');
embed.destroy();uj.setLocale(locale)
Wijzigt de widgettaal tijdens runtime:
await uj.setLocale('pt-BR');uj.setTheme(theme)
Wijzigt het widgetthema synchroon ('auto', 'light' of 'dark'). Ongeldige waarden geven INVALID_OPTIONS door via de gebeurtenis error. Omdat init altijd zijn eigen thema toepast (standaard 'auto'), moet je je beginthema opgeven in init in plaats van setTheme aan te roepen vóór init.
uj.getState()
Retourneert een alleen-lezen momentopname van de SDK-status:
{
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)
Abonneert zich op een gebeurtenis en retourneert een functie om het abonnement op te zeggen. Luisteraars blijven bestaan na destroy().
Gebeurtenis | Payload | Wanneer deze wordt geactiveerd |
|---|---|---|
| status | Laden voltooid. Wordt onmiddellijk opnieuw afgespeeld als het laden al is voltooid. |
| status | Bij elke statuswijziging. |
| status | De widget werd zichtbaar. |
| status | De widget werd verborgen. |
|
| De identiteit is gewijzigd, ook bij uitloggen. |
|
| Het aantal ongelezen items is gewijzigd. Wordt onmiddellijk opnieuw afgespeeld als de SDK al gereed is en de gegevens zijn opgehaald. |
|
| De beschikbaarheid van het team is gewijzigd tussen |
| fout | Bij elke SDK-fout. |
| status | De SDK is vernietigd. |
Als je je abonneert op unread of presence, blijven beide waarden op de achtergrond actueel, ook wanneer de standaardlauncher verborgen is.
uj.destroy(options?)
Verwijdert de widget, alle embeds en de sessie van de pagina:
uj.destroy();
uj.destroy({ clearConversationData: true });clearConversationData wist ook lokale toestemmingen voor anonieme gesprekken, concepten en onthouden contactgegevens (handig op gedeelde apparaten).
DOM-attributen voor het vastleggen van schermafbeeldingen
Wanneer een gebruiker vanuit de feedbackeditor van de widget een schermafbeelding van de pagina maakt (terugvaloptie voor DOM-vastlegging), verbergt UserJot automatisch widgetonderdelen en maskeert het input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] en input[name*="secret" i]. Je kunt het vastleggen ook voor specifieke elementen beheren met HTML-attributen:
Attribuut | Effect bij het vastleggen van een schermafbeelding van de pagina |
|---|---|
| Laat het element volledig weg uit de vastgelegde schermafbeelding. |
| Maakt de zichtbare inhoud van het element onleesbaar in de vastgelegde schermafbeelding. |
| Maskeert gevoelige |
Fouten
Fouten hebben de vorm { code, message, recoverable, cause? }.
Code | Betekenis |
|---|---|
|
|
|
|
|
|
| In de invoer van |
| De server heeft de identify-aanroep afgewezen (bijvoorbeeld vanwege een ongeldig token, een ontbrekende handtekening in de strikte modus, een conflict met |
| De SDK kon niet worden geladen. Controleer de project-ID, CSP-regels en netwerkverbinding. |
| Er is een aanroep uitgevoerd terwijl de SDK zich in een foutstatus bevond. |
|
|
| Berichten zijn uitgeschakeld voor deze workspace. De widget opent in plaats daarvan Home. |
| Het Help Center is niet actief voor deze workspace. De widget opent in plaats daarvan Home. |
| Het element |
| De gebruikersinterface van de widget kon niet worden geladen. |
| De embedcontainer bestaat niet. |
| Er is een aanroep uitgevoerd nadat |
| Al het overige. |