> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/how-authentication-works.md). # 身份验证如何运作 了解 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。` ```mermaid sequenceDiagram 参与者 Manager 作为 ConvaiManager 参与者 Credential 作为 AuthTokenCredentialProvider 参与者 Provider 作为 IConvaiAuthTokenProvider 参与者 Endpoint 作为 已配置的端点 参与者 Convai Manager->>Credential: EnsureCredentialsAsync alt 为此连接设置了显式令牌 Credential->>Credential: 消耗显式令牌 else 已注册提供程序 Credential->>Provider: GetTokenAsync Provider-->>Credential: AuthTokenResult else 未注册提供程序 Credential->>Endpoint: 请求令牌 Endpoint-->>Credential: apiAuthToken end Credential-->>Manager: 解析出的令牌 Manager->>Convai: 使用 API-AUTH-TOKEN 标头进行连接 ``` 在 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 中配置端点。		配置 Auth Token 模式
编写自定义令牌提供器
为每个玩家的令牌注册一个 IConvaiAuthTokenProvider。		编写自定义令牌提供程序
使用现有的身份验证令牌进行连接
使用一次性的 ConnectWithAuthTokenAsync 路径。		使用现有身份验证令牌连接
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/how-authentication-works.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.