> 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.md).

# 身份验证

比较 Convai Unity SDK 的 API Key 和 Auth Token 身份验证模式，了解何时使用各自模式，以及玩家构建中包含什么。

从 Unity 项目到 Convai 的每个连接都需要一个凭据，以证明该项目被允许与 Convai 通信。Convai 的 Unity SDK 支持两种提供该凭据的方式：已保存的账户 API 密钥，或由您控制的服务器签发的短期令牌。本节将解释这两种模式，并展示如何为每种模式进行配置、扩展和排错。

### 两种身份验证模式

`ConvaiAuthMode` (`ApiKey = 0`, `AuthToken = 1`) 控制如何为一个 `ConvaiManager` 为每个房间连接解析凭据。

| 模式             | 凭据如何获取                                                   | 凭据存放位置                                 |
| -------------- | -------------------------------------------------------- | -------------------------------------- |
| **API 密钥**     | SDK 读取保存在 Convai Project Settings 中的账户 API 密钥。           | 存储在磁盘上的 `ConvaiSettings` 资源中，经过混淆但未加密。 |
| **Auth Token** | SDK 从已注册的 `IConvaiAuthTokenProvider`，或者从您配置的 HTTPS 端点获取。 | 仅在一次连接尝试期间保存在内存中；SDK 从不将其写入磁盘。         |

### 何时适合使用每种模式

使用 **API 密钥** 用于本地开发的模式：在 Unity 编辑器中迭代场景、运行示例场景，或在仅由您控制的机器上测试。它不需要您自己的服务器。

使用 **Auth Token** 适用于您发布的任何内容的模式：分发给测试人员、玩家或最终用户的构建。Auth Token 模式下的玩家构建绝不会包含账户 API 密钥——构建处理器会在构建期间将其剥离，并在之后恢复。API Key 模式下的玩家构建会位于随构建发布的 `ConvaiSettings` 资源。

{% hint style="warning" %}
混淆并不等于加密。任何拥有 SDK 源代码的人都可以还原存储的 API 密钥。不要将 API Key 模式的构建发布给您并不完全信任的受众。
{% endhint %}

### 玩家构建中会随附什么

| 使用……构建生成      | 构建中包含 API 密钥                   | 连接时解析凭据        |
| ------------- | ------------------------------ | -------------- |
| API Key 模式    | 是的，经过混淆，位于 `ConvaiSettings` 资源 | 直接从资源中读取       |
| Auth Token 模式 | 否——在构建前剥离，并在之后恢复               | 从您注册的提供程序或端点获取 |

### 选择一个页面

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>身份验证如何工作</strong><br>凭据解析顺序以及每种模式发送的传输标头。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/how-authentication-works.md">身份验证如何运作</a></td></tr><tr><td><strong>配置 Auth Token 模式</strong><br>切换到认证令牌模式，并在项目设置中配置令牌端点。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/configure-auth-token-mode.md">配置 Auth Token 模式</a></td></tr><tr><td><strong>编写自定义令牌提供器</strong><br>实现 IConvaiAuthTokenProvider，从您自己的登录流程中获取令牌。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/custom-token-provider.md">编写自定义令牌提供程序</a></td></tr><tr><td><strong>使用现有的身份验证令牌进行连接</strong><br>当您的登录层已经持有令牌时，请使用 ConnectWithAuthTokenAsync。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/connect-with-auth-token.md">使用现有身份验证令牌连接</a></td></tr><tr><td><strong>身份验证脚本参考</strong><br>身份验证的完整接口、注册表和设置说明。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/scripting-reference.md">身份验证脚本参考</a></td></tr><tr><td><strong>发布安全构建</strong><br>构建处理器会剥离什么，以及令牌端点所需的 WebGL CORS 要求。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/ship-a-secure-build.md">发布安全构建</a></td></tr><tr><td><strong>排查认证问题</strong><br>两种认证模式的控制台消息和错误代码。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/troubleshooting.md">身份验证故障排查</a></td></tr></tbody></table>

### 下一步

如果您正在配置第一个项目，请从 API 密钥开始。

{% content-ref url="/pages/3a95f57092cf5e9062d0377485e90f72b444fbd3" %}
[配置 API 密钥](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-api-key.md)
{% endcontent-ref %}

当您准备发布构建时，请先了解凭据解析的工作方式，再配置 Auth Token 模式。

{% content-ref url="/pages/389c46e269963976d61ff73772bc3d2f56baf7d3" %}
[身份验证如何运作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/how-authentication-works.md)
{% endcontent-ref %}


---

# 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.md?ask=<question>&goal=<endgoal>
```

`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.