Kauth.Sdk 1.0.1

Kauth.Sdk C# 对接文档

官网：https://kauth.cn
包名：Kauth.Sdk（Install-Package Kauth.Sdk / dotnet add package Kauth.Sdk）
目标框架：.NET 8

加密、签名由 SDK 内部完成，作者只调公开方法。KauthClient 是实例：一份配置一份 token，可多开，不要做成进程级单例。

所有接口返回 KauthResult / KauthResult<T>：

1. 快速对接

1.1 安装

dotnet add package Kauth.Sdk

Visual Studio：右键项目 → 管理 NuGet 程序包 → 搜索 Kauth.Sdk。

1.2 初始化

程序 ID、程序密钥、RSA 公钥在商家后台 程序管理 / 密钥配置。

using Kauth.Sdk;
using Kauth.Sdk.Models;

var client = new KauthClient(new KauthOptions
{
    ApiDomain = "https://api.kauth.cn",   // 接入点
    ProgramId = "你的程序ID",
    ProgramSecret = "你的程序密钥",
    MerchantPublicKey = "你的RSA公钥",   // X.509 Base64，可带 PEM 头
    Timeout = TimeSpan.FromSeconds(30)     // 可选，默认 30 秒
});

建议先调一次 GetProgramDetailAsync()。返回 code=200 说明网络和签名都正常。

1.3 登录

三种登录成功后，SDK 会自动把 token 写到 client.Token，后续心跳、用户信息等会自动带上。

卡密登录（最常用）：

var login = await client.KaLoginAsync(new KaLoginRequest
{
    KaPwd = "卡密",
    DeviceId = DeviceId.GetDefault(), // 绑定设备请换成你自己稳定的设备码
    PlatformType = "windows"           // 可选：windows / android / ios 等
});

if (!login.IsSuccess)
{
    // login.Code / login.Message
    return;
}

var token = login.Data?.Token;
var nick = login.Data?.NickName;

账号密码登录：

var login = await client.PwdLoginAsync(new PwdLoginRequest
{
    LoginName = "账号",
    Password = "密码",
    DeviceId = DeviceId.GetDefault()
});

试用登录：

var login = await client.TrialLoginAsync(new TrialLoginRequest
{
    DeviceId = DeviceId.GetDefault(),
    PlatformType = "windows"
});

登录需要验证码时：先 GetCaptchaAsync()，把返回的 Uuid 和用户输入的验证码填进 CaptchaUuid / CaptchaCode。

DeviceId.GetDefault() 只是可选默认值（Windows 用 MachineGuid 的 MD5）。卡密绑定以你传入的值为准，请自己生成并持久化设备码。

2. 保持心跳

登录成功后必须启用心跳。SDK 内部调 pong，作者监听事件，在心跳失败时停软件。

建议间隔 ≥ 2 分钟。小于 30 秒会被强制改成 2 分钟。

2.1 判断逻辑（SDK 已实现）

每次心跳结果按下表处理：

pong 返回
  ├─ Code == 200
  │     成功。网络失败计数清零，继续下一次。
  │
  ├─ Code != 200 且能拿到服务端错误码（Code > 200，如 401/403）
  │     立即心跳失败，停止心跳。
  │     典型：token 失效、卡密被停、被踢下线。
  │
  └─ 网络异常（Code == 0，或超时、断网、Code < 200）
        失败计数 +1。
        连续次数 < maxFailures → 继续下一次。
        连续次数 ≥ maxFailures → 也算心跳失败，停止心跳。
        中途只要有一次 200，计数清零。

默认 maxFailures = 3（连续 3 次网络失败）。

2.2 推荐写法

client.Heartbeat.Changed += (_, e) =>
{
    switch (e.Event)
    {
        case HeartbeatEvent.Success:
            // 心跳正常，可刷新 UI「在线」
            break;

        case HeartbeatEvent.ServerFail:
            // 服务端明确失败（错误码非 200），立即停软件
            MessageBox.Show($"心跳失败：{e.Code} {e.Message}");
            Application.Exit();
            break;

        case HeartbeatEvent.NetworkFail:
            // 网络异常，尚未达到上限。e.FailureCount 为当前连续次数
            break;

        case HeartbeatEvent.Stopped:
            // 心跳已停止：手动 Stop、服务端失败、或网络连续失败超限
            if (e.Code != 0 || e.FailureCount > 0)
            {
                MessageBox.Show($"心跳已停止：{e.Message}");
                Application.Exit();
            }
            break;
    }
};

client.Heartbeat.Start(
    interval: TimeSpan.FromMinutes(2),
    maxFailures: 3   // 网络连续失败超过 3 次 → 心跳失败
);

软件退出时：

client.Heartbeat.Stop();
client.Dispose();

手动 Stop() 也会收到 Stopped（Code=0，Message=手动停止）。用一个标志区分「用户点退出」和「心跳失败」，避免误弹窗。

3. SDK API 一览

命名空间：Kauth.Sdk、Kauth.Sdk.Models。
未注明的接口登录后才可调（需要 Token）。

3.1 登录与账号

LoginResponse：UserId, NickName, Token, PongInterval, VmpSerial。

3.2 登录后状态

UserInfo：UserId, ServerExpireTime, ServerRemainNum, ServerType, Trial。

3.3 设备解绑

3.4 程序与时间

无需登录即可调用，适合启动时探测配置是否正确。

3.5 自定义配置

3.6 远程变量 / 远程数据 / 云函数

CallFunctionParam：ParamName, ParamValue。

3.7 脚本

3.8 其它成员

窗口示例：examples/KaWin。控制台示例：examples/KaLogin。