Referência do SDK

Shayan TaslimAtualizado

O SDK é disponibilizado como window.uj. As chamadas sem espera de resposta feitas através do proxy inline de pré-carregamento (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) são colocadas em fila e reproduzidas assim que uj.js é carregado. As chamadas que devolvem valores ou promessas (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) requerem que o script do SDK já tenha sido carregado.

uj.version

A cadeia de versão do SDK, por exemplo 1.0.0.

uj.init(projectId, options?)

Inicializa o SDK. Devolve uma promessa que é resolvida com o estado do SDK quando o carregamento terminar.

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

Opção

Predefinição

Descrição

widget

true

true apresenta o widget com as predefinições. false desativa-o. Um objeto permite configurá-lo.

widget.launcher

true

false oculta o botão predefinido. { selector } associa o widget ao seu próprio elemento.

widget.whispers

true

Notificações temporárias no canto do widget. São independentes do botão de abertura: continuam a aparecer quando este está oculto, a menos que sejam definidas como false. Um modo explícito de notificação de atualizações substitui esta definição apenas para os anúncios do registo de alterações. Consulte Controlar o widget.

widget.notifications.updates

'whisper' ou 'none' quando whispers: false

'whisper' anuncia atualizações numa notificação; 'full' abre a entrada mais recente ainda não vista no leitor do widget; 'none' suprime os anúncios de atualização, mantendo as entradas por ler. Os valores explícitos substituem whispers apenas no que diz respeito às atualizações.

widget.position

'right'

O lado do ecrã em que o widget é aberto.

widget.offset

{ bottom: 20, side: 20 }

Distância em píxeis do botão de abertura e dos avisos discretos em relação aos limites da janela de visualização.

widget.theme

'auto'

Seguir o sistema ou forçar o modo claro ou escuro.

locale

predefinição do espaço de trabalho com base no navegador →

Substituição do idioma. Se omitida, compara o idioma do navegador do visitante com os idiomas ativados no espaço de trabalho e, em seguida, usa o idioma predefinido do espaço de trabalho. Suporta os 14 idiomas do UserJot; as etiquetas regionais, como es-MX, são convertidas no respetivo idioma.

pageContext

'origin'

Que parte do URL da página atual é partilhada com a sua equipa nas conversas e em Live visitors. 'origin' envia apenas o nome do anfitrião, 'path' inclui o caminho (com as cadeias de consulta e #fragments removidos) e 'none' não envia nada.

onReady

É chamado quando o SDK está pronto.

onError

É chamado perante qualquer erro do SDK.

A promessa devolvida não é rejeitada em caso de problemas de rede (verifique state.status === 'ready'). Só é rejeitada em caso de erros de programação, como um ID de projeto vazio ou opções malformadas (INVALID_OPTIONS, recoverable: false).

O modo de atualização completa funciona sem botão de abertura, avisos discretos ou subscrições do anfitrião. Consulte Anúncios de atualização para conhecer as regras exatas de visibilidade, foco e armazenamento de itens vistos.

uj.ready()

Devolve a mesma promessa que init. Útil quando o código que precisa do SDK está separado da inicialização.

JavaScript
const state = await uj.ready();

uj.identify(input)

Identifica o utilizador atual. Devolve uma promessa com o resultado. Consulte Identificar utilizadores e Identidade assinada.

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 tem esta estrutura:

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
}

Avisos e chaves de atributos reservadas

Código

field

Significado

RESERVED_TRAIT_KEY_IGNORED

A chave do atributo

A chave está reservada pelo UserJot e foi descartada.

UNSIGNED_COMPANY_IGNORED

A empresa id

O espaço de trabalho exige uma associação à empresa assinada e esta empresa não constava do token.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar ou email

O utilizador é administrador ou proprietário de um espaço de trabalho. Os respetivos atributos e empresas são aplicados; o nome, o avatar e o email são geridos no painel de controlo.

As seguintes chaves de atributos estão reservadas e são ignoradas (emitindo 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 e __proto__.

É necessário pelo menos um de token ou user.id. Voltar a chamar identify com a mesma entrada não tem efeito enquanto a sessão estiver ativa; quando expirar, a mesma entrada envia um novo pedido. Chamar o método com uma nova entrada muda de sessão. Se várias chamadas se sobrepuserem, prevalece a última. identify é o único método que rejeita a promessa em caso de falhas durante a execução (IDENTIFY_FAILED), e impõe um período de espera local após respostas HTTP 429 (respeitando Retry-After, limitado a um segundo e uma hora, com um valor predefinido de 60 segundos).

uj.logout()

Limpa a identidade atual e devolve a sessão ao estado anónimo.

JavaScript
await uj.logout();

uj.open(target?)

Abre o widget. Sem argumentos, abre no ponto onde o utilizador ficou. A promessa é resolvida quando o widget fica visível.

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

O destino de help aceita, no máximo, um de article, collection ou query. article e collection recebem o slug do URL, e os slugs antigos redirecionam para a página para onde foram movidos. É rejeitado com INVALID_NAVIGATION se o destino for desconhecido ou se a combinação for inválida.

uj.close()

Oculta o widget. É síncrono e pode ser chamado em qualquer altura.

uj.toggle()

Abre o widget se estiver fechado e fecha-o se estiver aberto.

uj.createEmbed(options?)

Apresenta uma página do UserJot dentro de um contentor na sua página. Devolve um controlador. Consulte Incorporar páginas em linha.

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)

