自定义凭据提供程序

覆盖 SDK 的默认凭据来源，以便从环境变量、密钥保险库或任何运行时解析的凭据存储中提供 API 密钥。

默认情况下，Convai Unity SDK 会从以下位置读取 API 密钥和服务器 URL： ConvaiSettings.asset，存储于 Assets/Resources/。某些部署场景要求凭据来自其他位置——例如 CI 环境变量、secrets 管理器、按租户配置的服务，或提供短期令牌的后端。

先决条件

• 一个可工作的 Convai 场景，且其中有一个 ConvaiManager 组件位于某个 GameObject 上
• 所有示例都会创建以下类的子类： ConvaiManager ——将这个新组件添加到同一个 GameObject 上，并移除原始的 ConvaiManager 组件

如果你还没有搭建场景，请先查看 入门指南 。

凭据如何在 SDK 中传递

当运行时构建时， ConvaiBootstrapConfigSnapshot 会将 API 密钥和服务器 URL 作为一个不可变的配对进行捕获。一旦构建完成，这些值会通过以下方式暴露给模块和内部服务： ICredentialProvider:

public interface ICredentialProvider
{
    bool HasValidCredentials { get; }
    string GetApiKey();
    string GetServerUrl();
    void Refresh();
}

GetApiKey() 是位于 GetServerUrl() 会在连接时被调用——不是每一帧都调用。 HasValidCredentials 用于控制连接尝试：如果它返回 false，SDK 将不会尝试连接。 Refresh() 会在 SDK 检测到与凭据相关的错误，并希望提供者从其来源重新加载时被调用。

你不需要直接实现 ICredentialProvider 。你在构建运行时时提供凭据值，而 SDK 会根据这些值在内部创建提供者。

提供自定义凭据

重写 CreateRuntimeBuilder() 在一个 ConvaiManager 子类中，并调用 builder.UseConfig() ，其参数为从你的凭据来源构造的 ConvaiBootstrapConfigSnapshot 。务必先调用 base.CreateRuntimeBuilder() ——它会处理平台相关的传输选择、事件系统设置以及其他你无需复制的连接工作。随后调用 UseConfig() 只会覆盖凭据快照。

// EnvironmentCredentialManager.cs
using Convai.Runtime.Components;
using Convai.Runtime.Core;
using Convai.Runtime.Core.Configuration;
using UnityEngine;

public class EnvironmentCredentialManager : ConvaiManager
{
    protected override ConvaiRuntimeBuilder CreateRuntimeBuilder()
    {
        ConvaiRuntimeBuilder builder = base.CreateRuntimeBuilder();

        string apiKey    = ResolveApiKey();
        string serverUrl = ResolveServerUrl();

        if (string.IsNullOrEmpty(apiKey))
        {
            Debug.LogError("[EnvironmentCredentialManager] 未找到 API 密钥。" +
                           "请检查你的环境或 secrets 配置。");
        }

        builder.UseConfig(new ConvaiBootstrapConfigSnapshot(
            apiKey:    apiKey,
            serverUrl: serverUrl
        ));

        return builder;
    }

    private static string ResolveApiKey()
    {
        // 从环境变量读取（CI、Docker、云运行）。
        string key = System.Environment.GetEnvironmentVariable("CONVAI_API_KEY");
        if (!string.IsNullOrEmpty(key)) return key;

        // 回退到 ConvaiSettings（编辑器 / 本地开发）。
        return ConvaiSettings.Instance?.ApiKey ?? string.Empty;
    }

    private static string ResolveServerUrl()
    {
        return System.Environment.GetEnvironmentVariable("CONVAI_SERVER_URL")
               ?? ConvaiSettings.Instance?.ServerUrl
               ?? "https://live.convai.com";
    }
}

在你的 Hierarchy 中，找到带有 ConvaiManager 的 GameObject。添加 EnvironmentCredentialManager 作为新组件，然后移除原始的 ConvaiManager 组件。该子类继承了所有 ConvaiManager 功能——场景中的其他内容都不需要改变。

ConvaiBootstrapConfigSnapshot 参数

ConvaiBootstrapConfigSnapshot 是不可变的——所有值都在构造时设置，并且在运行时启动后不能再更改。

参数	类型	默认值	描述
apiKey	string	—	必需。 你的 Convai API 密钥。
serverUrl	string	—	必需。 Convai 实时服务器 URL。
connectionType	ConvaiConnectionType	音频	是仅连接音频，还是连接音频 + 视频。
serverEndpoint	ConvaiServerEndpoint	连接	服务器端点变体。除非另有指示，否则保持默认值。
connectionTimeoutSeconds	float	30f	连接尝试被视为失败之前的超时时间。
globalLogLevel	LogLevel	信息	初始 SDK 日志级别。可在运行时通过以下方式更改： ConvaiSettings.
enableSessionResume	bool	true	SDK 是否应尝试恢复之前的会话。
maxRetryAttempts	int	3	放弃之前的最大重连尝试次数。

