Referência do SDK

Shayan TaslimAtualizado

O SDK é exposto como window.uj. Chamadas fire-and-forget feitas pelo proxy inline de pré-carregamento (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) são enfileiradas e executadas novamente assim que uj.js é carregado. Chamadas que retornam valores ou promises (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) exigem que o script do SDK já tenha sido carregado.

uj.version

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

uj.init(projectId, options?)

Inicializa o SDK. Retorna uma promise que é resolvida com o estado do SDK quando o carregamento termina.

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

Padrão

Descrição

widget

true

true exibe o widget com as configurações padrão. false o desativa. Um objeto permite configurá-lo.

widget.launcher

true

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

widget.whispers

true

Notificações efêmeras exibidas no canto do widget. São independentes do botão de abertura: continuam aparecendo quando o botão está oculto, a menos que sejam definidas como false. Um modo explícito de notificação de atualizações substitui essa configuração apenas para os anúncios do changelog. Consulte Como controlar o widget.

widget.notifications.updates

'whisper', ou 'none' quando whispers: false

'whisper' anuncia atualizações em uma notificação toast; 'full' abre a entrada mais recente ainda não vista no leitor do widget; 'none' suprime os anúncios de atualização, mas mantém o status de não lida. Valores explícitos substituem whispers apenas para atualizações.

widget.position

'right'

Em que lado da tela o widget é aberto.

widget.offset

{ bottom: 20, side: 20 }

Distância em pixels do iniciador e das notificações sussurradas em relação às bordas da janela de visualização.

widget.theme

'auto'

Seguir as configurações do sistema ou forçar o modo claro ou escuro.

locale

navegador → padrão do workspace

Substituição de idioma. Se omitida, compara o idioma do navegador do visitante com os idiomas ativados no seu workspace e, em seguida, usa o idioma padrão do workspace. Compatível com todos os 14 idiomas do UserJot; tags regionais, como es-MX, são resolvidas para o idioma correspondente.

pageContext

'origin'

Quanto da URL da página atual é compartilhado com sua equipe nas conversas e em Visitantes ao vivo. 'origin' envia apenas o nome do host, 'path' inclui o caminho (com as strings de consulta e #fragments removidos), 'none' não envia nada.

onReady

Chamado quando o SDK está pronto.

onError

Chamado em caso de qualquer erro do SDK.

A promise retornada não é rejeitada em caso de problemas de rede (verifique state.status === 'ready'). Ela só é rejeitada por 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 iniciador, notificações sussurradas ou assinaturas do host. Consulte Anúncios de atualização para ver as regras exatas de visibilidade, foco e armazenamento de itens vistos.

uj.ready()

Retorna a mesma promise 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 usuário atual. Retorna uma promise com o resultado. Consulte Identificar usuários 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 este formato:

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 traits reservadas

Código

field

Significado

RESERVED_TRAIT_KEY_IGNORED

A chave da característica

A chave é reservada pelo UserJot e foi descartada.

UNSIGNED_COMPANY_IGNORED

A empresa id

O workspace exige associação à empresa assinada, e esta empresa não estava no token.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar ou email

O usuário é administrador ou proprietário de um espaço de trabalho. Os atributos e as empresas dele são aplicados; o nome, o avatar e o e-mail são gerenciados no painel.

As seguintes chaves de traits são reservadas e 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 informar pelo menos um entre token e user.id. Chamar identify novamente com a mesma entrada não faz nada enquanto a sessão ainda estiver ativa; depois que ela expirar, a mesma entrada envia uma nova solicitação. Chamá-lo com uma nova entrada troca a sessão. Se várias chamadas se sobrepuserem, a última prevalece. identify é o único método que rejeita a promessa em caso de falhas em tempo de execução (IDENTIFY_FAILED), e impõe um período de espera local após respostas HTTP 429 (respeitando Retry-After, limitado a um período entre 1 segundo e 1 hora, com padrão de 60 segundos).

uj.logout()

Limpa a identidade atual e retorna a sessão ao estado anônimo.

JavaScript
await uj.logout();

uj.open(target?)

Abre o widget. Sem argumentos, abre no ponto em que o usuário parou. 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 entre article, collection e query. article e collection recebem o slug do URL, e slugs antigos redirecionam para a página para a qual foram movidos. É rejeitado com INVALID_NAVIGATION para destinos desconhecidos ou combinações inválidas.

uj.close()

Oculta o widget. É síncrono e seguro para chamar a qualquer momento.

uj.toggle()

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

uj.createEmbed(options?)

Renderiza uma página do UserJot dentro de um contêiner na sua página. Retorna 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 em tempo de execução:

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

uj.setTheme(theme)

Altera o tema do widget de forma síncrona ('auto', 'light' ou 'dark'). Valores inválidos emitem INVALID_OPTIONS pelo evento error. Como init sempre aplica o próprio tema (usando 'auto' por padrão), passe o tema inicial em init em vez de chamar setTheme antes de init.

uj.getState()

Retorna um snapshot somente 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)

Inscreve-se em um evento e retorna uma função para cancelar a inscrição. Os listeners permanecem ativos após destroy().

Evento

Dados

Quando é disparado

ready

estado

Carregamento concluído. Reproduz imediatamente se já tiver sido concluído.

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, inclusive ao sair da conta.

unread

{ count }

Contagem de itens não lidos alterada. Reproduz imediatamente se já estiver pronto e os dados tiverem sido carregados.

presence

{ availability }

A disponibilidade da equipe mudou entre 'online' e 'neutral'. Reproduz imediatamente se já estiver pronto.

error

erro

Qualquer erro do SDK.

destroy

estado

O SDK foi destruído.

Inscrever-se em unread ou presence mantém ambos os valores atualizados em segundo plano, mesmo quando o iniciador padrão 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 permissões locais de conversa anônima, os rascunhos e os dados de contato lembrados (útil em dispositivos compartilhados).

Atributos do DOM para captura de tela

Quando um usuário captura uma captura de tela da página pelo 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]. Você também pode controlar a captura em elementos específicos usando atributos HTML:

Atributo

Efeito durante a captura de tela da página

data-userjot-capture-ignore

Exclui completamente o elemento da captura de tela.

data-userjot-capture-mask

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

data-userjot-sensitive

Mascara automaticamente os campos <textarea> confidenciais.

Erros

Os erros têm o formato { 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 recebeu opções inválidas.

INVALID_NAVIGATION

open recebeu um destino desconhecido ou inválido.

INVALID_IDENTIFY

A entrada de identify não contém token nem user.id.

IDENTIFY_FAILED

O servidor rejeitou a chamada identify (por exemplo, token inválido, assinatura ausente no modo estrito, conflito de 409, limite de requisições excedido ou 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

Uma chamada foi executada enquanto o SDK estava em estado de falha.

WIDGET_DISABLED

open foi chamado enquanto o widget estava desativado.

CONVERSATIONS_DISABLED

As mensagens estão desativadas para este workspace. O widget abre a página inicial.

HELP_DISABLED

A Central de Ajuda não está publicada para este workspace. O widget abre a página inicial.

LAUNCHER_NOT_FOUND

O elemento launcher.selector não existe.

SIDEBAR_LOAD_FAILED

Falha ao carregar a interface do widget.

EMBED_CONTAINER_NOT_FOUND

O contêiner do embed não existe.

DESTROYED

Uma chamada foi executada após destroy().

UNKNOWN

Qualquer outra coisa.

Isso respondeu à sua pergunta?