编写自定义 token 提供器

注册自定义凭据提供器，使你的后端为每次连接自动颁发短期 Convai 身份验证 token。

实现 IConvaiAuthTokenProvider 当你的项目已经有一个后端或登录层，可以生成 Convai 身份验证令牌，并且你希望 SDK 在每次连接时自动调用它时使用本页。当你的项目处于身份验证令牌模式，并且你希望在不修改各调用点连接代码的情况下完成令牌解析时，也使用本页。

前提条件

• 项目的 ConvaiSettings 资源文件有 AuthMode 设置为 AuthToken。另请参见 配置 Auth Token 模式.
• 一个后端端点或 SDK，用于返回一个短时有效的 Convai 身份验证令牌（一个 apiAuthToken）供已登录的玩家使用。

实现该接口

IConvaiAuthTokenProvider 只有一个方法：

public interface IConvaiAuthTokenProvider
{
    Task<AuthTokenResult> GetTokenAsync(CancellationToken cancellationToken);
}

SDK 会调用 GetTokenAsync 每次新的房间连接尝试都会调用一次。返回 AuthTokenResult.Succeeded(token, expiresAtUtc) 成功时，或 AuthTokenResult.Failed(errorMessage) 当无法解析令牌时。 expiresAtUtc 是可选的。

Assets/Scripts/MyAuthTokenProvider.cs

using System;
using System.Threading;
using System.Threading.Tasks;
using Convai.Runtime.Core.Configuration;

public sealed class MyAuthTokenProvider : IConvaiAuthTokenProvider
{
    public async Task<AuthTokenResult> GetTokenAsync(CancellationToken cancellationToken)
    {
        try
        {
            string token = await MyBackend.RequestConvaiTokenAsync(cancellationToken);
            return string.IsNullOrWhiteSpace(token)
                ? AuthTokenResult.Failed("我的后端返回了空令牌。")
                : AuthTokenResult.Succeeded(token);
        }
        catch (Exception exception)
        {
            return AuthTokenResult.Failed($"我的后端请求失败（{exception.GetType().Name}）。");
        }
    }
}

IConvaiAuthTokenProvider 实现不得记录或持久化返回的令牌。请将其视为仅限于单次连接尝试的短时密钥。

在连接之前注册提供程序

使用 ConvaiAuthTokenProviderRegistry 在首次连接尝试之前，通常在一个早期的 Awake:

using Convai.Runtime.Core.Configuration;
using UnityEngine;

public sealed class AuthBootstrap : MonoBehaviour
{
    private MyAuthTokenProvider _provider;

    private void Awake()
    {
        _provider = new MyAuthTokenProvider();
        ConvaiAuthTokenProviderRegistry.Register(_provider);
    }

    private void OnDestroy()
    {
        ConvaiAuthTokenProviderRegistry.Unregister(_provider);
    }
}

ConvaiAuthTokenProviderRegistry.Register 替换当前已注册的任意提供程序。 Unregister(provider) 仅当它仍是当前活动注册时才会将其移除； Unregister() 不带参数的 Clear() 都会移除当前活动的提供程序。

ConvaiAuthTokenProviderRegistry 是一个静态、进程本地的注册，会在 RuntimeInitializeLoadType.SubsystemRegistration。这会在每次域重新加载以及每次进入 Play 模式时运行，因此一次注册的提供程序不会保留——每次你的引导脚本运行时都要重新注册提供程序，不要假设一次调用就足够了。

使用委托处理简单情况

对于只需要一次异步查询的提供程序，将一个 lambda 包装在 DelegateAuthTokenProvider 而不是编写完整的类：

using Convai.Runtime.Core.Configuration;

ConvaiAuthTokenProviderRegistry.Register(
    new DelegateAuthTokenProvider(async cancellationToken =>
        await MyBackend.RequestConvaiTokenAsync(cancellationToken)));

DelegateAuthTokenProvider 封装一个 Func<CancellationToken, Task<string>>。如果出现以下情况则会失败： AuthTokenResult.Failed 如果委托返回 null、空任务或空字符串，因此你的委托只需返回令牌字符串或抛出。

验证设置

进入 Play 模式并连接一个角色。如果提供程序解析正确，连接会在没有任何身份验证相关错误的情况下继续。如果解析失败，连接会显示来自 AuthTokenResult.Failed 通过正常连接错误路径。

下一步

使用现有 auth token 连接身份验证脚本参考身份验证故障排查