De widget bedienen

Shayan TaslimBijgewerkt:

Je kunt de widget programmatisch vanuit je eigen interface bedienen: open specifieke secties, reageer op gebeurtenissen, configureer updateaankondigingen of vervang de standaardlauncher volledig.

De widget openen

Als je uj.open() zonder argumenten aanroept, wordt de widget geopend op de plek waar de gebruiker is gebleven:

JavaScript
uj.open();

Geef een doel op om een specifieke sectie te openen:

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

Opties voor deep links naar specifieke doelen:

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

Verberg of schakel de widget op elk gewenst moment in of uit:

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

Voor het doel messages moet Conversations zijn ingeschakeld; anders wordt via de gebeurtenis error CONVERSATIONS_DISABLED gemeld en wordt Home geopend. Voor het doel help moet je Help Center live zijn (article en collection gebruiken de URL-slug); anders wordt HELP_DISABLED gemeld en wordt Home geopend.

Luisteren naar events

Abonneer je met uj.on(event, listener), dat een functie retourneert waarmee je het abonnement kunt opzeggen:

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

unsubscribe();

Event

Wanneer dit event wordt geactiveerd

ready

De SDK is klaar met laden. Wordt onmiddellijk geactiveerd als de SDK al is geladen.

open

De widget is zichtbaar geworden.

close

De widget is verborgen.

identify

De identiteit is gewijzigd, ook bij uitloggen.

unread

Het aantal ongelezen items is gewijzigd. De payload is { count }. Wordt meteen opnieuw afgespeeld als de widget al gereed is.

presence

De beschikbaarheid van het team is gewijzigd. De payload is { availability: 'online' | 'neutral' }. Wordt meteen opnieuw afgespeeld als de widget al gereed is.

statechange

Een onderdeel van de widgetstatus is gewijzigd.

error

Er is iets misgegaan. De payload is het foutobject.

De status uitlezen

uj.getState() retourneert een momentopname van de huidige widgetstatus:

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

Je eigen launcher maken

Verberg de standaardlauncher om de widget te bedienen vanuit je eigen navigatie-item of knop:

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

Als je de launcher verbergt, verdwijnt de standaardknop, maar blijven de meldingen in de hoek actief (zie Whispers hieronder om ze te verplaatsen of uit te schakelen).

Koppel je knop, badge voor ongelezen items en eventuele indicator voor teambeschikbaarheid:

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' betekent dat de SDK niet kan bevestigen dat er momenteel een medewerker online is. Verberg de indicator daarom in plaats van een label voor offline weer te geven. Als de widget gesloten is, wordt de aanwezigheid vernieuwd bij het laden van de pagina, wanneer het tabblad focus krijgt en om de paar minuten; als de widget geopend is, wordt de status live bijgewerkt.

In de standaardlauncher heeft de ongelezen-indicator voorrang op de groene stip voor online status. Het aantal ongelezen items omvat antwoorden in gesprekken, changelogberichten en feedbackmeldingen. Als er ongelezen items zijn en je op de standaardlauncher klikt, word je in deze volgorde doorgestuurd: eerst naar Berichten (ongelezen antwoorden in gesprekken), dan naar Meldingen (ongeziene feedbackmeldingen) en vervolgens naar de nieuwste ongeziene Update.

Je kunt het standaardgedrag van de launcher rechtstreeks aan een bestaand element op je pagina koppelen door een CSS-selector op te geven:

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

Whispers

