身份验证如何工作

了解 Convai Unity SDK 遵循的凭据解析顺序，以及每种身份验证模式发送的传输头。

Convai SDK for Unity 会在每次房间连接尝试时重新解析凭据——它不会在连接之间缓存令牌。了解解析顺序有助于你决定是注册提供程序、配置端点，还是显式传入令牌。

凭据解析顺序

在 Auth Token 模式下， AuthTokenCredentialProvider.EnsureCredentialsAsync 每次连接尝试运行一次，并按以下顺序检查三个来源：

1. 一个一次性显式令牌。 如果当前连接是使用 ConvaiManager.ConnectWithAuthTokenAsync启动的，SDK 会使用该令牌并跳过另外两个来源。
2. 一个已注册的 IConvaiAuthTokenProvider. 如果未提供显式令牌，SDK 会检查 ConvaiAuthTokenProviderRegistry 中是否有提供程序，并调用其 GetTokenAsync 。
3. 在 Project Settings 中配置的端点。 如果没有注册提供程序，SDK 会回退到 EndpointAuthTokenProvider，它由以下配置构建： 令牌端点 URL, HTTP 方法, 令牌响应字段，以及 请求头 ，保存在 编辑 > 项目设置 > Convai SDK.

如果这三个来源都没有得到令牌，连接将失败并报错 Auth Token 模式需要已注册的 IConvaiAuthTokenProvider 或已配置的端点 URL。

在 API Key 模式下，解析更简单： ProjectSettingsCredentialProvider 直接从已保存的 ConvaiSettings asset 中读取账户 API 密钥。这里不涉及提供程序、端点或每次连接的网络调用。

哪种来源适用于你的集成

你的情况	适用来源
你的登录层在连接前已经持有一个 Convai 身份验证令牌	通过 ConnectWithAuthTokenAsync
你希望为每个玩家提供与你自己的登录系统关联的令牌	一个已注册的 IConvaiAuthTokenProvider
你的令牌端点接受未认证请求，或者你正在做原型开发	在 Project Settings 中配置的端点

当同一次连接尝试同时存在显式令牌和已注册提供程序时，显式令牌始终优先生效——这种情况下不会查询提供程序。

每种模式的传输标头

SDK 发送给 Convai 的标头因身份验证模式而异，而不是因平台而异：

模式	标头名称
API 密钥	X-API-Key
Auth Token	API-AUTH-TOKEN

TransportAuthenticationSupport.GetHeaderName 会从当前活动的 ITransportConfiguration中选择标头。Native 和 WebGL 房间控制器调用的是相同的选择逻辑，因此两个平台上的标头名称和身份验证模式处理都是一致的——无需考虑 WebGL 特有的标头变体。

仅限编辑器的回退

当选择 Auth Token 模式、已保存 API 密钥且未配置端点或提供程序时，编辑器会直接向 Convai 交换已保存的 API 密钥以获取令牌。此回退仅存在于 ConvaiEditorApiKeyAuthTokenProvider中，这是一个仅编辑器程序集类型，永远不会编译进玩家构建——在 Auth Token 模式下，已发布构建始终依赖真实的提供程序或端点，绝不依赖此回退。

下一步

配置 Auth Token 模式 切换模式并在 Project Settings 中配置端点。

编写自定义令牌提供器 为每个玩家的令牌注册一个 IConvaiAuthTokenProvider。

使用现有的身份验证令牌进行连接 使用一次性的 ConnectWithAuthTokenAsync 路径。