最终用户身份

了解 SDK 如何为长期记忆范围识别用户，以及如何实现自定义的基于身份验证的身份提供程序。

每个长期记忆会话都需要一个稳定的 end_user_id —— SDK 会在每次连接时发送给 Convai 的一个字符串。Convai 使用它来限定存储的记忆范围：从对话中提取的事实会根据 end_user_id 是位于 character_id。如果标识符在会话之间发生变化，服务器会将用户视为新用户，并且不会沿用任何记忆。

SDK 提供 DeviceEndUserIdProvider 作为零配置默认值。对于带有用户身份验证的应用程序，您可以将其替换为一个返回您账户 ID 的自定义提供程序。

---

默认身份： DeviceEndUserIdProvider

DeviceEndUserIdProvider 同时实现了 IEndUserIdProvider 是位于 IEndUserIdentityProvider。它会自动注册——无需配置。

在 Unity 编辑器中： 始终读取或创建存储在 PlayerPrefs 中的 GUID，键为 "convai.end_user_id"。同一台机器上的每个 Play Mode 会话都会共享此 GUID，因此在开发和测试期间记忆会按预期累积。

在玩家构建中： 首先尝试 SystemInfo.deviceUniqueIdentifier。如果该值不可用、为空、等于 SystemInfo.unsupportedIdentifier，或者全部由零组成，则会回退到一个 PlayerPrefs GUID——仅生成一次，并在该设备后续所有会话中重复使用。

GUID 格式为不含连字符的 32 位十六进制字符串（例如： a1b2c3d4e5f6789012345678abcdef01）。您会在控制台日志中以及检查 EndUserDetails.EndUserId.

PlayerPrefs 无法在重新安装后保留。清除 PlayerPrefs 或重新安装应用程序会生成一个新的 GUID。Convai 会将新的 GUID 视为新用户——所有先前存储的记忆在新 ID 下都无法访问（不过它们仍保留在服务器上的旧 ID 下）。对于需要在重新安装后保持数据连续性的应用程序，请通过自定义提供程序使用服务器分配的账户 ID。请参见 实现自定义身份提供程序 下文。

---

Player ID 不是终端用户 ID

在 ConvaiPlayer 组件上设置 Player ID 并不会更改用于记忆范围划分的 end_user_id 所使用的标识符。 Player ID 仅控制本地玩家名称在转录和调试日志中的显示方式。记忆范围始终由 IEndUserIdentityProvider决定，而不是由 ConvaiPlayer.

---

实现自定义身份提供程序

如果您的应用程序对用户进行身份验证，请实现 IEndUserIdentityProvider 以返回一个稳定的、由服务器分配的账户标识符。这可确保记忆在不同设备和重新安装之间跟随同一用户。

实现该接口

using Convai.Domain.Identity;

public class AccountIdentityProvider : IEndUserIdentityProvider
{
    private readonly string _accountId;

    public AccountIdentityProvider(string accountId)
    {
        _accountId = accountId;
    }

    public string GetEndUserId()
    {
        return _accountId;
    }
}

请使用后端分配的账户 ID 作为标识符。不要使用电子邮件地址或显示名称——它们可能会变化，这会导致服务器将该用户视为新用户。

可选地附加元数据

实现 IEndUserMetadataProvider 以便在发送身份信息时附带显示信息。Convai 会将此元数据存储在 EndUserDetails.Metadata 并使用 "name" 键中，以便在编辑器的长期记忆面板中填充显示名称。

using System.Collections.Generic;
using Convai.Domain.Identity;

public class AccountMetadataProvider : IEndUserMetadataProvider
{
    private readonly string _displayName;
    private readonly string _department;

    public AccountMetadataProvider(string displayName, string department)
    {
        _displayName = displayName;
        _department = department;
    }

    public IReadOnlyDictionary<string, object> GetEndUserMetadata()
    {
        return new Dictionary<string, object>
        {
            { "name", _displayName },
            { "department", _department }
        };
    }
}

在首次连接前注册

调用 SetEndUserIdentityProvider 是位于 SetEndUserMetadataProvider on ConvaiManager 在首次会话连接之前。如果 ConvaiCharacter 具有 自动连接 已启用，连接会在以下操作后立即开始 ConvaiRoomManager.Start() 完成——请在 Awake()，而不是 Start()中注册您的提供程序，以保证顺序正确。

using Convai.Runtime.Components;
using UnityEngine;

public class IdentityRegistrar : MonoBehaviour
{
    [SerializeField] private ConvaiManager _convaiManager;

    private void Awake()
    {
        // 在 ConvaiRoomManager.Start() 之前调用——适用于自动连接角色
        string accountId = AuthService.CurrentUser.AccountId;
        string displayName = AuthService.CurrentUser.DisplayName;
        string department = AuthService.CurrentUser.Department;

        _convaiManager.SetEndUserIdentityProvider(new AccountIdentityProvider(accountId));
        _convaiManager.SetEndUserMetadataProvider(new AccountMetadataProvider(displayName, department));
    }
}

如果您调用 SetEndUserIdentityProvider 在 ConnectAsync 如果当前会话已经调用过，则提供程序更改不会影响当前活动连接。新的提供程序将从下一次 ConnectAsync 调用开始生效。请始终在连接前注册。

---

空的或仅包含空白字符的终端用户 ID

如果 GetEndUserId() 返回空字符串、仅包含空白字符的字符串，或者 nullnull null 在发送前。Convai 会将 null 视为匿名会话—— 不会存储或检索任何记忆。请始终确保您的身份来源返回非空且不含空白字符的值。

---

身份来源对比

场景	推荐来源	重新安装后仍保留	更换设备后仍保留
开发 / 测试	DeviceEndUserIdProvider （默认）	没有	没有
消费者应用，无账户	DeviceEndUserIdProvider （默认）	没有	没有
带账户的消费者应用	自定义提供程序 → 服务器账户 ID	是	是
企业 / 培训平台	自定义提供程序 → 服务器账户 ID	是	是

---

下一步

管理最终用户记录记忆管理 API