身份验证脚本参考

Convai Unity SDK 身份验证 API 参考，包括 token 提供器接口、注册表和设置访问器。

Convai Unity SDK 中公共身份验证接口的完整 API 参考。类型位于 Convai.Runtime.Core.Configuration 命名空间，除非另有说明。

IConvaiAuthTokenProvider

Convai.Runtime.Core.Configuration — 接口

为 Convai 运行时连接解析一个短期凭证。在任何类上实现此接口，以便从你自己的后端提供令牌。

public interface IConvaiAuthTokenProvider
{
    Task<AuthTokenResult> GetTokenAsync(CancellationToken cancellationToken);
}

方法

方法	签名	描述
GetTokenAsync	Task<AuthTokenResult> GetTokenAsync(CancellationToken cancellationToken)	解析一个新的身份验证令牌。每次新的房间连接尝试都会调用一次；SDK 不会在连接之间缓存结果。

实现不得记录或持久化返回的令牌。

AuthTokenResult

Convai.Runtime.Core.Configuration — 只读结构体

由以下方法返回的结果 IConvaiAuthTokenProvider.GetTokenAsync.

属性

属性	类型	描述
IsSuccess	bool	true 时自动连接， Token 已成功解析。
Token	string	已解析的身份验证令牌。若 IsSuccess 为 false.
ExpiresAtUtc	DateTimeOffset?	令牌的可选过期时间，已标准化为 UTC。 null 如果未提供则为空。
错误消息	string	失败原因。若 IsSuccess 为 true.

工厂方法

方法	签名	在以下情况下使用
Succeeded	static AuthTokenResult Succeeded(string token, DateTimeOffset? expiresAtUtc = null)	已解析出令牌。
Failed	static AuthTokenResult Failed(string errorMessage)	令牌解析失败。

ConvaiAuthTokenProviderRegistry

Convai.Runtime.Core.Configuration — 静态类

进程本地的开发者提供的 IConvaiAuthTokenProvider的注册点。在第一次连接尝试之前注册提供器。

属性

属性	类型	描述
IsRegistered	bool	true 当当前注册的是自定义提供器时。

方法

方法	签名	描述
Register	static void Register(IConvaiAuthTokenProvider provider)	注册或替换活动提供器。抛出 ArgumentNullException 如果 provider 为 null.
Unregister	static bool Unregister(IConvaiAuthTokenProvider provider)	取消注册 provider 仅当它仍然是活动注册项时。返回 true 当已移除时。
Unregister	static void Unregister()	取消当前活动的提供器注册。
清除	static void Clear()	清除当前注册。

注册表会在 RuntimeInitializeLoadType.SubsystemRegistration时自动重置，这会在每次域重载以及每次进入 Play 模式时运行。请在每次此类重载后重新注册提供器，而不要依赖一次性的启动调用。

DelegateAuthTokenProvider

Convai.Runtime.Core.Configuration — 实现 IConvaiAuthTokenProvider

的密封类

构造函数

构造函数	签名	描述
DelegateAuthTokenProvider	将开发者提供的异步委托适配为提供器，适用于不需要专门类的情况。	DelegateAuthTokenProvider(Func<CancellationToken, Task<string>> getTokenAsync) 包装，它会在每次 GetTokenAsync 调用时被调用一次。抛出 ArgumentNullException 如果 包装 为 null.

GetTokenAsync 返回 AuthTokenResult.Failed 当委托返回 null、空任务或 null仅空白字符串时；否则返回 AuthTokenResult.Succeeded 以及修剪后的令牌。

ConvaiAuthMode

Convai.Runtime.Core.Configuration — 枚举

用于运行时 Convai 房间连接的身份验证策略。

值	Integer	描述
ApiKey	0	从 ConvaiSettings读取账户 API 密钥。默认。
AuthToken	1	从已注册的提供器或已配置的端点解析短期身份验证令牌。

ConvaiAuthTokenHttpMethod

Convai.Runtime.Core.Configuration — 枚举

配置的 Auth Token 模式端点使用的 HTTP 方法（在 Project Settings > Convai SDK > Credentials).

