SDK 参考

Shayan Taslim更新

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 状态作为结果解析。

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) => {}
});

选项

默认值

说明

widget

true

true 使用默认设置显示小组件。false 会将其禁用。传入对象可对其进行配置。

widget.launcher

true

false 会隐藏默认按钮。{ selector } 会将小组件绑定到你自己的元素。

widget.whispers

true

在小组件角落显示短暂的通知提示。此功能独立于启动按钮:即使按钮被隐藏,提示仍会显示,除非设为 false。显式设置更新通知模式只会覆盖此设置中的更新日志公告。参见 控制小组件。

widget.notifications.updates

'whisper',或在 whispers: false 时使用 'none'

'whisper' 会通过 toast 通知播报更新;'full' 会在小组件阅读器中打开最新的未读条目;'none' 会隐藏更新通知,但保留未读状态。显式值仅会覆盖更新相关的 whispers。

widget.position

'right'

小组件从屏幕哪一侧展开。

widget.offset

{ bottom: 20, side: 20 }

启动器和 whispers 距视口边缘的像素距离。

widget.theme

'auto'

遵循系统设置,或强制使用浅色或深色模式。

locale

浏览器 → 工作区默认值

语言覆盖设置。省略时,会将访客的浏览器语言与工作区已启用的语言进行匹配;若无匹配项,则使用工作区默认语言。支持全部 14 种 UserJot 语言;区域标签(如 es-MX)会解析为对应语言。

pageContext

'origin'

在对话和 实时访客中与团队共享当前页面 URL 的范围。'origin' 仅发送主机名,'path' 包含路径名(会剥除查询字符串和 #fragments),'none' 则不发送任何内容。

onReady

SDK 就绪时调用。

onError

发生任何 SDK 错误时调用。

遇到网络问题时,返回的 promise 不会拒绝(请检查 state.status === 'ready')。只有在出现程序错误时才会拒绝,例如项目 ID 为空或选项格式错误(INVALID_OPTIONS、recoverable: false)。

完整更新模式无需启动器、whispers 或宿主订阅即可运行。有关可见性、焦点和已读存储规则的详情,请参阅 更新通知。

uj.ready()

返回与 init 相同的 promise。当需要 SDK 的代码与初始化代码分开时,这会很有用。

JavaScript
const state = await uj.ready();

uj.identify(input)

识别当前用户。返回一个包含结果的 promise。参见 识别用户 和 签名身份。

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 的结构如下:

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
}

警告和保留的 trait 键

代码

field

含义

RESERVED_TRAIT_KEY_IGNORED

特征键

该键由 UserJot 保留,因此已被丢弃。

UNSIGNED_COMPANY_IGNORED

公司 id

该工作区要求提供签名的公司成员身份,而此公司未包含在令牌中。

PRIVILEGED_PROFILE_IGNORED

firstName、lastName、avatar 或 email

该用户是工作区管理员或所有者。其特征和公司信息会应用于该用户;姓名、头像和电子邮件由控制面板管理。

以下 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()

清除当前身份,并将会话恢复为匿名状态。

JavaScript
await uj.logout();

uj.open(target?)

打开小组件。不带参数时,会打开到用户上次离开时所在的位置。小组件显示后,操作即完成。

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' });

help 目标最多只能指定 article、collection 或 query 中的一项。article 和 collection 接受 URL slug;旧 slug 会重定向到迁移后的页面。目标未知或组合无效时,会以 INVALID_NAVIGATION 拒绝。

uj.close()

隐藏小组件。同步执行,可随时安全调用。

uj.toggle()

如果小组件处于关闭状态,则将其打开;如果处于打开状态,则将其关闭。

uj.createEmbed(options?)

在页面上的容器中呈现 UserJot 页面,并返回一个控制器。请参阅 在页面中嵌入内容。

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)

在运行时更改小组件语言:

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

uj.setTheme(theme)

同步更改小组件主题('auto'、'light' 或 'dark')。值无效时,会通过 error 事件触发 INVALID_OPTIONS。由于 init 总会应用自己的主题(默认值为 'auto'),请在 init 中传入初始主题,而不要在 init 之前调用 setTheme。

uj.getState()

返回 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)

订阅事件并返回一个取消订阅函数。监听器在 destroy() 后仍会保留。

事件

有效负载

触发时机

ready

状态

加载已完成。如果加载已完成,则立即重放。

statechange

状态

任何状态变化。

open

状态

小组件已显示。

close

状态

小组件已隐藏。

identify

{ viewer, identityTrust }

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

unread

{ count }

未读数发生变化。如果已就绪且已获取数据,则立即重放。

presence

{ availability }

团队可用状态在 'online' 和 'neutral' 之间切换。如果已就绪,则立即重放。

error

错误

任何 SDK 错误。

destroy

状态

SDK 已销毁。

订阅 unread 或 presence 后,即使默认启动器处于隐藏状态,这两个值也会在后台保持最新。

uj.destroy(options?)

从页面中移除小组件、所有嵌入内容和会话:

JavaScript
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 属性控制特定元素的捕获行为:

属性

页面内屏幕截图捕获期间的效果

data-userjot-capture-ignore

完全不将该元素包含在捕获的屏幕截图中。

data-userjot-capture-mask

遮盖该元素在捕获的屏幕截图中可见的内容。

data-userjot-sensitive

自动遮盖敏感的 <textarea> 字段。

错误

错误的结构为 { code, message, recoverable, cause? }。

代码

含义

INVALID_PROJECT_ID

调用 init 时使用了空的项目 ID。

INVALID_OPTIONS

init、setLocale 或 setTheme 收到了无效选项。

INVALID_NAVIGATION

open 收到了未知或无效的目标。

INVALID_IDENTIFY

identify 输入中缺少 token 和 user.id。

IDENTIFY_FAILED

服务器拒绝了 identify 调用(例如,令牌无效、严格模式下缺少签名、409 冲突、触发速率限制,或成员已被删除)。

BOOTSTRAP_FAILED

SDK 无法加载。请检查项目 ID、CSP 规则和网络连接。

NOT_READY

SDK 处于失败状态时执行了调用。

WIDGET_DISABLED

小组件已停用时调用了 open。

CONVERSATIONS_DISABLED

此工作区已停用消息功能。小组件会改为打开“主页”。

HELP_DISABLED

此工作区的帮助中心尚未上线。小组件会改为打开“主页”。

LAUNCHER_NOT_FOUND

launcher.selector 元素不存在。

SIDEBAR_LOAD_FAILED

widget 界面加载失败。

EMBED_CONTAINER_NOT_FOUND

嵌入容器不存在。

DESTROYED

在调用 destroy() 后执行了调用。

UNKNOWN

其他所有情况。

这是否解答了您的问题?