识别用户
默认情况下,组件会将访客视为匿名用户。调用 uj.identify 可将反馈、投票、评论、通知和对话关联到客户的账户。
基本识别
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():
if (user) {
uj.identify({
user: {
id: user.id,
email: user.email,
firstName: user.firstName,
lastName: user.lastName
}
});
} else {
uj.logout();
}添加特征
属性是附加到成员个人资料的自定义属性,会显示在控制面板中的请求和对话旁边。
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 产品,可以为用户关联一个或多个公司:
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:
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 在服务器端验证账户。
我应该使用哪种身份验证方式?
方式 | 适用场景 | 安全性 | 套餐 | 指南 |
|---|---|---|---|---|
未签名( | 应用内小组件 | 由浏览器提供(可能被伪造) | 所有套餐 | 本文 |
签名身份(HS256 JWT) | 应用内小组件(启用 Automatic login 时,也可通过链接访问公开门户) | 服务器验证的 JWT | Starter 和 Professional(用于严格模式) | |
自动登录 | 公开门户和内嵌内容( | 服务器验证的 HS256 JWT | Starter 和 Professional | |
单点登录(SSO) | 公开门户登录重定向 | 服务器验证的 HS256 JWT | Professional | |
Swift SDK( | iOS 和 macOS 应用 | 未签名或 HMAC-SHA256 签名 | Starter 和 Professional(需要启用 Automatic login) |
下一步
在 签名身份 中,从后端验证用户身份。