初始化身份参数说明

1. email 与 account

email 与 account 的本质相同：都是微吼系统与接入方业务系统之间打通用户身份、用于标识用户的字段，不是昵称、头像一类的展示资料。

两者必须且只能传一个，不能同时传，也不能都不传。

推荐使用 email 作为系统间用户唯一标识：它不需要在微吼侧预创建用户，因此用户信息不必在两个系统之间提前预置。email 只承担标识作用，不要求客户系统确实存在用户邮箱字段，可以使用“业务用户 ID + 固定域名”拼装，例如 88888@xxxx.com。

使用 account 时，必须先在业务后端调用创建三方用户接口完成预创建；初始化小程序 SDK 时，微吼侧必须已存在该用户 ID，否则初始化不会成功。

两者都参与服务端签名，前端初始化与服务端签名必须使用同一个字段、同一个值。

2. 参数定义

email 与 account 的本质相同：都是微吼系统与接入方业务系统之间用于打通用户身份、完成用户识别与数据归属的标识字段。它们不是展示资料，也不承担登录密码等凭证的作用。真正的区别只有两点：身份来自哪里，以及是否需要提前在微吼侧建立用户。

2.1 email（跨系统用户唯一标识）

这里需要特别澄清：email 的职责是“标识”，不是“通讯邮箱地址”。

客户系统本来就有真实邮箱时，可以直接使用该邮箱，来标识用户唯一；

客户系统没有邮箱字段时，也可以按固定规则拼装一个邮箱格式的标识，例如业务用户 ID 为 88888，拼装为 88888@xxxx.com；

拼装值不要求真实可收信，但必须是稳定的映射：同一个用户在每次初始化时都应得到相同的 email；

不要使用随机数、时间戳或会话 ID 拼装邮箱，否则同一用户会被识别成多个不同身份；

建议将 xxxx.com 替换为接入方统一约定的固定域名，并把映射规则沉淀到用户标识服务中。

拼装后的邮箱总长度不要超过50字符。

email 只负责身份识别，用户在直播间展示的昵称仍由 username 单独传入，头像仍由 head 单独传入。

2.2 account（三方用户 ID）

account 与 email 最大的区别是：它不是“即传即用”，而是要求两个系统先完成用户打通。 这一前置步骤包括：

业务后端调用微吼创建三方用户接口；

微吼返回用户注册信息；

业务后端持久化保存业务用户与三方用户 ID 的映射；

小程序初始化 SDK 时，传入已存在的三方用户 ID。

如果跳过预创建，或传入了一个微吼侧不存在的ID，SDK 初始化不会成功。

这里的 account 按文档定义应填你方系统内的用户唯一标识，也就是调用创建接口时提交的 third_user_id 对应的值。

2.3 对照表

维度	`email`	`account`
身份来源	以邮箱格式承载的跨系统用户标识	接入方自有用户体系中的用户 ID
典型值	`88888@xxxx.com`（可由业务 ID 拼装）	`88888`（创建时的 `third_user_id`）
是否需要预先创建	不需要	必须：后端先调用创建三方用户接口
初始化成功前提	提供唯一、稳定的邮箱格式标识	微吼侧已存在该三方用户 ID

3. 如何选择

优先使用 email（推荐）：

希望系统之间不预置用户资料，以最低耦合完成身份打通；

客户系统没有邮箱字段，也可以按固定规则拼装邮箱格式标识，例如 88888@xxxx.com；

不希望为每位用户额外调用创建三方用户接口，减少接入和运维成本；

可以接受邮箱身份没有默认头像，需要头像时另行传入 head。

email 模式时序：

email 模式无需预创建用户，链路更短。

使用 account：

已经在微吼侧建立了三方用户，或需要以自有用户 ID 关联聊天、问卷等导出数据；

已有稳定的用户体系，愿意维护“业务用户 ID ↔ 三方用户 ID”的映射；

需要将小程序、Web 等多端的用户身份统一到同一个三方用户上；

能够确保每次初始化前该用户 ID 已在微吼侧存在。

account 模式时序：

account 模式必须先完成用户打通，且初始化时该用户 ID 必须已存在。

总结：account 多一步“先创建、后使用”，email 可以直接使用，不需要预置用户。

两种模式的共同要求：

身份标识必须唯一且稳定。同一个业务用户每次进入直播间，生成的 email 或 account 必须一致；

只能传一个身份字段，另一个必须删除，不能留空字符串，也不能传 null 占位；

身份字段参与签名，确定后不要在前端临时替换。

不建议的用法：

同时传 email 和 account，违反互斥约束；

两个都不传，初始化时缺少用户身份；

使用 account 但未预创建，或传入微吼内部 user_id，会导致初始化失败；

用邮箱作为 account 的值来“兼容”两种模式，这不会带来兼容收益，反而会让身份归属混乱；

每次进入都随机拼装不同的 email，会把同一用户拆成多个身份。

4. 参考文档

快速接入

签名鉴权说明

创建三方用户

身份参数说明

初始化身份参数说明#

1. email 与 account#

2. 参数定义#

2.1 email（跨系统用户唯一标识）#

2.2 account（三方用户 ID）#

2.3 对照表#

3. 如何选择#

4. 参考文档#