Dokumentacja SDK

Shayan TaslimZaktualizowano

SDK jest udostępniane jako window.uj. Wywołania typu fire-and-forget wykonywane za pośrednictwem wbudowanego proxy przed załadowaniem (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) są umieszczane w kolejce i odtwarzane po załadowaniu uj.js. Wywołania zwracające wartości lub obietnice (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) wymagają wcześniejszego załadowania skryptu SDK.

uj.version

Ciąg wersji SDK, na przykład 1.0.0.

uj.init(projectId, options?)

Inicjuje SDK. Zwraca obietnicę, która po zakończeniu ładowania rozwiązuje się bieżącym stanem SDK.

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

Opcja

Domyślnie

Opis

widget

true

true wyświetla widżet z ustawieniami domyślnymi. false go wyłącza. Obiekt pozwala go skonfigurować.

widget.launcher

true

false ukrywa domyślny przycisk. { selector } wiąże widżet z własnym elementem.

widget.whispers

true

Nietrwałe powiadomienia w formie wyskakujących komunikatów w rogu widżetu. Działają niezależnie od przycisku uruchamiającego: nadal się pojawiają, gdy przycisk jest ukryty, chyba że ustawiono false. Jawne ustawienie trybu powiadomień o aktualizacjach zastępuje to zachowanie wyłącznie w przypadku ogłoszeń o zmianach. Zobacz Sterowanie widżetem.

widget.notifications.updates

'whisper' lub 'none', gdy whispers: false

'whisper' wyświetla powiadomienia o aktualizacjach w formie toastów; 'full' otwiera najnowszy nieprzeczytany wpis w czytniku widżetu; 'none' wyłącza powiadomienia o aktualizacjach, ale pozostawia je jako nieprzeczytane. Jawnie podane wartości zastępują whispers wyłącznie w przypadku aktualizacji.

widget.position

'right'

Po której stronie ekranu otwiera się widżet.

widget.offset

{ bottom: 20, side: 20 }

Odległość w pikselach, w jakiej launcher i powiadomienia typu whisper są wyświetlane od krawędzi obszaru widoku.

widget.theme

'auto'

Dopasowanie do ustawień systemu albo wymuszenie jasnego lub ciemnego motywu.

locale

przeglądarka → domyślne ustawienie obszaru roboczego

Ustawienie języka. Jeśli nie zostanie podane, język przeglądarki odwiedzającego jest dopasowywany do języków włączonych w obszarze roboczym, a w razie braku dopasowania używany jest język domyślny obszaru roboczego. Obsługiwane są wszystkie 14 języków UserJot; tagi regionalne, takie jak es-MX, są mapowane na odpowiadający im język.

pageContext

'origin'

Określa, jaka część adresu URL bieżącej strony jest udostępniana zespołowi w rozmowach i w sekcji Live visitors. 'origin' wysyła tylko nazwę hosta, 'path' uwzględnia ścieżkę (bez parametrów zapytania i #fragments), a 'none' niczego nie wysyła.

onReady

Wywoływana, gdy SDK jest gotowe.

onError

Wywoływana w przypadku dowolnego błędu SDK.

Zwrócona obietnica nie jest odrzucana w przypadku problemów z siecią (sprawdź state.status === 'ready'). Jest odrzucana wyłącznie w przypadku błędów programistycznych, takich jak pusty identyfikator projektu lub nieprawidłowe opcje (INVALID_OPTIONS, recoverable: false).

Pełny tryb aktualizacji działa bez launchera, powiadomień typu whisper i subskrypcji hosta. Dokładne zasady wyświetlania, ustawiania fokusu i zapisywania informacji o przeczytaniu opisano w sekcji Powiadomienia o aktualizacjach.

uj.ready()

Zwraca tę samą obietnicę co init. Przydatne, gdy kod wymagający SDK znajduje się w innym miejscu niż kod inicjalizujący.

JavaScript
const state = await uj.ready();

uj.identify(input)

Identyfikuje bieżącego użytkownika. Zwraca obietnicę z wynikiem. Zobacz Identyfikowanie użytkowników i Podpisana tożsamość.

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 ma następującą 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
}

Ostrzeżenia i zarezerwowane klucze cech

Kod

field

Znaczenie

RESERVED_TRAIT_KEY_IGNORED

Klucz cechy

Klucz jest zarezerwowany przez UserJot i został pominięty.

UNSIGNED_COMPANY_IGNORED

Firma id

Obszar roboczy wymaga podpisanego członkostwa w firmie, a tej firmy nie było w tokenie.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar lub email

Użytkownik jest administratorem lub właścicielem obszaru roboczego. Jego cechy i firmy mają zastosowanie; imię i nazwisko, awatar oraz adres e-mail są zarządzane w panelu.

Następujące klucze cech są zarezerwowane i ignorowane (generują RESERVED_TRAIT_KEY_IGNORED): 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 i __proto__.

Wymagane jest podanie co najmniej jednego z token lub user.id. Ponowne wywołanie identify z tymi samymi danymi nie powoduje żadnych zmian, dopóki sesja pozostaje aktywna; po jej wygaśnięciu te same dane powodują wysłanie nowego żądania. Wywołanie z nowymi danymi przełącza sesję. Jeśli kilka wywołań nakłada się na siebie, obowiązuje ostatnie. identify to jedyna metoda, która odrzuca obietnicę w przypadku błędów czasu wykonywania (IDENTIFY_FAILED), i wymusza lokalny okres oczekiwania po odpowiedziach HTTP 429 (z uwzględnieniem Retry-After, ograniczony do zakresu od 1 sekundy do 1 godziny; domyślnie 60 sekund).

uj.logout()

Czyści bieżącą tożsamość i przywraca sesję do stanu anonimowego.

