控制小组件

Shayan Taslim更新

你可以通过自己的界面以编程方式控制小组件:打开特定版块、响应事件、配置更新公告,或完全替换默认启动器。

打开小组件

不带参数调用 uj.open() 会在用户上次离开的位置打开小组件:

JavaScript
uj.open();

传入目标位置即可打开特定版块:

JavaScript
uj.open({ to: 'home' });
uj.open({ to: 'feedback' });
uj.open({ to: 'roadmap' });
uj.open({ to: 'updates' });
uj.open({ to: 'messages' });
uj.open({ to: 'notifications' });
uj.open({ to: 'help' });

特定目标位置的深度链接选项:

JavaScript
// Open the feedback submission form directly
uj.open({ to: 'feedback', compose: true });

// Open a specific feedback post
uj.open({ to: 'feedback', submissionId: 'POST_ID' });

// Open a specific changelog update
uj.open({ to: 'updates', updateId: 'UPDATE_ID' });

// Start a message with prefilled text
uj.open({ to: 'messages', compose: { text: 'I need help with...' } });

// Open a help article, collection, or search results
uj.open({ to: 'help', article: 'reset-password' });
uj.open({ to: 'help', collection: 'billing' });
uj.open({ to: 'help', query: 'invoices' });

随时隐藏或切换小组件的显示状态:

JavaScript
uj.close();
uj.toggle();

messages 目标要求启用 Conversations;否则会通过 error 事件报告 CONVERSATIONS_DISABLED,并打开 Home。help 目标要求你的帮助中心已上线(article 和 collection 会接收 URL 路径段);否则会报告 HELP_DISABLED 并打开 Home。

监听事件

使用 uj.on(event, listener) 订阅事件;该方法会返回一个取消订阅函数:

JavaScript
const unsubscribe = uj.on('open', () => {
  console.log('widget opened');
});

unsubscribe();

事件

触发时机

ready

SDK 加载完成。如果 SDK 已加载,则会立即触发。

open

小组件变为可见。

close

小组件已隐藏。

identify

身份信息发生变化,包括退出登录。

unread

未读数量已更改。载荷为 { count }。如果小组件已就绪,则会立即重放此事件。

presence

团队在线状态已更改。载荷为 { availability: 'online' | 'neutral' }。如果小组件已就绪,则会立即重放此事件。

statechange

小组件状态的任意部分发生变化。

error

发生错误。载荷为错误对象。

读取状态

uj.getState() 会返回当前小组件状态的快照:

JavaScript
const state = uj.getState();

state.status;          // 'ready' once the SDK is loaded
state.widget.open;     // whether the widget is visible
state.unreadCount;     // number, or null before the first fetch
state.presence;        // 'online' or 'neutral'
state.session.status;  // 'anonymous', 'identifying', or 'identified'
state.session.viewer;  // the identified user, or null

创建自定义启动按钮

隐藏默认启动器,即可通过自己的导航项或按钮控制小组件:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false }
});

隐藏启动器会移除默认按钮,但角落中的通知轻提示仍会显示(请参阅下文的“轻提示”,了解如何调整其位置或将其关闭)。

为你的按钮、未读徽标以及可选的团队在线状态指示器添加事件处理:

JavaScript
const button = document.querySelector('#feedback-button');
const badge = document.querySelector('#feedback-badge');
const dot = document.querySelector('#feedback-online-dot');

button.addEventListener('click', () => uj.toggle());

uj.on('unread', ({ count }) => {
  badge.textContent = count > 0 ? String(count) : '';
});

uj.on('presence', ({ availability }) => {
  dot.hidden = availability !== 'online';
});

'neutral' 表示 SDK 无法确认当前是否有客服人员在线,因此应隐藏指示器,而不是显示“离线”标签。小组件关闭时,在线状态会在页面加载、标签页获得焦点时以及每隔几分钟刷新一次;小组件打开时则会实时更新。

