SDK-referentie

Shayan TaslimBijgewerkt:

De SDK is beschikbaar als window.uj. Aanroepen zonder resultaat af te wachten via de inline proxy voor het laden (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) worden in de wachtrij gezet en opnieuw uitgevoerd zodra uj.js is geladen. Voor aanroepen die waarden of promises retourneren (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) moet het SDK-script eerst zijn geladen.

uj.version

De SDK-versietekst, bijvoorbeeld 1.0.0.

uj.init(projectId, options?)

Initialiseert de SDK. Geeft een promise terug die wordt opgelost met de SDK-status zodra het laden is voltooid.

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

Optie

Standaard

Beschrijving

widget

true

true toont de widget met de standaardinstellingen. false schakelt de widget uit. Met een object kun je deze configureren.

widget.launcher

true

false verbergt de standaardknop. { selector } koppelt de widget aan je eigen element.

widget.whispers

true

Tijdelijke notificatietoasts in de hoek van de widget. Ze werken onafhankelijk van de opener: ze blijven verschijnen als de knop verborgen is, tenzij dit is ingesteld op false. Een expliciete modus voor updatemeldingen overschrijft dit alleen voor aankondigingen van changelog-updates. Zie De widget bedienen.

widget.notifications.updates

'whisper', of 'none' wanneer whispers: false

'whisper' kondigt updates aan in een toastmelding; 'full' opent het nieuwste ongeziene item in de widgetlezer; 'none' onderdrukt updateaankondigingen zonder de ongelezen status te wijzigen. Expliciete waarden overschrijven whispers alleen voor updates.

widget.position

'right'

Aan welke kant van het scherm de widget wordt geopend.

widget.offset

{ bottom: 20, side: 20 }

Afstand in pixels tussen de launcher en whispers en de randen van de viewport.

widget.theme

'auto'

Volg de systeeminstelling of forceer de lichte of donkere modus.

locale

browser → standaardinstelling van de workspace

Taaloverschrijving. Als deze ontbreekt, wordt de browsertaal van de bezoeker vergeleken met de ingeschakelde talen van je workspace. Als er geen overeenkomst is, wordt de standaardtaal van de workspace gebruikt. Ondersteunt alle 14 UserJot-talen; regionale tags zoals es-MX worden omgezet naar de bijbehorende taal.

pageContext

'origin'

Hoeveel van de URL van de huidige pagina met je team wordt gedeeld in gesprekken en Live bezoekers. 'origin' stuurt alleen de hostnaam, 'path' bevat het pad (querystrings en #fragments worden weggelaten), 'none' stuurt niets.

onReady

Wordt aangeroepen zodra de SDK klaar is.

onError

Wordt aangeroepen bij elke SDK-fout.

De geretourneerde promise wordt niet afgewezen bij netwerkproblemen (controleer state.status === 'ready'). Afwijzing vindt alleen plaats bij programmeerfouten, zoals een lege project-ID of onjuist opgemaakte opties (INVALID_OPTIONS, recoverable: false).

De volledige updatemodus werkt zonder launcher, whispers of abonnementen op hostgebeurtenissen. Zie Updateaankondigingen voor de exacte regels voor zichtbaarheid, focus en opslag van de gelezen status.

uj.ready()

Retourneert dezelfde promise als init. Handig wanneer de code die de SDK nodig heeft losstaat van de initialisatie.

JavaScript
const state = await uj.ready();

uj.identify(input)

Identificeert de huidige gebruiker. Geeft een promise met het resultaat terug. Zie Gebruikers identificeren en Ondertekende identiteit.

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 heeft deze vorm:

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
}

Waarschuwingen en gereserveerde trait-sleutels

Code

field

Betekenis

RESERVED_TRAIT_KEY_IGNORED

De kenmerkensleutel

De sleutel is gereserveerd door UserJot en is genegeerd.

UNSIGNED_COMPANY_IGNORED

Het bedrijf id

De werkruimte vereist ondertekend lidmaatschap van het bedrijf en dit bedrijf stond niet in het token.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar of email

De gebruiker is beheerder of eigenaar van een werkruimte. Hun kenmerken en bedrijven worden toegepast; hun naam, avatar en e-mailadres worden beheerd in het dashboard.

De volgende trait-sleutels zijn gereserveerd en worden genegeerd (waarbij RESERVED_TRAIT_KEY_IGNORED wordt uitgezonden): 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 en __proto__.

Minstens één van token of user.id is vereist. Als je identify opnieuw aanroept met dezelfde invoer, gebeurt er niets zolang de sessie nog actief is; zodra deze is verlopen, verstuurt dezelfde invoer een nieuw verzoek. Bij nieuwe invoer wordt de sessie omgeschakeld. Als meerdere aanroepen elkaar overlappen, wint de laatste. identify is de enige methode die bij runtimefouten een foutmelding geeft (IDENTIFY_FAILED), en die een lokale wachttijd afdwingt na HTTP 429-reacties (met inachtneming van Retry-After, begrensd op minimaal 1 seconde en maximaal 1 uur, met een standaardwaarde van 60 seconden).

uj.logout()

Wist de huidige identiteit en zet de sessie terug naar anoniem.

JavaScript
await uj.logout();

uj.open(target?)