ConvaiBootstrapConfigSnapshot 会在启动时被捕获。如果你的凭据来源发放的是短期令牌，SDK 无法在会话进行中自动轮换它们。请设计你的令牌生命周期长于最长预期会话，或者断开并重新连接以应用刷新后的令牌。

切勿将你的 API 密钥记录或序列化到 Unity 的 Console 或日志文件中。 ConvaiBootstrapConfigSnapshot 有意从其 ToString() 输出中省略了 API 密钥。

使用示例

示例 1：带本地回退的环境变量

如上所示于 提供自定义凭据。最适合 CI/CD 流水线和基于 Docker 的部署，其中 secrets 以环境变量形式注入。

示例 2：启动前从 secrets vault 获取

某些部署会在启动时从 secrets 服务拉取凭据。因为 ConvaiBootstrapConfigSnapshot 必须在以下调用之前就绪： ConvaiManager.Awake() 调用 BuildRuntime()，所以必须在 base.Awake() 运行之前异步获取凭据。

// VaultCredentialManager.cs
using System.Threading.Tasks;
using Convai.Runtime.Components;
using Convai.Runtime.Core;
using Convai.Runtime.Core.Configuration;
using UnityEngine;

public class VaultCredentialManager : ConvaiManager
{
    [SerializeField] private string _vaultEndpoint = "https://vault.internal/v1/convai";

    private string _resolvedApiKey;
    private string _resolvedServerUrl = "https://live.convai.com";

    protected override async void Awake()
    {
        await FetchCredentialsAsync();
        base.Awake(); // 使用已解析的凭据触发 BuildRuntime() → CreateRuntimeBuilder()。
    }

    private async Task FetchCredentialsAsync()
    {
        using var client = new System.Net.Http.HttpClient();
        try
        {
            string json = await client.GetStringAsync(_vaultEndpoint);
            var response = JsonUtility.FromJson<VaultResponse>(json);
            _resolvedApiKey = response.ApiKey;
        }
        catch (System.Exception ex)
        {
            Debug.LogError($"[VaultCredentialManager] 获取凭据失败：{ex.Message}");
        }
    }

    protected override ConvaiRuntimeBuilder CreateRuntimeBuilder()
    {
        ConvaiRuntimeBuilder builder = base.CreateRuntimeBuilder();
        builder.UseConfig(new ConvaiBootstrapConfigSnapshot(_resolvedApiKey, _resolvedServerUrl));
        return builder;
    }

    [System.Serializable]
    private class VaultResponse { public string ApiKey; }
}

base.Awake() 会在凭据获取完成后显式调用。其他 Awake() 方法中任何依赖于 ConvaiManager.ActiveManager 已就绪的代码都必须改用 Start() 或更后面的阶段。

示例 3：来自配置服务的按租户凭据

对于多租户部署，每个客户都有不同 API 密钥，可以在场景开始时从租户配置端点解析凭据。

// TenantCredentialManager.cs
using Convai.Runtime.Components;
using Convai.Runtime.Core;
using Convai.Runtime.Core.Configuration;
using UnityEngine;

public class TenantCredentialManager : ConvaiManager
{
    [SerializeField] private TenantConfigService _configService;

    private string _apiKey;
    private string _serverUrl = "https://live.convai.com";

    protected override async void Awake()
    {
        TenantConfig config = await _configService.LoadAsync();
        _apiKey    = config.ConvaiApiKey;
        _serverUrl = config.ConvaiServerUrl ?? _serverUrl;
        base.Awake();
    }

    protected override ConvaiRuntimeBuilder CreateRuntimeBuilder()
    {
        ConvaiRuntimeBuilder builder = base.CreateRuntimeBuilder();
        builder.UseConfig(new ConvaiBootstrapConfigSnapshot(_apiKey, _serverUrl));
        return builder;
    }
}

故障排除

症状	可能原因	修复
[ConvaiManager] 无法启动：适配器未初始化。 在 Console 中	BuildRuntime() 在凭据解析之前运行	请确保在以下调用之前完成凭据获取： base.Awake() 被调用。
会话已连接，但 Convai 立即返回身份验证错误	传入快照的 API 密钥为空或不正确	记录已解析的密钥 长度 （不是值本身），以确认其在构建前已填充。
IsValid 返回 false 在配置快照上	apiKey 或 serverUrl 为 null 或空	在你的解析方法中添加空值检查和回退逻辑。
ConvaiSettings.Instance 在构建中为 null	ConvaiSettings.asset 不存在于 Assets/Resources/	仅将 ConvaiSettings.Instance 在编辑器/开发环境中作为回退；在生产构建中切勿将其作为唯一来源。

下一步

自定义身份提供程序自定义持久化提供程序