Referência do SDK
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.
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 |
|---|---|---|
|
|
|
|
|
|
|
| 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 |
|
|
|
|
| O lado do ecrã em que o widget é aberto. |
|
| Distância em píxeis do botão de abertura e dos avisos discretos em relação aos limites da janela de visualização. |
|
| Seguir o sistema ou forçar o modo claro ou escuro. |
| 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 |
|
| Que parte do URL da página atual é partilhada com a sua equipa nas conversas e em Live visitors. |
| É chamado quando o SDK está pronto. | |
| É 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.
const state = await uj.ready();uj.identify(input)
Identifica o utilizador atual. Devolve uma promessa com o resultado. Consulte Identificar utilizadores 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 esta estrutura:
{
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 |
| Significado |
|---|---|---|
| A chave do atributo | A chave está reservada pelo UserJot e foi descartada. |
| A empresa | O espaço de trabalho exige uma associação à empresa assinada e esta empresa não constava do token. |
|
| 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.
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.
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.
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:
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:
{
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 |
|---|---|---|
| estado | Carregamento concluído. Se já tiver sido concluído, reproduz o evento imediatamente. |
| estado | Qualquer alteração de estado. |
| estado | O widget ficou visível. |
| estado | O widget foi ocultado. |
|
| A identidade foi alterada, incluindo ao terminar sessão. |
|
| Contagem de itens por ler alterada. Se o SDK já estiver pronto e os dados tiverem sido obtidos, reproduz o evento imediatamente. |
|
| A disponibilidade da equipa passou de |
| erro | Qualquer erro do SDK. |
| 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:
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 |
|---|---|
| Exclui completamente o elemento da captura de ecrã. |
| Oculta o conteúdo visível do elemento na captura de ecrã. |
| Mascara automaticamente os campos |
Erros
Os erros têm a estrutura { code, message, recoverable, cause? }.
Código | Significado |
|---|---|
|
|
|
|
|
|
| Faltam |
| 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 |
| Não foi possível carregar o SDK. Verifique o ID do projeto, as regras de CSP e a rede. |
| Foi feita uma chamada enquanto o SDK se encontrava num estado de falha. |
|
|
| As mensagens estão desativadas para este espaço de trabalho. Em vez disso, o widget abre a página inicial. |
| O Centro de Ajuda não está ativo para este espaço de trabalho. Em vez disso, o widget abre a página inicial. |
| O elemento |
| Não foi possível carregar a interface do widget. |
| O contentor de incorporação não existe. |
| Foi feita uma chamada depois de |
| Qualquer outra coisa. |