SDK-Referenz

Shayan TaslimAktualisiert

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.

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

Option

Standard

Beschreibung

widget

true

true zeigt das Widget mit den Standardeinstellungen an. false deaktiviert es. Mit einem Objekt lässt es sich konfigurieren.

widget.launcher

true

false blendet die Standardschaltfläche aus. { selector } bindet das Widget an ein eigenes Element.

widget.whispers

true

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 false gesetzt sind. Ein expliziter Benachrichtigungsmodus für Updates setzt dies nur für Changelog-Ankündigungen außer Kraft. Siehe Widget steuern.

widget.notifications.updates

'whisper' oder 'none', wenn whispers: false

'whisper' kündigt Aktualisierungen in einer Toast-Benachrichtigung an; 'full' öffnet den neuesten ungelesenen Eintrag im Widget-Reader; 'none' unterdrückt Aktualisierungsankündigungen, während die Einträge ungelesen bleiben. Explizite Werte überschreiben whispers ausschließlich für Aktualisierungen.

widget.position

'right'

Auf welcher Seite des Bildschirms das Widget geöffnet wird.

widget.offset

{ bottom: 20, side: 20 }

Abstand des Launchers und der Hinweise zu den Viewporträndern in Pixeln.

widget.theme

'auto'

Systemeinstellung übernehmen oder hellen beziehungsweise dunklen Modus erzwingen.

locale

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 es-MX werden der jeweiligen Sprache zugeordnet.

pageContext

'origin'

Wie viel von der URL der aktuellen Seite in Unterhaltungen und bei Live visitors mit deinem Team geteilt wird. 'origin' sendet nur den Hostnamen, 'path' enthält den Pfad (Abfrageparameter und #fragments werden entfernt), 'none' sendet nichts.

onReady

Wird aufgerufen, sobald das SDK bereit ist.

onError

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.

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

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 hat folgende Struktur:

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
}

Warnungen und reservierte Trait-Schlüssel

Code

field

Bedeutung

RESERVED_TRAIT_KEY_IGNORED

Der Eigenschaftsschlüssel

Der Schlüssel ist UserJot vorbehalten und wurde verworfen.

UNSIGNED_COMPANY_IGNORED

Das Unternehmen id

Der Workspace erfordert eine signierte Unternehmensmitgliedschaft, und dieses Unternehmen war nicht im Token enthalten.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar oder email

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.

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

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

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.

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)

Ändert die Sprache des Widgets zur Laufzeit:

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

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)

Abonniert ein Ereignis und gibt eine Funktion zum Abbestellen zurück. Listener bleiben auch nach destroy() bestehen.

Ereignis

Nutzdaten

Auslöser

ready

state

Ladevorgang abgeschlossen. Wird sofort erneut ausgelöst, wenn der Ladevorgang bereits abgeschlossen ist.

statechange

state

Bei jeder Zustandsänderung.

open

state

Das Widget wurde sichtbar.

close

state

Das Widget wurde ausgeblendet.

identify

{ viewer, identityTrust }

Die Identität hat sich geändert, einschließlich beim Abmelden.

unread

{ count }

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.

presence

{ availability }

Die Teamverfügbarkeit hat zwischen 'online' und 'neutral' gewechselt. Wird sofort erneut ausgelöst, wenn das Widget bereits bereit ist.

error

error

Bei jedem SDK-Fehler.

destroy

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:

JavaScript
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

data-userjot-capture-ignore

Lässt das Element vollständig aus dem aufgenommenen Screenshot weg.

data-userjot-capture-mask

Schwärzt den sichtbaren Inhalt des Elements im aufgenommenen Screenshot.

data-userjot-sensitive

Maskiert sensible <textarea>-Felder automatisch.

Fehler

Fehler haben die Form { code, message, recoverable, cause? }.

Code

Bedeutung

INVALID_PROJECT_ID

init wurde mit einer leeren Projekt-ID aufgerufen.

INVALID_OPTIONS

init, setLocale oder setTheme wurden ungültige Optionen übergeben.

INVALID_NAVIGATION

open hat ein unbekanntes oder ungültiges Ziel erhalten.

INVALID_IDENTIFY

Bei der Eingabe von identify fehlen sowohl token als auch user.id.

IDENTIFY_FAILED

Der Server hat den Identify-Aufruf abgelehnt (zum Beispiel wegen eines ungültigen Tokens, einer fehlenden Signatur im strikten Modus, eines 409-Konflikts, einer Ratenbegrenzung oder eines gelöschten Mitglieds).

BOOTSTRAP_FAILED

Das SDK konnte nicht geladen werden. Prüfen Sie die Projekt-ID, die CSP-Regeln und die Netzwerkverbindung.

NOT_READY

Ein Aufruf wurde ausgeführt, während sich das SDK in einem Fehlerzustand befand.

WIDGET_DISABLED

open wurde aufgerufen, während das Widget deaktiviert war.

CONVERSATIONS_DISABLED

Nachrichten sind für diesen Workspace deaktiviert. Das Widget öffnet stattdessen die Startseite.

HELP_DISABLED

Das Help Center ist für diesen Workspace nicht live. Das Widget öffnet stattdessen die Startseite.

LAUNCHER_NOT_FOUND

Das Element launcher.selector ist nicht vorhanden.

SIDEBAR_LOAD_FAILED

Die Benutzeroberfläche des Widgets konnte nicht geladen werden.

EMBED_CONTAINER_NOT_FOUND

Der Einbettungscontainer ist nicht vorhanden.

DESTROYED

Ein Aufruf wurde nach destroy() ausgeführt.

UNKNOWN

Alles andere.

Hat das Ihre Frage beantwortet?