Dokumentacja SDK
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.
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 |
|---|---|---|
|
|
|
|
|
|
|
| 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 |
|
|
|
|
| Po której stronie ekranu otwiera się widżet. |
|
| Odległość w pikselach, w jakiej launcher i powiadomienia typu whisper są wyświetlane od krawędzi obszaru widoku. |
|
| Dopasowanie do ustawień systemu albo wymuszenie jasnego lub ciemnego motywu. |
| 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 |
|
| Określa, jaka część adresu URL bieżącej strony jest udostępniana zespołowi w rozmowach i w sekcji Live visitors. |
| Wywoływana, gdy SDK jest gotowe. | |
| 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.
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ść.
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ę:
{
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 |
| Znaczenie |
|---|---|---|
| Klucz cechy | Klucz jest zarezerwowany przez UserJot i został pominięty. |
| Firma | Obszar roboczy wymaga podpisanego członkostwa w firmie, a tej firmy nie było w tokenie. |
|
| 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.
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.
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.
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:
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:
{
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 |
|---|---|---|
| stan | Ładowanie zakończone. Jeśli zostało już zakończone, zdarzenie jest emitowane ponownie natychmiast. |
| stan | Każda zmiana stanu. |
| stan | Widżet stał się widoczny. |
| stan | Widżet został ukryty. |
|
| Zmiana tożsamości, w tym wylogowanie. |
|
| Zmiana liczby nieprzeczytanych. Jeśli SDK jest już gotowe i pobrało dane, zdarzenie jest emitowane ponownie natychmiast. |
|
| Dostępność zespołu zmieniła się między wartościami |
| błąd | Dowolny błąd SDK. |
| 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:
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 |
|---|---|
| Całkowicie pomija element na przechwyconym zrzucie ekranu. |
| Zasłania widoczną zawartość elementu na przechwyconym zrzucie ekranu. |
| Automatycznie maskuje wrażliwe pola |
Błędy
Błędy mają postać { code, message, recoverable, cause? }.
Kod | Znaczenie |
|---|---|
| Wywołano |
| Metoda |
| Do |
| W danych wejściowych |
| Serwer odrzucił wywołanie identify (na przykład z powodu nieprawidłowego tokenu, braku podpisu w trybie ścisłym, konfliktu |
| Nie udało się załadować SDK. Sprawdź identyfikator projektu, reguły CSP i połączenie sieciowe. |
| Wywołanie nastąpiło, gdy SDK było w stanie błędu. |
| Wywołano |
| Wiadomości są wyłączone dla tego obszaru roboczego. Widżet otworzy stronę główną. |
| Centrum pomocy nie jest aktywne dla tego obszaru roboczego. Widżet otworzy stronę główną. |
| Element |
| Nie udało się załadować interfejsu widgetu. |
| Kontener osadzonego elementu nie istnieje. |
| Wywołanie nastąpiło po |
| Wszystko inne. |