SDK-Referenz
Das SDK wird als window.uj bereitgestellt. Fire-and-forget-Aufrufe über den Inline-Preload-Proxy (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) werden in die Warteschlange gestellt und wiedergegeben, sobald uj.js geladen ist. Aufrufe, die Werte oder Promises zurückgeben (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version), setzen voraus, dass das SDK-Skript bereits geladen wurde.
uj.version
Die Versionszeichenfolge des SDK, zum Beispiel 1.0.0.
uj.init(projectId, options?)
Initialisiert das SDK. Gibt ein Promise zurück, das aufgelöst wird, sobald der Ladevorgang abgeschlossen ist, und den SDK-Status enthält.
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) => {}
});Option | Standard | Beschreibung |
|---|---|---|
|
|
|
|
|
|
|
| Kurzlebige Benachrichtigungs-Toasts in der Ecke des Widgets. Sie sind unabhängig vom Launcher und werden weiterhin angezeigt, wenn die Schaltfläche ausgeblendet ist, sofern sie nicht auf |
|
|
|
|
| Auf welcher Seite des Bildschirms das Widget geöffnet wird. |
|
| Abstand des Launchers und der Hinweise zu den Viewporträndern in Pixeln. |
|
| Systemeinstellung übernehmen oder hellen beziehungsweise dunklen Modus erzwingen. |
| Browser → Workspace-Standardeinstellung | Sprachüberschreibung. Wenn keine Sprache angegeben wird, wird die Browsersprache des Besuchers mit den für Ihren Workspace aktivierten Sprachen abgeglichen. Gibt es keine Übereinstimmung, wird die Standardsprache des Workspace verwendet. Unterstützt alle 14 UserJot-Sprachen; regionale Sprachcodes wie |
|
| Wie viel von der URL der aktuellen Seite in Unterhaltungen und bei Live visitors mit deinem Team geteilt wird. |
| Wird aufgerufen, sobald das SDK bereit ist. | |
| Wird bei jedem SDK-Fehler aufgerufen. |
Das zurückgegebene Promise wird bei Netzwerkproblemen nicht abgelehnt (prüfen Sie state.status === 'ready'). Es wird nur bei Programmierfehlern abgelehnt, etwa bei einer leeren Projekt-ID oder fehlerhaften Optionen (INVALID_OPTIONS, recoverable: false).
Der vollständige Aktualisierungsmodus funktioniert auch ohne Launcher, Hinweise oder Host-Abonnements. Unter Ankündigungen von Aktualisierungen finden Sie die genauen Regeln zur Sichtbarkeit, zum Fokus und zur Speicherung des Gelesen-Status.
uj.ready()
Gibt dasselbe Promise wie init zurück. Nützlich, wenn der Code, der das SDK benötigt, nicht bei der Initialisierung ausgeführt wird.
const state = await uj.ready();uj.identify(input)
Identifiziert den aktuellen Benutzer. Gibt ein Promise mit dem Ergebnis zurück. Siehe Benutzer identifizieren und Signierte Identität.
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 hat folgende Struktur:
{
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
}Warnungen und reservierte Trait-Schlüssel
Code |
| Bedeutung |
|---|---|---|
| Der Eigenschaftsschlüssel | Der Schlüssel ist UserJot vorbehalten und wurde verworfen. |
| Das Unternehmen | Der Workspace erfordert eine signierte Unternehmensmitgliedschaft, und dieses Unternehmen war nicht im Token enthalten. |
|
| Der Benutzer ist Workspace-Admin oder -Eigentümer. Seine Merkmale und Unternehmen werden übernommen; Name, Avatar und E-Mail werden im Dashboard verwaltet. |
Die folgenden Trait-Schlüssel sind reserviert und werden ignoriert (dabei wird RESERVED_TRAIT_KEY_IGNORED ausgegeben): 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 und __proto__.
Mindestens eines von token oder user.id ist erforderlich. Ein erneuter Aufruf von identify mit derselben Eingabe bewirkt nichts, solange die Sitzung noch aktiv ist; nach ihrem Ablauf wird bei derselben Eingabe eine neue Anfrage gesendet. Bei einer neuen Eingabe wird die Sitzung gewechselt. Überlappen sich mehrere Aufrufe, gilt der letzte. Nur identify wird bei Laufzeitfehlern (IDENTIFY_FAILED) abgelehnt und erzwingt nach HTTP-429-Antworten eine lokale Wartezeit (unter Berücksichtigung von Retry-After, begrenzt auf 1 Sekunde bis 1 Stunde, Standard: 60 Sekunden).
uj.logout()
Löscht die aktuelle Identität und setzt die Sitzung auf anonym zurück.
await uj.logout();uj.open(target?)
Öffnet das Widget. Ohne Argument wird die Ansicht geöffnet, an der der Benutzer zuletzt aufgehört hat. Wird aufgelöst, sobald das Widget sichtbar ist.
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' });Für das Ziel von help ist höchstens eines der Felder article, collection oder query zulässig. article und collection erwarten den URL-Slug; alte Slugs leiten zur verschobenen Seite weiter. Bei unbekannten Zielen oder ungültigen Kombinationen wird das Promise mit INVALID_NAVIGATION abgelehnt.
uj.close()
Blendet das Widget aus. Der Aufruf erfolgt synchron und ist jederzeit sicher.
uj.toggle()
Öffnet das Widget, wenn es geschlossen ist, und schließt es, wenn es geöffnet ist.
uj.createEmbed(options?)
Rendert eine UserJot-Seite in einem Container auf Ihrer Seite. Gibt einen Controller zurück. Siehe Seiten inline einbetten.
const embed = uj.createEmbed({
container: '[data-userjot-embed]',
path: '/',
basePath: '/feedback',
theme: 'auto',
onReady: () => {},
onError: (error) => {}
});
embed.navigate('/roadmap');
embed.destroy();uj.setLocale(locale)
Ändert die Sprache des Widgets zur Laufzeit:
await uj.setLocale('pt-BR');uj.setTheme(theme)
Ändert das Widget-Design synchron ('auto', 'light' oder 'dark'). Ungültige Werte lösen über das Ereignis error die Ausgabe von INVALID_OPTIONS aus. Da init immer ein eigenes Design anwendet (standardmäßig 'auto'), übergeben Sie das initiale Design in init, anstatt setTheme vor init aufzurufen.
uj.getState()
Gibt eine schreibgeschützte Momentaufnahme des SDK-Status zurück:
{
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)
Abonniert ein Ereignis und gibt eine Funktion zum Abbestellen zurück. Listener bleiben auch nach destroy() bestehen.
Ereignis | Nutzdaten | Auslöser |
|---|---|---|
| state | Ladevorgang abgeschlossen. Wird sofort erneut ausgelöst, wenn der Ladevorgang bereits abgeschlossen ist. |
| state | Bei jeder Zustandsänderung. |
| state | Das Widget wurde sichtbar. |
| state | Das Widget wurde ausgeblendet. |
|
| Die Identität hat sich geändert, einschließlich beim Abmelden. |
|
| Die Anzahl ungelesener Einträge hat sich geändert. Wird sofort erneut ausgelöst, wenn das Widget bereits bereit ist und die Daten abgerufen wurden. |
|
| Die Teamverfügbarkeit hat zwischen |
| error | Bei jedem SDK-Fehler. |
| state | Das SDK wurde zerstört. |
Wenn Sie unread oder presence abonnieren, bleiben beide Werte im Hintergrund aktuell, auch wenn der Standard-Launcher ausgeblendet ist.
uj.destroy(options?)
Entfernt das Widget, alle Einbettungen und die Sitzung von der Seite:
uj.destroy();
uj.destroy({ clearConversationData: true });clearConversationData löscht außerdem lokale Berechtigungen für anonyme Unterhaltungen, Entwürfe und gespeicherte Kontaktdaten (nützlich auf gemeinsam genutzten Geräten).
DOM-Attribute für die Screenshot-Erfassung
Wenn ein Nutzer über den Feedback-Editor des Widgets einen Screenshot innerhalb der Seite aufnimmt (Fallback für die DOM-Erfassung), blendet UserJot automatisch Widget-Elemente aus und maskiert input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] und input[name*="secret" i]. Mit HTML-Attributen kannst du die Erfassung auch für bestimmte Elemente steuern:
Attribut | Auswirkung bei der Screenshot-Erfassung innerhalb der Seite |
|---|---|
| Lässt das Element vollständig aus dem aufgenommenen Screenshot weg. |
| Schwärzt den sichtbaren Inhalt des Elements im aufgenommenen Screenshot. |
| Maskiert sensible |
Fehler
Fehler haben die Form { code, message, recoverable, cause? }.
Code | Bedeutung |
|---|---|
|
|
|
|
|
|
| Bei der Eingabe von |
| Der Server hat den Identify-Aufruf abgelehnt (zum Beispiel wegen eines ungültigen Tokens, einer fehlenden Signatur im strikten Modus, eines |
| Das SDK konnte nicht geladen werden. Prüfen Sie die Projekt-ID, die CSP-Regeln und die Netzwerkverbindung. |
| Ein Aufruf wurde ausgeführt, während sich das SDK in einem Fehlerzustand befand. |
|
|
| Nachrichten sind für diesen Workspace deaktiviert. Das Widget öffnet stattdessen die Startseite. |
| Das Help Center ist für diesen Workspace nicht live. Das Widget öffnet stattdessen die Startseite. |
| Das Element |
| Die Benutzeroberfläche des Widgets konnte nicht geladen werden. |
| Der Einbettungscontainer ist nicht vorhanden. |
| Ein Aufruf wurde nach |
| Alles andere. |