Opent de widget. Zonder argument wordt de widget geopend op de plek waar de gebruiker is gebleven. Wordt voltooid zodra de widget zichtbaar is.

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

Het doel van help mag maximaal één van article, collection of query bevatten. article en collection accepteren de URL-slug; oude slugs verwijzen door naar de verplaatste pagina. De promise wordt afgewezen met INVALID_NAVIGATION bij onbekende doelen of ongeldige combinaties.

uj.close()

Verbergt de widget. Dit gebeurt synchroon en je kunt dit op elk moment veilig aanroepen.

uj.toggle()

Opent de widget als deze gesloten is en sluit deze als hij geopend is.

uj.createEmbed(options?)

Geeft een UserJot-pagina weer in een container op je pagina. Retourneert een controller. Zie Pagina's inline insluiten.

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)

Wijzigt de widgettaal tijdens runtime:

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

uj.setTheme(theme)

Wijzigt het widgetthema synchroon ('auto', 'light' of 'dark'). Ongeldige waarden geven INVALID_OPTIONS door via de gebeurtenis error. Omdat init altijd zijn eigen thema toepast (standaard 'auto'), moet je je beginthema opgeven in init in plaats van setTheme aan te roepen vóór init.

uj.getState()

Retourneert een alleen-lezen momentopname van de SDK-status:

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)

Abonneert zich op een gebeurtenis en retourneert een functie om het abonnement op te zeggen. Luisteraars blijven bestaan na destroy().

Gebeurtenis

Payload

Wanneer deze wordt geactiveerd

ready

status

Laden voltooid. Wordt onmiddellijk opnieuw afgespeeld als het laden al is voltooid.

statechange

status

Bij elke statuswijziging.

open

status

De widget werd zichtbaar.

close

status

De widget werd verborgen.

identify

{ viewer, identityTrust }

De identiteit is gewijzigd, ook bij uitloggen.

unread

{ count }

Het aantal ongelezen items is gewijzigd. Wordt onmiddellijk opnieuw afgespeeld als de SDK al gereed is en de gegevens zijn opgehaald.

presence

{ availability }

De beschikbaarheid van het team is gewijzigd tussen 'online' en 'neutral'. Wordt onmiddellijk opnieuw afgespeeld als de SDK al gereed is.

error

fout

Bij elke SDK-fout.

destroy

status

De SDK is vernietigd.

Als je je abonneert op unread of presence, blijven beide waarden op de achtergrond actueel, ook wanneer de standaardlauncher verborgen is.

uj.destroy(options?)

Verwijdert de widget, alle embeds en de sessie van de pagina:

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

clearConversationData wist ook lokale toestemmingen voor anonieme gesprekken, concepten en onthouden contactgegevens (handig op gedeelde apparaten).

DOM-attributen voor het vastleggen van schermafbeeldingen

Wanneer een gebruiker vanuit de feedbackeditor van de widget een schermafbeelding van de pagina maakt (terugvaloptie voor DOM-vastlegging), verbergt UserJot automatisch widgetonderdelen en maskeert het input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] en input[name*="secret" i]. Je kunt het vastleggen ook voor specifieke elementen beheren met HTML-attributen:

Attribuut

Effect bij het vastleggen van een schermafbeelding van de pagina

data-userjot-capture-ignore

Laat het element volledig weg uit de vastgelegde schermafbeelding.

data-userjot-capture-mask

Maakt de zichtbare inhoud van het element onleesbaar in de vastgelegde schermafbeelding.

data-userjot-sensitive

Maskeert gevoelige <textarea>-velden automatisch.

Fouten

Fouten hebben de vorm { code, message, recoverable, cause? }.

Code

Betekenis

INVALID_PROJECT_ID

init is aangeroepen met een lege project-ID.

INVALID_OPTIONS

init, setLocale of setTheme heeft ongeldige opties ontvangen.

INVALID_NAVIGATION

open heeft een onbekend of ongeldig doel ontvangen.

INVALID_IDENTIFY

In de invoer van identify ontbreken zowel token als user.id.

IDENTIFY_FAILED

De server heeft de identify-aanroep afgewezen (bijvoorbeeld vanwege een ongeldig token, een ontbrekende handtekening in de strikte modus, een conflict met 409, een snelheidslimiet of een verwijderd lid).

BOOTSTRAP_FAILED

De SDK kon niet worden geladen. Controleer de project-ID, CSP-regels en netwerkverbinding.

NOT_READY

Er is een aanroep uitgevoerd terwijl de SDK zich in een foutstatus bevond.

WIDGET_DISABLED

open is aangeroepen terwijl de widget is uitgeschakeld.

CONVERSATIONS_DISABLED

Berichten zijn uitgeschakeld voor deze workspace. De widget opent in plaats daarvan Home.

HELP_DISABLED

Het Help Center is niet actief voor deze workspace. De widget opent in plaats daarvan Home.

LAUNCHER_NOT_FOUND

Het element launcher.selector bestaat niet.

SIDEBAR_LOAD_FAILED

De gebruikersinterface van de widget kon niet worden geladen.

EMBED_CONTAINER_NOT_FOUND

De embedcontainer bestaat niet.

DESTROYED

Er is een aanroep uitgevoerd nadat destroy() was aangeroepen.

UNKNOWN

Al het overige.

Heeft dit je vraag beantwoord?