Das Widget steuern
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:
uj.open();Übergeben Sie ein Ziel, um einen bestimmten Bereich zu öffnen:
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:
// 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:
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:
const unsubscribe = uj.on('open', () => {
console.log('widget opened');
});
unsubscribe();Event | Wann es ausgelöst wird |
|---|---|
| Das Laden des SDK ist abgeschlossen. Wird sofort ausgelöst, wenn es bereits geladen ist. |
| Das Widget wurde sichtbar. |
| Das Widget wurde ausgeblendet. |
| Die Identität hat sich geändert, auch beim Abmelden. |
| Die Anzahl ungelesener Elemente hat sich geändert. Die Nutzdaten sind |
| Die Teamverfügbarkeit hat sich geändert. Die Nutzdaten sind |
| Ein beliebiger Teil des Widget-Status hat sich geändert. |
| Ein Fehler ist aufgetreten. Die Nutzdaten enthalten das Fehlerobjekt. |
Status auslesen
uj.getState() gibt eine Momentaufnahme des aktuellen Widget-Status zurück:
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 nullEigenen Launcher erstellen
Blenden Sie den Standard-Launcher aus, um das Widget über einen eigenen Navigationseintrag oder Button zu steuern:
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:
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:
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: falseoder 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:
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):
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:
uj.init('YOUR_PROJECT_ID', {
widget: {
notifications: { updates: 'full' }
}
});Modus | Verhalten |
|---|---|
| Kündigt das Update mit einer Benachrichtigung in der Ecke an, wobei die Anzahl der Wiederholungen begrenzt ist. |
| Öffnet das Update direkt im Widget-Reader mit Titelbild und vollständigem Inhalt. |
| 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:
Eine explizite Option
locale, die anuj.init(...)oderuj.setLocale(...)übergeben wird.Die Browsersprache des Besuchers, sofern sie einer der für Ihren Workspace unter Einstellungen → Sprachen aktivierten Sprachen entspricht.
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:
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });
// Change later at runtime
await uj.setLocale('pt-BR');