Das Widget steuern

Shayan TaslimAktualisiert

Sie können das Widget programmgesteuert über Ihre eigene Benutzeroberfläche steuern: bestimmte Bereiche öffnen, auf Ereignisse reagieren, Update-Ankündigungen konfigurieren oder den Standard-Launcher vollständig ersetzen.

Das Widget öffnen

Wenn Sie uj.open() ohne Argumente aufrufen, wird das Widget dort geöffnet, wo der Benutzer es zuletzt verlassen hat:

JavaScript
uj.open();

Übergeben Sie ein Ziel, um einen bestimmten Bereich zu öffnen:

JavaScript
uj.open({ to: 'home' });
uj.open({ to: 'feedback' });
uj.open({ to: 'roadmap' });
uj.open({ to: 'updates' });
uj.open({ to: 'messages' });
uj.open({ to: 'notifications' });
uj.open({ to: 'help' });

Deep-Link-Optionen für bestimmte Ziele:

JavaScript
// Open the feedback submission form directly
uj.open({ to: 'feedback', compose: true });

// Open a specific feedback post
uj.open({ to: 'feedback', submissionId: 'POST_ID' });

// Open a specific changelog update
uj.open({ to: 'updates', updateId: 'UPDATE_ID' });

// Start a message with prefilled text
uj.open({ to: 'messages', compose: { text: 'I need help with...' } });

// Open a help article, collection, or search results
uj.open({ to: 'help', article: 'reset-password' });
uj.open({ to: 'help', collection: 'billing' });
uj.open({ to: 'help', query: 'invoices' });

Blenden Sie das Widget jederzeit aus oder schalten Sie es um:

JavaScript
uj.close();
uj.toggle();

Für das Ziel messages muss Conversations aktiviert sein. Andernfalls wird über das Ereignis error CONVERSATIONS_DISABLED gemeldet und Home geöffnet. Für das Ziel help muss Ihr Help Center live sein (article und collection verwenden den URL-Slug). Andernfalls wird HELP_DISABLED gemeldet und Home geöffnet.

Events abonnieren

Abonnieren Sie mit uj.on(event, listener). Die Funktion gibt eine Abmeldefunktion zurück:

JavaScript
const unsubscribe = uj.on('open', () => {
  console.log('widget opened');
});

unsubscribe();

Event

Wann es ausgelöst wird

ready

Das Laden des SDK ist abgeschlossen. Wird sofort ausgelöst, wenn es bereits geladen ist.

open

Das Widget wurde sichtbar.

close

Das Widget wurde ausgeblendet.

identify

Die Identität hat sich geändert, auch beim Abmelden.

unread

Die Anzahl ungelesener Elemente hat sich geändert. Die Nutzdaten sind { count }. Wird sofort erneut ausgelöst, wenn das Widget bereits bereit ist.

presence

Die Teamverfügbarkeit hat sich geändert. Die Nutzdaten sind { availability: 'online' | 'neutral' }. Wird sofort erneut ausgelöst, wenn das Widget bereits bereit ist.

statechange

Ein beliebiger Teil des Widget-Status hat sich geändert.

error

Ein Fehler ist aufgetreten. Die Nutzdaten enthalten das Fehlerobjekt.

Status auslesen

uj.getState() gibt eine Momentaufnahme des aktuellen Widget-Status zurück:

JavaScript
const state = uj.getState();

state.status;          // 'ready' once the SDK is loaded
state.widget.open;     // whether the widget is visible
state.unreadCount;     // number, or null before the first fetch
state.presence;        // 'online' or 'neutral'
state.session.status;  // 'anonymous', 'identifying', or 'identified'
state.session.viewer;  // the identified user, or null

Eigenen Launcher erstellen

Blenden Sie den Standard-Launcher aus, um das Widget über einen eigenen Navigationseintrag oder Button zu steuern:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false }
});