在默认启动器上,未读提示的优先级高于绿色的在线状态圆点。未读计数包含对话回复、更新日志文章和反馈通知。存在未读内容时,点击默认启动器会按以下优先级跳转:先到消息(未读对话回复),再到通知(未查看的反馈通知),最后到最新的未查看更新。

若要将默认启动器行为直接绑定到页面上已有的元素,请传入 CSS 选择器:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: { selector: '#feedback-button' } }
});

提示气泡

轻提示是短暂出现、可点击的角落弹窗,用于提醒团队对话中有未读回复、收到反馈通知或发布了新的更新日志文章。优先级依次为:未读对话回复、反馈评论/回复通知、其他通知,最后是更新日志更新。为保护隐私,对话轻提示只显示队友的头像和<Name> replied(绝不显示消息文本),点击后会打开消息。

  • 时效性和时间要求:仅对过去14 天内创建或发布的内容显示轻提示。小组件会等待用户实际操作:用户在页面停留4 秒、静止1.2 秒,且距离上次轻提示至少30 秒。用户正在输入框、文本区域、选择框或可编辑字段中输入时,或在自动化浏览器中时,轻提示绝不会打断用户。

  • 重复次数限制和退避机制:每个项目最多显示轻提示3 次(需持续可见且受到关注 1.5 秒,才计为已送达),之后按间隔退避:更新分别为30 分钟、24 小时和3 天;通知和对话回复分别为30 分钟、1 小时和24 小时。

  • 有无默认启动器均可:轻提示独立于启动器。使用默认启动器时,轻提示会从按钮展开;使用launcher: false或选择器启动器时,轻提示会独立显示在角落,并在超时后收起为可点击的圆形图标,保留60 秒后再隐藏。

使用 offset 调整轻提示的位置,避免遮挡你自己的界面:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    launcher: false,
    offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
  }
});

或者完全停用轻提示(不再显示对话、反馈和默认更新轻提示):

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false, whispers: false }
});

如果两者都已关闭,且未显式设置更新模式,那么在调用 uj.open() 之前,小组件不会显示任何内容;与此同时,unread 和 presence 订阅仍会在后台更新。

更新通知

使用 widget.notifications.updates 控制小组件如何播报最新的未读更新日志条目:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    notifications: { updates: 'full' }
  }
});

模式

行为

'whisper'

在角落通知中播报更新,并限制重复显示次数。

'full'

直接在小组件的阅读器中打开更新,并显示封面图片和完整内容。

'none'

不播报更新,但“更新”标签页和未读徽标仍保持启用。

如果省略,更新默认使用'whisper'(或在whispers: false时使用'none')。显式设置widget.notifications.updates只会覆盖更新日志更新的whispers;对话和反馈轻提示仍遵循whispers。

即使启动器已隐藏且没有事件监听器,完整模式仍然有效。首次访问时,即使最新已发布的更新发布时间较早,完整模式也可能会将其打开。SDK 在每次初始化访问中最多尝试自动打开一次(手动打开、切换、关闭或尝试失败都会用掉这次机会;重新加载页面或调用 init() 会开始新的访问,而身份变更或 SPA 导航不会)。自动打开要求页面可见且已获得焦点,并且小组件处于关闭状态;当 widget: false 时,自动打开会被禁用。

当更新内容在页面可见且已获得焦点时,加载到显示中的小组件后,该更新就会被标记为已读。已读状态会按项目和来源保存在浏览器本地存储中;更新会在初始化时、标签页获得焦点时以及小组件关闭期间大约每五分钟检查一次。

更改语言

如果未指定 locale,小组件会按以下顺序选择语言:

  1. 传递给 uj.init(...) 或 uj.setLocale(...) 的显式 locale 选项。

  2. 访客的浏览器语言(如果该语言与工作区在 设置 → 语言 中启用的语言相符)。

  3. 工作区的默认语言。

小组件支持全部 14 种 UserJot 语言(请参阅 语言)。你可以在初始化时或运行期间更改语言,无需重新加载:

JavaScript
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });

// Change later at runtime
await uj.setLocale('pt-BR');

这是否解答了您的问题?