Sterowanie widżetem

Shayan TaslimZaktualizowano

Możesz sterować widżetem programowo z poziomu własnego interfejsu: otwierać określone sekcje, reagować na zdarzenia, konfigurować powiadomienia o aktualizacjach lub całkowicie zastąpić domyślny przycisk uruchamiający.

Otwieranie widżetu

Wywołanie uj.open() bez argumentów otwiera widżet w miejscu, w którym użytkownik go zamknął:

JavaScript
uj.open();

Przekaż cel, aby otworzyć określoną sekcję:

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

Opcje precyzyjnego linkowania do określonych celów:

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

W dowolnym momencie możesz ukryć widżet lub przełączać jego widoczność:

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

Cel messages wymaga włączonej funkcji Conversations. W przeciwnym razie zdarzenie error zgłosi CONVERSATIONS_DISABLED, a widżet otworzy stronę główną. Cel help wymaga aktywnego Centrum pomocy (parametry article i collection przyjmują slug URL). W przeciwnym razie zostanie zgłoszone HELP_DISABLED, a widżet otworzy stronę główną.

Nasłuchiwanie zdarzeń

Subskrybuj zdarzenia za pomocą uj.on(event, listener), które zwraca funkcję anulującą subskrypcję:

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

unsubscribe();

Zdarzenie

Kiedy jest wywoływane

ready

SDK zakończył ładowanie. Jeśli jest już załadowany, zdarzenie jest wywoływane natychmiast.

open

Widżet stał się widoczny.

close

Widżet został ukryty.

identify

Tożsamość uległa zmianie, również w przypadku wylogowania.

unread

Liczba nieprzeczytanych elementów uległa zmianie. Dane zdarzenia: { count }. Jeśli widżet jest już gotowy, zdarzenie zostanie wyemitowane ponownie natychmiast.

presence

Dostępność zespołu uległa zmianie. Dane zdarzenia: { availability: 'online' | 'neutral' }. Jeśli widżet jest już gotowy, zdarzenie zostanie wyemitowane ponownie natychmiast.

statechange

Dowolna część stanu widżetu uległa zmianie.

error

Wystąpił błąd. Dane zdarzenia to obiekt błędu.

Odczytywanie stanu

uj.getState() zwraca migawkę bieżącego stanu widżetu:

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

Tworzenie własnego przycisku uruchamiającego

Ukryj domyślny przycisk uruchamiający, aby sterować widżetem za pomocą własnego elementu nawigacyjnego lub przycisku:

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

Ukrycie przycisku uruchamiającego usuwa domyślny przycisk, ale pozostawia aktywne powiadomienia wyświetlane w rogu (poniżej, w sekcji „Powiadomienia”, znajdziesz informacje o ich przesuwaniu lub wyłączaniu).

Skonfiguruj przycisk, plakietkę z liczbą nieprzeczytanych elementów i opcjonalny wskaźnik dostępności zespołu:

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' oznacza, że SDK nie może potwierdzić, czy operator jest obecnie dostępny, dlatego należy ukryć wskaźnik zamiast wyświetlać etykietę „Niedostępny”. Gdy widżet jest zamknięty, status obecności jest odświeżany przy ładowaniu strony, aktywowaniu karty i co kilka minut. Gdy widżet jest otwarty, aktualizuje się na bieżąco.

W domyślnym launcherze wskaźnik nieprzeczytanych elementów ma pierwszeństwo przed zieloną kropką oznaczającą status online. Liczba nieprzeczytanych obejmuje odpowiedzi w rozmowach, wpisy w dzienniku zmian i powiadomienia o opiniach. Kliknięcie domyślnego launchera, gdy są nieprzeczytane elementy, przekierowuje w następującej kolejności: Wiadomości (nieprzeczytane odpowiedzi w rozmowach), następnie Powiadomienia (nieprzeczytane powiadomienia o opiniach), a na końcu najnowsza nieprzeczytana Aktualizacja.

Aby bezpośrednio powiązać domyślne działanie przycisku uruchamiającego z istniejącym elementem na stronie, przekaż selektor CSS:

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

Whispers

