> 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` 资源中，经过混淆但未加密。 |
| **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>切换到 Auth Token 模式，并在项目设置中配置令牌端点。</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 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.