值	Integer	描述
Get	0	发送一个 HTTP GET 请求，不带请求体。默认。
Post	1	发送一个 HTTP POST 请求，带一个空 JSON 对象请求体。

ConvaiAuthTokenHeader

Convai.Runtime.Core.Configuration — 可序列化结构体

发送到 Auth Token 模式端点的单个静态 HTTP 头名称/值对。

属性

属性	类型	描述
Name	string	头名称。绝不 null.
值	string	头值。绝不 null.

构造函数

构造函数	签名	描述
ConvaiAuthTokenHeader	ConvaiAuthTokenHeader(string name, string value)	创建一个头对。 null 参数会被规范化为空字符串。

ConvaiManager.ConnectWithAuthTokenAsync

Convai.Runtime.Components

使用显式提供的身份验证令牌进行连接，而不是使用已注册的提供器或端点。用法请参见 使用现有的身份验证令牌进行连接 。

public IConvaiOperation<RoomSession> ConnectWithAuthTokenAsync(
    string authToken,
    string endUserId,
    string endUserName,
    CancellationToken cancellationToken = default)

参数	类型	描述
authToken	string	必需。仅用于此次连接的 Convai 身份验证令牌。
endUserId	string	必需。作为 end_user_id.
endUserName	string	必需。作为 end_user_metadata.name.
cancellationToken	CancellationToken	取消挂起的连接尝试。默认为 default.

返回 IConvaiOperation<RoomSession>.

下面的每个失败都带有一个 ConvaiOperationException，以及你如何接收它取决于你如何调用该方法。等待该操作会重新抛出异常，因此在 try/catch 周围的 await 处理所有情况。如果你不想捕获异常，则不要 await，而是保留该操作，并在 IsSuccessful, HasError，以及 错误 之后读取 IsCompleted 为 true 时 — 错误 携带相同的代码和消息。

错误

错误代码	消息	原因
ConnectionInvalidToken	需要非空的 Convai 身份验证令牌。	authToken 为空或仅包含空白字符。
ConnectionBadRequest	需要非空的终端用户 ID。	endUserId 为空或仅包含空白字符。
ConnectionBadRequest	需要非空的终端用户名称。	endUserName 为空或仅包含空白字符。
ConnectionFailed	ConvaiRoomManager 不可用。	管理器对象上不存在房间管理器。
ConfigAuthTokenModeRequired	显式的身份验证令牌连接需要在 Convai 项目设置中启用 Auth Token 模式。	项目的身份验证模式是 ConvaiAuthMode.ApiKey.
ConnectionInvalidToken	连接令牌无效	Convai 拒绝了所提供的令牌。

前四种错误会在任何网络工作开始之前抛出；最后两种会在连接尝试期间抛出。两者都会以相同方式返回给调用方。

ConvaiSettings 身份验证访问器

Convai.Runtime — 项目保存的 ConvaiSettings 资源，可通过 编辑 > 项目设置 > Convai SDK.

属性

属性	类型	描述
AuthMode	ConvaiAuthMode	项目配置的身份验证模式。
AuthTokenEndpointUrl	string	已配置的 Auth Token 模式端点 URL，已去除首尾空白。若未配置则为空。
AuthTokenHttpMethod	ConvaiAuthTokenHttpMethod	调用已配置端点时使用的 HTTP 方法。
AuthTokenResponseField	string	端点响应中包含已解析令牌的 JSON 字段或点式字段路径。默认为 apiAuthToken ，当未设置时。
AuthTokenHeaders	ConvaiAuthTokenHeader[]	发送到已配置端点的静态头。若未配置则为空数组。
HasValidAuthConfig	bool	true 当所选模式具备足够的配置可尝试连接时：对于 ApiKey，已存在 API 密钥；对于 AuthToken，已在 ConvaiAuthTokenProviderRegistry 中注册提供器，或者已配置有效的端点 URL。

端点 URL 验证——需要 HTTPS，但本地开发期间对 HTTP 回环地址除外——会在 SDK 从已配置端点解析令牌时内部应用。你的代码中没有可公开调用的方法来执行该检查；请改为读取 HasValidAuthConfig ，以确认项目具有足够的配置来连接。

下一步

编写自定义 token 提供器使用现有 auth token 连接身份验证故障排查