Szepty to krótkie, klikalne powiadomienia wyświetlane w rogu, informujące o nieprzeczytanych odpowiedziach w rozmowach zespołowych, powiadomieniach o opiniach i nowych wpisach w dzienniku zmian. Są wyświetlane w tej kolejności: najpierw nieprzeczytane odpowiedzi w rozmowach, następnie powiadomienia o komentarzach lub odpowiedziach do opinii, potem pozostałe powiadomienia, a na końcu aktualizacje dziennika zmian. Ze względu na prywatność szepty dotyczące rozmów pokazują tylko awatar współpracownika i <Name> replied (nigdy treść wiadomości), a kliknięcie otwiera Wiadomości.

  • Świeżość i czas wyświetlania: Szeptem oznaczane są tylko elementy utworzone lub opublikowane w ciągu ostatnich 14 dni. Widget czeka na rzeczywistą aktywność użytkownika, 4 sekundy na stronie, 1,2 sekundy bezczynności i co najmniej 30 sekund od poprzedniego szeptu. Szepty nie przerywają pracy, gdy użytkownik pisze w polu tekstowym, polu wielowierszowym, polu wyboru lub polu edytowalnym, ani w przeglądarkach działających automatycznie.

  • Limity powtórzeń i odstępy: Każdy element jest wyświetlany szeptem maksymalnie 3 razy (za wyświetlony uznaje się go po co najmniej 1,5 sekundy widoczności, na którą użytkownik zwraca uwagę). Odstępy między wyświetleniami wynoszą 30 minut, 24 godziny i 3 dni w przypadku aktualizacji oraz 30 minut, 1 godzina i 24 godziny w przypadku powiadomień i odpowiedzi w rozmowach.

  • Z domyślnym launcherem lub bez niego: Szepty działają niezależnie od launchera. Przy domyślnym launcherze rozwijają się z przycisku; przy użyciu launcher: false lub launchera selektorowego pojawiają się samodzielnie w rogu, a po upływie czasu zwijają się do klikalnego kółka, które pozostaje widoczne przez 60 sekund, zanim zniknie.

Za pomocą offset możesz przesunąć powiadomienia tak, aby nie zasłaniały Twojego interfejsu:

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

Możesz też całkowicie wyłączyć szepty (dotyczące rozmów, opinii i domyślnych aktualizacji):

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

Jeśli obie opcje są wyłączone i nie określono trybu aktualizacji, widżet niczego nie wyświetla, dopóki nie wywołasz uj.open(). Subskrypcje unread i presence nadal aktualizują się w tle.

Powiadomienia o aktualizacjach

Za pomocą widget.notifications.updates możesz określić, jak widżet informuje o najnowszym niewidzianym wpisie w dzienniku zmian:

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

Tryb

Działanie

'whisper'

Informuje o aktualizacji za pomocą powiadomienia w rogu, z ograniczeniem liczby ponownych wyświetleń.

'full'

Otwiera aktualizację bezpośrednio w czytniku widżetu, wraz z obrazem okładkowym i pełną treścią.

'none'

Nie wyświetla powiadomień o aktualizacjach, ale pozostawia aktywną kartę Aktualizacje i plakietkę z liczbą nieprzeczytanych elementów.

Jeśli pominięto tę opcję, aktualizacje domyślnie używają 'whisper' (lub 'none', gdy whispers: false). Jawne ustawienie widget.notifications.updates zastępuje whispers wyłącznie w przypadku aktualizacji dziennika zmian; szepty dotyczące rozmów i opinii nadal korzystają z whispers.

Tryb pełny działa nawet wtedy, gdy przycisk uruchamiający jest ukryty i nie ma nasłuchiwaczy zdarzeń. Podczas pierwszej wizyty tryb pełny może otworzyć najnowszą opublikowaną aktualizację, nawet jeśli jest starsza. SDK podejmuje próbę automatycznego otwarcia najwyżej raz podczas jednej wizyty inicjalizacyjnej (ręczne otwarcie, przełączenie widoczności, zamknięcie lub nieudana próba wykorzystują ten limit; ponowne załadowanie strony lub wywołanie init() rozpoczyna nową wizytę, natomiast zmiana tożsamości użytkownika i nawigacja w SPA — nie). Automatyczne otwarcie wymaga widocznej, aktywnej karty i zamkniętego widżetu. Jest wyłączone, gdy widget: false.

Aktualizacja zostaje oznaczona jako przeczytana, gdy jej treść zostanie wyświetlona w otwartym widżecie na widocznej, aktywnej karcie. Stan przeczytania jest zapisywany lokalnie w pamięci przeglądarki osobno dla każdego projektu i źródła. Aktualizacje są wyszukiwane podczas inicjalizacji, po aktywowaniu karty i mniej więcej co pięć minut, gdy widżet jest zamknięty.

Zmiana języka

Jeśli pominięto locale, widżet wybiera język w następującej kolejności:

  1. Jawna opcja locale przekazana do uj.init(...) lub uj.setLocale(...).

  2. Język przeglądarki odwiedzającego, jeśli jest dostępny wśród języków włączonych w obszarze roboczym w Ustawieniach → Języki.

  3. Domyślny język obszaru roboczego.

Widżet obsługuje wszystkie 14 języków UserJot (zobacz Języki). Możesz zmienić język podczas inicjalizacji lub w trakcie działania, bez ponownego ładowania strony:

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

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

Czy ten artykuł odpowiedział na Twoje pytanie?