Whispers zijn korte, aanklikbare meldingen in de hoek van het scherm die ongelezen antwoorden in teamgesprekken, feedbackmeldingen en nieuwe changelogberichten aankondigen. De prioriteitsvolgorde is: eerst ongelezen antwoorden in gesprekken, dan meldingen over feedbackreacties en -antwoorden, vervolgens andere meldingen en tot slot changelogupdates. Om privacyredenen tonen whispers in gesprekken alleen de avatar van de teamgenoot en <Name> replied (nooit de berichttekst). Als je erop klikt, wordt Berichten geopend.

  • Actualiteit en timing: Alleen items die in de afgelopen 14 dagen zijn gemaakt of gepubliceerd, worden als whisper getoond. De widget wacht tot er echte gebruikersactiviteit is, je 4 seconden op de pagina bent, het 1,2 seconden stil is en er minstens 30 seconden zijn verstreken sinds de vorige whisper. Whispers onderbreken nooit wanneer een gebruiker typt in een invoerveld, tekstvak, selectievak of bewerkbaar veld, en verschijnen ook niet in geautomatiseerde browsers.

  • Herhalingslimieten en wachttijden: Elk item wordt maximaal 3 keer bezorgd als whisper (waarbij het item 1,5 seconde zichtbaar moet zijn terwijl de gebruiker aandachtig kijkt om als bezorgd te tellen). Daarna neemt de wachttijd toe: voor updates 30 minuten, 24 uur en 3 dagen, en voor meldingen en antwoorden in gesprekken 30 minuten, 1 uur en 24 uur.

  • Met of zonder de standaardlauncher: Whispers werken onafhankelijk van de launcher. Met de standaardlauncher verschijnen ze vanuit de knop; met launcher: false of een selectorlauncher verschijnen ze zelfstandig in de hoek. Na het verlopen van de time-out worden ze 60 seconden ingeklapt tot een aanklikbare cirkel, waarna ze verdwijnen.

Verplaats whispers zodat ze niet over je eigen interface vallen met offset:

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

Je kunt whispers ook volledig uitschakelen (waardoor whispers voor gesprekken, feedback en standaardupdates worden onderdrukt):

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

Als beide zijn uitgeschakeld en er geen expliciete updatemodus is ingesteld, wordt er niets weergegeven door de widget totdat je uj.open() aanroept. Abonnementen op unread en presence blijven op de achtergrond bijgewerkt worden.

Updatemeldingen

Bepaal met widget.notifications.updates hoe de widget het nieuwste ongeziene changelogitem aankondigt:

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

Modus

Gedrag

'whisper'

Kondigt de update aan met een melding in de hoek, met een limiet voor herhalingen.

'full'

Opent de update rechtstreeks in de widgetlezer, met de omslagafbeelding en de volledige inhoud.

'none'

Onderdrukt updateaankondigingen, maar houdt het tabblad Updates en de badge voor ongelezen items actief.

Als dit niet is opgegeven, zijn updates standaard ingesteld op 'whisper' (of op 'none' wanneer whispers: false). Als je widget.notifications.updates expliciet instelt, heeft dit alleen voorrang op whispers voor changelogupdates; whispers voor gesprekken en feedback volgen nog steeds whispers.

De volledige modus werkt ook als de launcher verborgen is en er geen gebeurtenislisteners zijn. Tijdens een eerste bezoek kan de volledige modus de nieuwste gepubliceerde update openen, ook als die ouder is. De SDK probeert per initialisatiebezoek maximaal één keer automatisch iets te openen (een handmatige opening, schakelactie, sluiting of mislukte poging verbruikt die mogelijkheid; opnieuw laden of init() aanroepen begint een nieuw bezoek, maar wijzigingen van de identiteit of SPA-navigatie niet). Automatisch openen vereist een zichtbare pagina met focus en een gesloten widget, en is uitgeschakeld wanneer widget: false.

Een update wordt als gezien gemarkeerd zodra de inhoud ervan wordt geladen in de getoonde widget op een zichtbare pagina met focus. De status ‘gezien’ wordt lokaal opgeslagen in de browseropslag, per project en oorsprong. Updates worden gevonden bij initialisatie, wanneer het tabblad focus krijgt en ongeveer elke vijf minuten zolang de widget gesloten is.

De taal wijzigen

Als locale wordt weggelaten, kiest de widget een taal in deze volgorde:

  1. Een expliciete optie locale die wordt doorgegeven aan uj.init(...) of uj.setLocale(...).

  2. De browsertaal van de bezoeker, als die overeenkomt met een van de talen die zijn ingeschakeld voor je werkruimte in Instellingen → Talen.

  3. De standaardtaal van je werkruimte.

De widget ondersteunt alle 14 talen van UserJot (zie Talen). Stel de taal in bij initialisatie of tijdens runtime, zonder opnieuw te laden:

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

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

Heeft dit je vraag beantwoord?