Wenn Sie den Launcher ausblenden, wird der Standard-Button entfernt. Benachrichtigungs-Whispers bleiben jedoch in der Ecke aktiv (unter „Whispers“ weiter unten erfahren Sie, wie Sie sie verschieben oder deaktivieren).

Verbinden Sie Ihren Button, das Badge für ungelesene Elemente und optional eine Anzeige der Teamverfügbarkeit:

JavaScript
const button = document.querySelector('#feedback-button');
const badge = document.querySelector('#feedback-badge');
const dot = document.querySelector('#feedback-online-dot');

button.addEventListener('click', () => uj.toggle());

uj.on('unread', ({ count }) => {
  badge.textContent = count > 0 ? String(count) : '';
});

uj.on('presence', ({ availability }) => {
  dot.hidden = availability !== 'online';
});

'neutral' bedeutet, dass das SDK nicht bestätigen kann, ob gerade ein Mitarbeiter online ist. Blenden Sie die Anzeige daher aus, anstatt eine Meldung wie „offline“ anzuzeigen. Wenn das Widget geschlossen ist, wird die Verfügbarkeit beim Laden der Seite, beim Fokussieren des Tabs und alle paar Minuten aktualisiert. Wenn es geöffnet ist, wird sie in Echtzeit aktualisiert.

Beim Standard-Launcher hat die Anzeige ungelesener Inhalte Vorrang vor dem grünen Online-Punkt. Die Anzahl ungelesener Inhalte umfasst Antworten in Unterhaltungen, Changelog-Beiträge und Feedback-Benachrichtigungen. Wenn ungelesene Inhalte vorliegen und jemand auf den Standard-Launcher klickt, wird je nach Priorität Folgendes geöffnet: Nachrichten (ungelesene Antworten in Unterhaltungen), dann Benachrichtigungen (ungesehene Feedback-Benachrichtigungen) und schließlich das neueste ungesehene Update.

Um das Verhalten des Standard-Launchers direkt mit einem vorhandenen Element auf Ihrer Seite zu verknüpfen, übergeben Sie einen CSS-Selektor:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: { selector: '#feedback-button' } }
});

Whispers

Whispers sind kurze, anklickbare Benachrichtigungen in der Bildschirmecke, die auf ungelesene Antworten in Team-Unterhaltungen, Feedback-Benachrichtigungen und neue Changelog-Beiträge hinweisen. Die Priorität ist wie folgt: zuerst ungelesene Antworten in Unterhaltungen, dann Benachrichtigungen zu Feedback-Kommentaren und -Antworten, anschließend andere Benachrichtigungen und zuletzt Changelog-Updates. Zum Schutz der Privatsphäre zeigen Unterhaltungs-Whispers nur den Avatar des Teammitglieds und <Name> replied (niemals den Nachrichtentext). Ein Klick darauf öffnet Nachrichten.

  • Aktualität und Zeitsteuerung: Whispers werden nur für Inhalte angezeigt, die innerhalb der letzten 14 Tage erstellt oder veröffentlicht wurden. Das Widget wartet auf tatsächliche Nutzeraktivität, 4 Sekunden auf der Seite, 1,2 Sekunden ohne Aktivität und mindestens 30 Sekunden seit dem vorherigen Whisper. Whispers werden niemals angezeigt, während jemand in einem Eingabefeld, Textbereich, Auswahlfeld oder bearbeitbaren Feld tippt oder sich in einem automatisierten Browser befindet.

  • Wiederholungslimits und Wartezeiten: Für jeden Inhalt wird ein Whisper höchstens 3 Mal zugestellt (er muss dabei 1,5 Sekunden lang aufmerksam sichtbar sein, um als zugestellt zu gelten). Die Wartezeit wird dabei auf 30 Minuten, 24 Stunden und 3 Tage für Updates erhöht, beziehungsweise auf 30 Minuten, 1 Stunde und 24 Stunden für Benachrichtigungen und Antworten in Unterhaltungen.

  • Mit oder ohne Standard-Launcher: Whispers funktionieren unabhängig vom Launcher. Beim Standard-Launcher werden sie aus der Schaltfläche heraus eingeblendet. Mit launcher: false oder einem Launcher mit Selektor erscheinen sie eigenständig in der Ecke und werden nach Ablauf der Anzeigezeit zu einem anklickbaren, eingeklappten Kreis. Dieser bleibt 60 Sekunden sichtbar, bevor er ausgeblendet wird.

