> 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 项目设置中的账户 API 密钥。                                | 存储在磁盘上的 `ConvaiSettings` 资源中，经过混淆但未加密。 |
| **身份验证令牌** | SDK 会从已注册的 `IConvaiAuthTokenProvider`中解析短期令牌，或从你配置的 HTTPS 端点获取令牌。 | 仅在单次连接尝试期间保存在内存中；SDK 绝不会将其写入磁盘。        |

### 何时适合使用各模式

在本地开发时使用 **API 密钥** 模式：例如在 Unity Editor 中迭代场景、运行示例场景，或在仅由你控制的设备上测试。此模式无需自建服务器。

发布任何内容时使用 **身份验证令牌** 模式：例如分发给测试人员、玩家或最终用户的构建版本。采用身份验证令牌模式的玩家构建版本绝不会包含账户 API 密钥——构建处理器会在构建期间将其移除，并在之后恢复。采用 API 密钥模式的玩家构建版本则会在随附的 `ConvaiSettings` 资源中包含账户密钥，该密钥经过可逆加密混淆。

{% hint style="warning" %}
混淆不等于加密。任何拥有 SDK 源代码的人都可以还原存储的 API 密钥。请勿向你无法完全信任的用户群发布采用 API 密钥模式的构建版本。
{% endhint %}

### 玩家构建版本中包含的内容

| 构建版本采用的模式 | 构建版本中是否包含 API 密钥                  | 连接时解析的凭据       |
| --------- | --------------------------------- | -------------- |
| API 密钥模式  | 是，密钥经过混淆并存储在 `ConvaiSettings` 资源中 | 直接从资源中读取       |
| 身份验证令牌模式  | 否——构建前移除，构建后恢复                    | 从已注册的提供程序或端点获取 |

### 选择页面

<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="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/how-authentication-works.md">身份验证如何运作</a></td></tr><tr><td><strong>配置身份验证令牌模式</strong><br>切换到身份验证令牌模式，并在项目设置中配置令牌端点。</td><td><a href="https://docs.convai.com/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="https://docs.convai.com/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="https://docs.convai.com/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="https://docs.convai.com/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="https://docs.convai.com/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="https://docs.convai.com/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 密钥](https://docs.convai.com/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" %}
[身份验证如何运作](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