JavaScript
await uj.logout();

uj.open(target?)

Otwiera widżet. Bez argumentu otwiera go w miejscu, w którym użytkownik zakończył korzystanie. Zwraca wynik po wyświetleniu widżetu.

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

Cel help może przyjmować najwyżej jedną z wartości: article, collection lub query. Metody article i collection przyjmują slug URL, a stare slugi przekierowują do przeniesionej strony. Odrzucają obietnicę z błędem INVALID_NAVIGATION w przypadku nieznanych celów lub nieprawidłowych kombinacji.

uj.close()

Ukrywa widżet. Działa synchronicznie i można bezpiecznie wywołać tę metodę w dowolnym momencie.

uj.toggle()

Otwiera widżet, jeśli jest zamknięty, a zamyka go, jeśli jest otwarty.

uj.createEmbed(options?)

Renderuje stronę UserJot w kontenerze na Twojej stronie. Zwraca kontroler. Zobacz Osadzanie stron w treści.

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)

Zmienia język widżetu w czasie działania:

JavaScript
await uj.setLocale('pt-BR');

uj.setTheme(theme)

Zmienia synchronicznie motyw widżetu ('auto', 'light' lub 'dark'). Nieprawidłowe wartości generują INVALID_OPTIONS za pośrednictwem zdarzenia error. Ponieważ init zawsze stosuje własny motyw (domyślnie 'auto'), początkowy motyw należy przekazać w init, zamiast wywoływać setTheme przed init.

uj.getState()

Zwraca tylko do odczytu migawkę stanu SDK:

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)

Subskrybuje zdarzenie i zwraca funkcję anulującą subskrypcję. Nasłuchiwacze pozostają aktywne po wywołaniu destroy().

Zdarzenie

Dane zdarzenia

Kiedy jest wywoływane

ready

stan

Ładowanie zakończone. Jeśli zostało już zakończone, zdarzenie jest emitowane ponownie natychmiast.

statechange

stan

Każda zmiana stanu.

open

stan

Widżet stał się widoczny.

close

stan

Widżet został ukryty.

identify

{ viewer, identityTrust }

Zmiana tożsamości, w tym wylogowanie.

unread

{ count }

Zmiana liczby nieprzeczytanych. Jeśli SDK jest już gotowe i pobrało dane, zdarzenie jest emitowane ponownie natychmiast.

presence

{ availability }

Dostępność zespołu zmieniła się między wartościami 'online' i 'neutral'. Jeśli SDK jest już gotowe, zdarzenie jest emitowane ponownie natychmiast.

error

błąd

Dowolny błąd SDK.

destroy

stan

SDK został zniszczony.

Subskrybowanie unread lub presence sprawia, że obie wartości są aktualizowane w tle, nawet gdy domyślny launcher jest ukryty.

uj.destroy(options?)

Usuwa widżet, wszystkie osadzone elementy i sesję ze strony:

JavaScript
uj.destroy();
uj.destroy({ clearConversationData: true });

clearConversationData usuwa również lokalne uprawnienia do anonimowych konwersacji, wersje robocze i zapamiętane dane kontaktowe (przydatne na urządzeniach współdzielonych).

Atrybuty DOM dotyczące przechwytywania zrzutów ekranu

Gdy użytkownik wykonuje zrzut ekranu strony z poziomu formularza opinii w widżecie (awaryjne przechwytywanie DOM), UserJot automatycznie ukrywa elementy widżetu i maskuje input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] oraz input[name*="secret" i]. Możesz też kontrolować przechwytywanie dla konkretnych elementów za pomocą atrybutów HTML:

Atrybut

Działanie podczas przechwytywania zrzutu ekranu strony

data-userjot-capture-ignore

Całkowicie pomija element na przechwyconym zrzucie ekranu.

data-userjot-capture-mask

Zasłania widoczną zawartość elementu na przechwyconym zrzucie ekranu.

data-userjot-sensitive

Automatycznie maskuje wrażliwe pola <textarea>.

Błędy

Błędy mają postać { code, message, recoverable, cause? }.

Kod

Znaczenie

INVALID_PROJECT_ID

Wywołano init z pustym identyfikatorem projektu.

INVALID_OPTIONS

Metoda init, setLocale lub setTheme otrzymała nieprawidłowe opcje.

INVALID_NAVIGATION

Do open przekazano nieznany lub nieprawidłowy cel.

INVALID_IDENTIFY

W danych wejściowych identify brakuje zarówno token, jak i user.id.

IDENTIFY_FAILED

Serwer odrzucił wywołanie identify (na przykład z powodu nieprawidłowego tokenu, braku podpisu w trybie ścisłym, konfliktu 409, przekroczenia limitu żądań lub usuniętego członka).

BOOTSTRAP_FAILED

Nie udało się załadować SDK. Sprawdź identyfikator projektu, reguły CSP i połączenie sieciowe.

NOT_READY

Wywołanie nastąpiło, gdy SDK było w stanie błędu.

WIDGET_DISABLED

Wywołano open, gdy widżet jest wyłączony.

CONVERSATIONS_DISABLED

Wiadomości są wyłączone dla tego obszaru roboczego. Widżet otworzy stronę główną.

HELP_DISABLED

Centrum pomocy nie jest aktywne dla tego obszaru roboczego. Widżet otworzy stronę główną.

LAUNCHER_NOT_FOUND

Element launcher.selector nie istnieje.

SIDEBAR_LOAD_FAILED

Nie udało się załadować interfejsu widgetu.

EMBED_CONTAINER_NOT_FOUND

Kontener osadzonego elementu nie istnieje.

DESTROYED

Wywołanie nastąpiło po destroy().

UNKNOWN

Wszystko inne.

Czy ten artykuł odpowiedział na Twoje pytanie?