Verschieben Sie Whispers mit offset, damit sie Ihre eigene Benutzeroberfläche nicht überdecken:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    launcher: false,
    offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
  }
});

Oder deaktivieren Sie Whispers vollständig (damit werden Whispers zu Unterhaltungen, Feedback und standardmäßigen Updates unterdrückt):

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false, whispers: false }
});

Wenn beide Optionen deaktiviert sind und kein Update-Modus explizit festgelegt wurde, wird nichts angezeigt, bis Sie uj.open() aufrufen. Die Abonnements für unread und presence werden im Hintergrund weiter aktualisiert.

Update-Ankündigungen

Legen Sie mit widget.notifications.updates fest, wie das Widget den neuesten noch nicht gesehenen Eintrag im Änderungsprotokoll ankündigt:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    notifications: { updates: 'full' }
  }
});

Modus

Verhalten

'whisper'

Kündigt das Update mit einer Benachrichtigung in der Ecke an, wobei die Anzahl der Wiederholungen begrenzt ist.

'full'

Öffnet das Update direkt im Widget-Reader mit Titelbild und vollständigem Inhalt.

'none'

Unterdrückt Update-Ankündigungen, während der Updates-Tab und das Badge für ungelesene Elemente aktiv bleiben.

Wenn nicht angegeben, werden Updates standardmäßig auf 'whisper' gesetzt (oder auf 'none', wenn whispers: false). Wenn widget.notifications.updates ausdrücklich festgelegt ist, überschreibt dies whispers nur für Changelog-Updates. Whispers zu Unterhaltungen und Feedback richten sich weiterhin nach whispers.

Der vollständige Modus funktioniert auch mit ausgeblendetem Launcher und ohne Ereignis-Listener. Beim ersten Besuch kann der vollständige Modus auch ein älteres, zuletzt veröffentlichtes Update öffnen. Das SDK versucht pro Initialisierungsbesuch höchstens ein automatisches Öffnen (ein manuelles Öffnen, Umschalten, Schließen oder ein fehlgeschlagener Versuch verbraucht diese Möglichkeit; durch Neuladen oder Aufrufen von init() wird ein neuer Besuch gestartet, durch Identitätsänderungen oder SPA-Navigation hingegen nicht). Das automatische Öffnen setzt eine sichtbare, fokussierte Seite und ein geschlossenes Widget voraus und ist deaktiviert, wenn widget: false.

Ein Update gilt als gesehen, sobald sein Inhalt im angezeigten Widget auf einer sichtbaren, fokussierten Seite geladen wurde. Der Status „gesehen“ wird lokal im Browserspeicher pro Projekt und Origin gespeichert. Updates werden bei der Initialisierung, beim Fokussieren des Tabs und etwa alle fünf Minuten erkannt, solange das Widget geschlossen ist.

Sprache ändern

Wenn locale nicht angegeben ist, wählt das Widget die Sprache in dieser Reihenfolge:

  1. Eine explizite Option locale, die an uj.init(...) oder uj.setLocale(...) übergeben wird.

  2. Die Browsersprache des Besuchers, sofern sie einer der für Ihren Workspace unter Einstellungen → Sprachen aktivierten Sprachen entspricht.

  3. Die Standardsprache Ihres Workspace.

Das Widget unterstützt alle 14 Sprachen von UserJot (siehe Sprachen). Sie können die Sprache bei der Initialisierung oder zur Laufzeit ändern, ohne die Seite neu zu laden:

JavaScript
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });

// Change later at runtime
await uj.setLocale('pt-BR');

Hat das Ihre Frage beantwortet?