SDK 参考
SDK 以 window.uj 的形式公开。通过内联预加载代理(init、open、close、toggle、identify、logout、setLocale、setTheme、destroy)发起的即发即忘调用会进入队列,并在 uj.js 加载后重放。返回值或 promise 的调用(await uj.identify(...)、uj.createEmbed(...)、uj.on(...)、uj.getState()、uj.version)必须等 SDK 脚本先加载完成。
uj.version
SDK 版本字符串,例如 1.0.0。
uj.init(projectId, options?)
初始化 SDK。返回一个 promise,待加载过程结束后会以 SDK 状态作为结果解析。
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) => {}
});选项 | 默认值 | 说明 |
|---|---|---|
|
|
|
|
|
|
|
| 在小组件角落显示短暂的通知提示。此功能独立于启动按钮:即使按钮被隐藏,提示仍会显示,除非设为 |
|
|
|
|
| 小组件从屏幕哪一侧展开。 |
|
| 启动器和 whispers 距视口边缘的像素距离。 |
|
| 遵循系统设置,或强制使用浅色或深色模式。 |
| 浏览器 → 工作区默认值 | 语言覆盖设置。省略时,会将访客的浏览器语言与工作区已启用的语言进行匹配;若无匹配项,则使用工作区默认语言。支持全部 14 种 UserJot 语言;区域标签(如 |
|
| 在对话和 实时访客中与团队共享当前页面 URL 的范围。 |
| SDK 就绪时调用。 | |
| 发生任何 SDK 错误时调用。 |
遇到网络问题时,返回的 promise 不会拒绝(请检查 state.status === 'ready')。只有在出现程序错误时才会拒绝,例如项目 ID 为空或选项格式错误(INVALID_OPTIONS、recoverable: false)。
完整更新模式无需启动器、whispers 或宿主订阅即可运行。有关可见性、焦点和已读存储规则的详情,请参阅 更新通知。
uj.ready()
返回与 init 相同的 promise。当需要 SDK 的代码与初始化代码分开时,这会很有用。
const state = await uj.ready();uj.identify(input)
识别当前用户。返回一个包含结果的 promise。参见 识别用户 和 签名身份。
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 的结构如下:
{
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
}警告和保留的 trait 键
代码 |
| 含义 |
|---|---|---|
| 特征键 | 该键由 UserJot 保留,因此已被丢弃。 |
| 公司 | 该工作区要求提供签名的公司成员身份,而此公司未包含在令牌中。 |
|
| 该用户是工作区管理员或所有者。其特征和公司信息会应用于该用户;姓名、头像和电子邮件由控制面板管理。 |
以下 trait 键为保留键,会被忽略(并触发 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 和 __proto__。
必须至少提供 token 或 user.id。在会话仍有效期间,使用相同输入再次调用 identify 不会执行任何操作;会话过期后,使用相同输入会发送新的请求。使用新输入调用则会切换会话。如果多个调用重叠,则以最后一次调用为准。identify 是唯一一个在运行时失败时会拒绝的 method(IDENTIFY_FAILED),并且在收到 HTTP 429 响应后会强制执行本地退避时段(遵循 Retry-After,时长限制为 1 秒至 1 小时,默认 60 秒)。
uj.logout()
清除当前身份,并将会话恢复为匿名状态。
await uj.logout();uj.open(target?)
打开小组件。不带参数时,会打开到用户上次离开时所在的位置。小组件显示后,操作即完成。
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' });help 目标最多只能指定 article、collection 或 query 中的一项。article 和 collection 接受 URL slug;旧 slug 会重定向到迁移后的页面。目标未知或组合无效时,会以 INVALID_NAVIGATION 拒绝。
uj.close()
隐藏小组件。同步执行,可随时安全调用。
uj.toggle()
如果小组件处于关闭状态,则将其打开;如果处于打开状态,则将其关闭。
uj.createEmbed(options?)
在页面上的容器中呈现 UserJot 页面,并返回一个控制器。请参阅 在页面中嵌入内容。
const embed = uj.createEmbed({
container: '[data-userjot-embed]',
path: '/',
basePath: '/feedback',
theme: 'auto',
onReady: () => {},
onError: (error) => {}
});
embed.navigate('/roadmap');
embed.destroy();uj.setLocale(locale)
在运行时更改小组件语言:
await uj.setLocale('pt-BR');uj.setTheme(theme)
同步更改小组件主题('auto'、'light' 或 'dark')。值无效时,会通过 error 事件触发 INVALID_OPTIONS。由于 init 总会应用自己的主题(默认值为 'auto'),请在 init 中传入初始主题,而不要在 init 之前调用 setTheme。
uj.getState()
返回 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)
订阅事件并返回一个取消订阅函数。监听器在 destroy() 后仍会保留。
事件 | 有效负载 | 触发时机 |
|---|---|---|
| 状态 | 加载已完成。如果加载已完成,则立即重放。 |
| 状态 | 任何状态变化。 |
| 状态 | 小组件已显示。 |
| 状态 | 小组件已隐藏。 |
|
| 身份发生变化,包括退出登录。 |
|
| 未读数发生变化。如果已就绪且已获取数据,则立即重放。 |
|
| 团队可用状态在 |
| 错误 | 任何 SDK 错误。 |
| 状态 | SDK 已销毁。 |
订阅 unread 或 presence 后,即使默认启动器处于隐藏状态,这两个值也会在后台保持最新。
uj.destroy(options?)
从页面中移除小组件、所有嵌入内容和会话:
uj.destroy();
uj.destroy({ clearConversationData: true });clearConversationData 还会清除本地匿名会话授权、草稿和记住的联系信息(适用于共享设备)。
用于屏幕截图捕获的 DOM 属性
当用户通过小组件反馈编辑器捕获页面内屏幕截图时(DOM 捕获回退方案),UserJot 会自动隐藏小组件界面,并遮盖 input[type="password"]、input[type="email"]、input[type="tel"]、input[name*="token" i] 和 input[name*="secret" i]。你也可以使用 HTML 属性控制特定元素的捕获行为:
属性 | 页面内屏幕截图捕获期间的效果 |
|---|---|
| 完全不将该元素包含在捕获的屏幕截图中。 |
| 遮盖该元素在捕获的屏幕截图中可见的内容。 |
| 自动遮盖敏感的 |
错误
错误的结构为 { code, message, recoverable, cause? }。
代码 | 含义 |
|---|---|
| 调用 |
|
|
|
|
|
|
| 服务器拒绝了 identify 调用(例如,令牌无效、严格模式下缺少签名、 |
| SDK 无法加载。请检查项目 ID、CSP 规则和网络连接。 |
| SDK 处于失败状态时执行了调用。 |
| 小组件已停用时调用了 |
| 此工作区已停用消息功能。小组件会改为打开“主页”。 |
| 此工作区的帮助中心尚未上线。小组件会改为打开“主页”。 |
|
|
| widget 界面加载失败。 |
| 嵌入容器不存在。 |
| 在调用 |
| 其他所有情况。 |