Altera o idioma do widget durante a execução:

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

uj.setTheme(theme)

Altera o tema do widget de forma síncrona ('auto', 'light' ou 'dark'). Os valores inválidos emitem INVALID_OPTIONS através do evento error. Como init aplica sempre o seu próprio tema (por predefinição, 'auto'), indique o tema inicial em init em vez de chamar setTheme antes de init.

uj.getState()

Devolve uma captura só de leitura do estado do 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)

Subscreve um evento e devolve uma função para cancelar a subscrição. Os ouvintes mantêm-se após destroy().

Evento

Dados

Quando ocorre

ready

estado

Carregamento concluído. Se já tiver sido concluído, reproduz o evento imediatamente.

statechange

estado

Qualquer alteração de estado.

open

estado

O widget ficou visível.

close

estado

O widget foi ocultado.

identify

{ viewer, identityTrust }

A identidade foi alterada, incluindo ao terminar sessão.

unread

{ count }

Contagem de itens por ler alterada. Se o SDK já estiver pronto e os dados tiverem sido obtidos, reproduz o evento imediatamente.

presence

{ availability }

A disponibilidade da equipa passou de 'online' para 'neutral' ou vice-versa. Se o SDK já estiver pronto, reproduz o evento imediatamente.

error

erro

Qualquer erro do SDK.

destroy

estado

O SDK foi destruído.

A subscrição de unread ou presence mantém ambos os valores atualizados em segundo plano, mesmo quando o botão de abertura predefinido está oculto.

uj.destroy(options?)

Remove o widget, todas as incorporações e a sessão da página:

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

clearConversationData também limpa as autorizações locais de conversação anónima, os rascunhos e os dados de contacto guardados (útil em dispositivos partilhados).

Atributos DOM para a captura de ecrãs

Quando um utilizador captura uma imagem de ecrã na página através do compositor de feedback do widget (alternativa de captura do DOM), o UserJot oculta automaticamente as superfícies do widget e mascara input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] e input[name*="secret" i]. Também pode controlar a captura em elementos específicos com atributos HTML:

Atributo

Efeito durante a captura de ecrã na página

data-userjot-capture-ignore

Exclui completamente o elemento da captura de ecrã.

data-userjot-capture-mask

Oculta o conteúdo visível do elemento na captura de ecrã.

data-userjot-sensitive

Mascara automaticamente os campos <textarea> sensíveis.

Erros

Os erros têm a estrutura { code, message, recoverable, cause? }.

Código

Significado

INVALID_PROJECT_ID

init foi chamado com um ID de projeto vazio.

INVALID_OPTIONS

init, setLocale ou setTheme receberam opções inválidas.

INVALID_NAVIGATION

open recebeu um destino desconhecido ou inválido.

INVALID_IDENTIFY

Faltam token e user.id na entrada de identify.

IDENTIFY_FAILED

O servidor rejeitou a chamada de identificação (por exemplo, devido a um token inválido, à falta de assinatura no modo estrito, a um conflito de 409, a um limite de pedidos ou a um membro apagado).

BOOTSTRAP_FAILED

Não foi possível carregar o SDK. Verifique o ID do projeto, as regras de CSP e a rede.

NOT_READY

Foi feita uma chamada enquanto o SDK se encontrava num estado de falha.

WIDGET_DISABLED

open foi chamado quando o widget está desativado.

CONVERSATIONS_DISABLED

As mensagens estão desativadas para este espaço de trabalho. Em vez disso, o widget abre a página inicial.

HELP_DISABLED

O Centro de Ajuda não está ativo para este espaço de trabalho. Em vez disso, o widget abre a página inicial.

LAUNCHER_NOT_FOUND

O elemento launcher.selector não existe.

SIDEBAR_LOAD_FAILED

Não foi possível carregar a interface do widget.

EMBED_CONTAINER_NOT_FOUND

O contentor de incorporação não existe.

DESTROYED

Foi feita uma chamada depois de destroy().

UNKNOWN

Qualquer outra coisa.

Isto respondeu à sua pergunta?