Referência do SDK
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.
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 |
|---|---|---|
|
|
|
|
|
|
|
| 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 |
|
|
|
|
| Em que lado da tela o widget é aberto. |
|
| Distância em pixels do iniciador e das notificações sussurradas em relação às bordas da janela de visualização. |
|
| Seguir as configurações do sistema ou forçar o modo claro ou escuro. |
| 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 |
|
| Quanto da URL da página atual é compartilhado com sua equipe nas conversas e em Visitantes ao vivo. |
| Chamado quando o SDK está pronto. | |
| 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.
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.
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:
{
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 |
| Significado |
|---|---|---|
| A chave da característica | A chave é reservada pelo UserJot e foi descartada. |
| A empresa | O workspace exige associação à empresa assinada, e esta empresa não estava no token. |
|
| 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.
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.
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.
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:
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:
{
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 |
|---|---|---|
| estado | Carregamento concluído. Reproduz imediatamente se já tiver sido concluído. |
| estado | Qualquer alteração de estado. |
| estado | O widget ficou visível. |
| estado | O widget foi ocultado. |
|
| A identidade foi alterada, inclusive ao sair da conta. |
|
| Contagem de itens não lidos alterada. Reproduz imediatamente se já estiver pronto e os dados tiverem sido carregados. |
|
| A disponibilidade da equipe mudou entre |
| erro | Qualquer erro do SDK. |
| 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:
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 |
|---|---|
| Exclui completamente o elemento da captura de tela. |
| Oculta o conteúdo visível do elemento na captura de tela. |
| Mascara automaticamente os campos |
Erros
Os erros têm o formato { code, message, recoverable, cause? }.
Código | Significado |
|---|---|
|
|
|
|
|
|
| A entrada de |
| O servidor rejeitou a chamada identify (por exemplo, token inválido, assinatura ausente no modo estrito, conflito de |
| Não foi possível carregar o SDK. Verifique o ID do projeto, as regras de CSP e a rede. |
| Uma chamada foi executada enquanto o SDK estava em estado de falha. |
|
|
| As mensagens estão desativadas para este workspace. O widget abre a página inicial. |
| A Central de Ajuda não está publicada para este workspace. O widget abre a página inicial. |
| O elemento |
| Falha ao carregar a interface do widget. |
| O contêiner do embed não existe. |
| Uma chamada foi executada após |
| Qualquer outra coisa. |