Widget 安装

Shayan Taslim更新

安装 widget 只需一段代码。将它粘贴到 HTML 页面的靠近末尾处,也就是紧挨着闭合 </body> 标签之前:

HTML
<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 加入队列:

HTML
<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>
Note

预加载代理对每次调用都会返回 undefined。如果你需要返回值或 Promise,例如 await uj.identify(...)、uj.createEmbed(...)、uj.on(...) 或 uj.getState(),请等待 SDK 脚本加载完成后再调用。

不使用内联脚本(严格 CSP)

如果你的网站会阻止内联脚本,请使用带有 data-project 的单标签安装方式,让 SDK 自行初始化:

HTML
<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.com

  • connect-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:

JavaScript
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。

验证安装

加载页面后:

  1. 启动器按钮会显示在配置的角落。

  2. 点击启动按钮即可打开小组件。

  3. 你可以在 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 与已登录用户关联。

这是否解答了您的问题?