Widget 安装
安装 widget 只需一段代码。将它粘贴到 HTML 页面的靠近末尾处,也就是紧挨着闭合 </body> 标签之前:
<script>
window.uj ||= new Proxy(
{},
{
get: (_, p) =>
p == 'then'
? 0
: (...a) => {
(window.$ujq ||= []).push([p, ...a]);
}
}
);
uj.init('YOUR_PROJECT_ID');
</script>
<script type="module" async src="https://cdn.userjot.com/sdk/v3/uj.js"></script>在 设置 → 登录 → 密钥 中找到 YOUR_PROJECT_ID(也可以从控制面板的 分享 页面复制已填好的代码片段)。加载完成后,启动器会显示在页面的右下角。
内嵌代码片段会设置一个 window.uj 代理,将即发即弃调用(init、open、close、toggle、identify、logout、setTheme、setLocale、destroy)排队,直到 SDK 加载完成,然后重新执行这些调用。
调用顺序无关紧要
在 SDK 完成加载前,你可以在同一个 tick 中将 init、identify 和 open 加入队列:
<script>
window.uj ||= new Proxy(
{},
{
get: (_, p) =>
p == 'then'
? 0
: (...a) => {
(window.$ujq ||= []).push([p, ...a]);
}
}
);
uj.init('YOUR_PROJECT_ID');
uj.identify({ user: { id: 'user-123', email: 'user@example.com' } });
</script>
<script type="module" async src="https://cdn.userjot.com/sdk/v3/uj.js"></script>预加载代理对每次调用都会返回 undefined。如果你需要返回值或 Promise,例如 await uj.identify(...)、uj.createEmbed(...)、uj.on(...) 或 uj.getState(),请等待 SDK 脚本加载完成后再调用。
不使用内联脚本(严格 CSP)
如果你的网站会阻止内联脚本,请使用带有 data-project 的单标签安装方式,让 SDK 自行初始化:
<script
type="module"
async
src="https://cdn.userjot.com/sdk/v3/uj.js"
data-project="YOUR_PROJECT_ID"
></script>脚本加载后,你仍然可以从自己的 bundle 中调用 window.uj 方法。如果你的代码也调用 uj.init(...),则以你显式调用的内容为准,优先于 data-project。
内容安全策略(CSP)指令
如果你的应用实施了内容安全策略,请允许以下 UserJot 来源:
script-src:https://cdn.userjot.comconnect-src:https://widget.userjot.com wss://widget.userjot.com https://collect.jotlens.com(SDK 会在非本地主机上向collect.jotlens.com发送轻量级的 widget 遥测信标)img-src:https://media.userjot.com(上传资源时还需添加https://cdn.userjot.com)style-src和font-src:https://cdn.userjot.com(字体由本站托管;无需允许 Google Fonts)如果使用 内嵌组件,请添加
frame-src:https://<your-workspace>.userjot.com(或你的自定义域名)
React、Next.js 和单页应用
在根布局中加载一次
https://cdn.userjot.com/sdk/v3/uj.js(例如,在 Next.js 中使用<Script strategy="afterInteractive" />,或在index.html中加载)。路由切换时不要重复注入 script 标签。在应用启动时调用一次
uj.init('YOUR_PROJECT_ID', ...),并在身份验证状态发生变化时调用uj.identify(...)/uj.logout()。在组件清理函数中(
useEffect返回时)清理所有uj.on(...)订阅和embed.destroy()句柄。
配置
将选项作为第二个参数传递给 init:
uj.init('YOUR_PROJECT_ID', {
widget: {
position: 'right', // 'left' or 'right'
theme: 'auto', // 'auto', 'light', or 'dark'
launcher: true // false hides the default button
},
locale: 'en-US' // optional override
});所有选项均为可选项。设置 launcher: false 后,即可通过自己的按钮打开 widget,而不是使用默认启动器。示例请参阅控制 widget。
验证安装
加载页面后:
启动器按钮会显示在配置的角落。
点击启动按钮即可打开小组件。
你可以在 widget 中浏览主页和反馈(启用后还包括路线图);如果启用了公开变更日志,还可以浏览更新。
如果帮助中心已上线,或已启用对话,则帮助和消息标签页会自动显示,无需修改脚本。
常见问题
小组件未显示
确认两个 script 标签都已存在(或者确认带有
data-project的单个标签已存在)。确认
YOUR_PROJECT_ID与设置 → 登录 → 密钥 中的值一致。确认你没有在
init中传入widget: false或launcher: false。检查浏览器控制台中是否有阻止
cdn.userjot.com或widget.userjot.com的内容安全策略错误。
调用似乎没有效果
如果调用 uj.open() 或 uj.identify(...) 没有任何效果,请确认页面上已运行 uj.init(...)。在 init 之前加入队列的调用会一直等待,直到 init 运行;如果仍有调用在没有 init 的情况下留在队列中,SDK 会在控制台记录警告。
下一步
请参阅识别用户,将 widget 与已登录用户关联。