识别用户

Shayan Taslim更新

默认情况下,组件会将访客视为匿名用户。调用 uj.identify 可将反馈、投票、评论、通知和对话关联到客户的账户。

基本识别

JavaScript
uj.identify({
  user: {
    id: 'user-123',
    email: 'ada@example.com',
    firstName: 'Ada',
    lastName: 'Lovelace',
    avatar: 'https://example.com/avatar.jpg'
  }
});

user.id 为必填项。请使用数据库中的稳定 ID,而不要使用可能会更改的电子邮件地址或显示名称。email 为可选项,但强烈建议提供,以便 UserJot 能在看板、电子邮件转发和对话中识别同一用户。传入 email 只会关联到电子邮件地址已确认的现有 UserJot 账户。

何时调用 identify

应用确定用户已登录后,调用 uj.identify。只要会话仍有效,使用完全相同的载荷再次调用就不会执行任何操作。会话过期后,或任何字段(包括电子邮件或属性)发生变化时,SDK 都会发送新请求。传入其他用户会立即切换会话。

用户退出应用时,请调用 uj.logout():

JavaScript
if (user) {
  uj.identify({
    user: {
      id: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName
    }
  });
} else {
  uj.logout();
}

添加特征

属性是附加到成员个人资料的自定义属性,会显示在控制面板中的请求和对话旁边。

JavaScript
uj.identify({
  user: {
    id: 'user-123',
    email: 'ada@example.com',
    traits: {
      plan: 'pro',
      seats: 12,
      trialing: false
    }
  }
});

特征值可以是字符串、数字、布尔值或 null(发送 monthlySpend 时,该值必须是非负数)。保留键(例如 id、email、role 或 companies)会被忽略,并在 result.warnings 中报告。请参阅 SDK 参考中的完整列表。

添加公司

对于 B2B 产品,可以为用户关联一个或多个公司:

JavaScript
uj.identify({
  user: { id: 'user-123', email: 'ada@example.com' },
  companies: [
    {
      id: 'acme',
      name: 'ACME Inc.',
      domain: 'acme.com',
      logo: 'https://acme.com/logo.png',
      traits: { plan: 'enterprise', arr: 24000 }
    }
  ]
});

每家公司都必须提供 id。name、domain、logo(HTTPS URL)和 traits 均为可选项。如果在 设置 → 登录中启用了 要求使用已签名令牌,则会忽略通过已签名 JWT 以外的方式传入的公司信息,并显示 UNSIGNED_COMPANY_IGNORED 警告。

identify 的返回值

SDK 脚本加载后,uj.identify 会返回一个 promise:

JavaScript
const result = await uj.identify({
  user: { id: 'user-123', email: 'ada@example.com' }
});

result.viewer;        // the identified user, or null
result.identityTrust; // 'signed' or 'unsigned'
result.warnings;      // fields the server ignored or adjusted

速率限制与错误

  • 速率限制和客户端退避:Identify 请求按 IP 地址和工作区进行限制,每分钟最多 30 次,每小时最多 300 次。超过每小时限制将触发 1 小时的封锁。收到 HTTP 429 后,SDK 会强制执行本地冷却时间(遵循 Retry-After,并限制在 1 秒至 1 小时之间;默认值为 60 秒),这样重试循环会在本地失败,而不会向 API 发送大量请求。

  • 被拒绝的调用:如果服务器拒绝身份识别调用(例如令牌无效、启用了 Require signed tokens 但未提供令牌、电子邮件冲突并返回 409,或已通过 GDPR 删除的成员返回 403 / member_erased),promise 会以 IDENTIFY_FAILED 拒绝,访问者仍保持匿名状态。

身份与对话

启用 Conversations 后:

  • 已识别的用户无需填写访问者详细信息提示,并会在其账户电子邮件中收到团队回复。

  • 匿名访问者会获得仅限当前浏览器的访客对话;是否收集联系方式取决于小组件设置。

在组件中,匿名访客可以提交反馈并对更新作出回应;但要为反馈点赞、发表评论以及打开通知铃铛,则必须调用 uj.identify。要在组件中编辑或删除自己的帖子和评论,则需要使用 已签名身份。

如果在 Settings → Login 中启用了 Require signed tokens,未签名的 identify 调用会被拒绝,并返回 HTTP 403,访问者也会保持匿名状态。请使用 Signed identity 在服务器端验证账户。

我应该使用哪种身份验证方式?

方式

适用场景

安全性

套餐

指南

未签名(uj.identify)

应用内小组件

由浏览器提供(可能被伪造)

所有套餐

本文

签名身份(HS256 JWT)

应用内小组件(启用 Automatic login 时,也可通过链接访问公开门户)

服务器验证的 JWT

Starter 和 Professional(用于严格模式)

签名身份

自动登录

公开门户和内嵌内容(?token=...)

服务器验证的 HS256 JWT

Starter 和 Professional

自动登录

单点登录(SSO)

公开门户登录重定向

服务器验证的 HS256 JWT

Professional

单点登录

Swift SDK(identify)

iOS 和 macOS 应用

未签名或 HMAC-SHA256 签名

Starter 和 Professional(需要启用 Automatic login)

Swift SDK 身份验证

下一步

在 签名身份 中,从后端验证用户身份。

这是否解答了您的问题?