快速开始

欢迎使用久伴验证平台开发者文档。我们提供了简单易用的 API 和 SDK，帮助您快速将验证功能集成到您的应用中。

请先前往控制台获取您的 API 密钥和应用 ID。

接入步骤

注册账号 - 前往注册页面创建开发者账号
获取密钥 - 登录控制台，获取您的应用 ID
下载 SDK - 根据您的平台下载对应的 SDK
集成验证 - 按照下方文档集成验证功能
测试上线 - 使用测试卡密验证后正式上线

Web SDK 接入

适用于网页应用，只需引入 JavaScript 文件即可快速集成。

1. 引入 SDK

<script src="https://verify.9990066.xyz/sdk/jiuban_auth.js"></script>

2. 初始化并验证

JavaScript

// 初始化
// 初始化
JiubanAuth.init({
    serverUrl: 'https://verify.9990066.xyz',
    appKey: 'YOUR_APP_KEY',
    appSecret: '' // 可选，暂未启用签名
});

// 验证卡密
async function verifyLicense(cardCode) {
    try {
        const result = await JiubanAuth.verify(cardCode);
        if (result.success) {
            console.log('验证成功，到期时间:', result.expire_time);
            // 允许使用功能
        } else {
            console.log('验证失败:', result.message);
            // 提示用户
        }
    } catch (error) {
        console.error('网络错误:', error);
    }
}

// 检查设备状态（自动验证）
async function checkDevice() {
    const result = await JiubanAuth.checkDevice();
    if (result.success) {
        console.log('设备已授权，到期时间:', result.expire_time);
    } else {
        // 需要用户输入卡密
        showVerificationModal();
    }
}

3. 完整示例

HTML

<!DOCTYPE html>
<html>
<head>
    <title>我的应用</title>
    <script src="https://verify.9990066.xyz/sdk/jiuban_auth.js"></script>
</head>
<body>
    <div id="app" style="display:none;">
        <!-- 您的应用内容 -->
    </div>
    
    <div id="verify-modal">
        <input type="text" id="card-code" placeholder="请输入卡密">
        <button onclick="verify()">验证</button>
    </div>

    <script>
    <script>
        JiubanAuth.init({ 
            serverUrl: 'https://verify.9990066.xyz',
            appKey: 'YOUR_APP_KEY'
        });
        
        // 页面加载时检查设备
        JiubanAuth.checkDevice().then(result => {
            if (result.success) {
                document.getElementById('verify-modal').style.display = 'none';
                document.getElementById('app').style.display = 'block';
            }
        });

        function verify() {
            const code = document.getElementById('card-code').value;
            JiubanAuth.verify(code).then(result => {
                if (result.success) {
                    alert('验证成功！');
                    location.reload();
                } else {
                    alert('验证失败: ' + result.message);
                }
            });
        }
    </script>
</body>
</html>

Web API 接入

适用于所有支持 HTTP 请求的平台，包括 Web、Python 脚本、游戏引擎等。

应用鉴权说明

所有 API 请求必须携带 app_key 参数以进行应用绑定验证。

注：目前暂未强制开启 AppSecret 签名验证，您可以忽略 sign 参数。

1. 初始化/验证卡密

应用初始化并验证卡密，支持应用绑定卡密验证。

POST /api/v1/init

curl -X POST https://verify.9990066.xyz/api/v1/init \
-H "Content-Type: application/json" \
-d '{
    "app_key": "YOUR_APP_KEY",
    "device_id": "unique-device-id",
    "card_code": "XXXX-XXXX-XXXX-XXXX"
}'

请求参数

参数名	类型	说明
app_key	string	应用识别码（控制台获取）
device_id	string	设备唯一标识
card_code	string	卡密（首次验证时必填）

响应示例

// 成功响应
{
    "code": 0,
    "msg": "Success",
    "data": {
        "status": "active",
        "expire_time": "2025-12-31 23:59:59",
        "notice": "应用公告内容",
        "version": "1.0.0",
        "download_url": "https://example.com/update"
    }
}

// 失败响应
{
    "code": 1,
    "msg": "此卡密不适用于当前应用"
}

卡密绑定： 如果卡密在生成时绑定了特定应用，则只能在该应用中使用。通用卡密（未绑定应用）可在任何应用中使用。

2. 检查设备状态

检查当前设备是否已有效授权（无需卡密）。

POST /api/check_device

curl -X POST https://verify.9990066.xyz/api/check_device \
-H "Content-Type: application/json" \
-d '{
    "app_key": "YOUR_APP_KEY",
    "device_id": "unique-device-id-123"
}'

响应示例

{
    "success": true,
    "message": "设备已激活",
    "expires_at": "2025-12-31 23:59:59"
}

3. 错误码对照表

code	说明
0	成功
1	验证失败（卡密无效/过期/不适用）
401	无效的 App Key
403	签名验证失败

iOS SDK 接入

我们提供两种 iOS 接入方式，分别适用于原生 App 开发和越狱/注入插件开发。

1. 导入 SDK

将 JiubanAuth.framework (或源代码) 拖入您的 Xcode 项目中。

2. 初始化与调用

Objective-C

#import <JiubanAuth/JiubanAuth.h>

// 1. 初始化 (通常在 AppDelegate didFinishLaunchingWithOptions)
[[JiubanAuth shared] initWithServerUrl:@"https://verify.9990066.xyz/api/v1" appKey:@"YOUR_APP_KEY"];

// 2. 检查状态
- (void)checkLicense {
    [[JiubanAuth shared] checkStatus:^(BOOL success, NSString *msg) {
        if (success) {
            NSLog(@"验证成功");
            // 进入 App 主逻辑
        } else {
            // 未激活，弹出输入框
            [self showInputAlert];
        }
    }];
}

// 3. 激活设备
- (void)activate:(NSString *)code {
    [[JiubanAuth shared] activateWithCode:code completion:^(BOOL success, NSString *msg) {
        if (success) {
            NSLog(@"激活成功");
        } else {
            NSLog(@"激活失败: %@", msg);
        }
    }];
}

1. 源码配置

适用于 Tweak 开发。SDK 文件包含 + (void)load 方法，注入即自动运行。

打开 JiubanAuth.m 源文件，修改顶部的宏定义：

JiubanAuth.m

// 配置项
#define kServerUrl @"https://verify.9990066.xyz/api/v1"
#define kAppKey @"YOUR_APP_KEY"      // 填入您的 AppKey
#define kAppSecret @""               // 留空即可

2. 编译与注入

使用 Theos 或 Xcode 编译生成 .dylib 文件，并通过注入工具 (如 Cydia Substrate) 注入到目标 App 中。

功能特性：

自动启动： 注入后自动运行，无需额外调用代码。
强制验证： 如果未激活，会自动在目标 App 顶层弹出不可取消的验证框。
设备绑定： 自动获取 IDFA/IDFV 进行设备绑定。

Android SDK 接入

适用于 Android 原生应用开发。

1. 添加依赖

在您的模块级 build.gradle 中添加：

dependencies {
    implementation 'com.jiuban.auth:sdk:1.0.0'
}

2. 调用验证

Java

import com.jiuban.auth.JiubanAuth;
import com.jiuban.auth.Callback;

// 在 MainActivity 或 Application 中
// 在 MainActivity 或 Application 中
// 参数: Context, ServerURL, AppKey, AppSecret(可选)
JiubanAuth.getInstance().init(context, "https://verify.9990066.xyz/api/v1", "YOUR_APP_KEY", "");

JiubanAuth.getInstance().activate("用户卡密", new JiubanAuth.AuthCallback() {
    @Override
    public void onSuccess(String msg) {
        // 验证通过
        Toast.makeText(context, msg, Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onFail(String errorMsg) {
        // 验证失败
        Toast.makeText(context, "验证失败: " + errorMsg, Toast.LENGTH_LONG).show();
    }
});

功能集成指南

本节详细介绍了久伴验证平台的核心功能逻辑及客户端处理建议。

冻结与解冻

管理员可在后台对违规卡密进行冻结操作。冻结后，所有关联设备将无法通过验证。

客户端处理：

触发条件： API 返回 code: 1 且 msg 包含 "冻结"。
建议动作： 弹出不可取消的弹窗，提示用户联系客服解冻。
自动恢复： 管理员解冻后，再次调用验证接口即可自动恢复正常。

设备换绑

默认开启设备绑定保护。当卡密在由 A 设备登录后，无法直接在 B 设备使用。

客户端处理：

触发条件： API 返回 code: 1 且 msg 包含 "设备" 或 "绑定"。
建议动作： 提示用户"设备不匹配"，并引导扣除时间换绑或联系管理员。
解绑操作： 管理员在后台手动解绑后，新设备即可绑定成功。

过期处理

卡密到期后将自动失效。系统精确到秒级控制。

客户端处理：

触发条件： API 返回 code: 1 且 msg 包含 "过期"。
建议动作： 提示用户"卡密已过期"，并提供购买链接或续费入口。

版本更新

管理员可在后台发布新版本及下载链接。

数据获取：

API 字段： 成功响应中的 data.version 和 data.download_url。
建议动作： 比较本地版本号，如低于服务器版本，弹出更新提示框。

错误码说明

以下是 API 可能返回的所有状态码及其含义。

成功状态

代码	说明	响应示例
200	请求成功	`{"success": true, "message": "验证成功", "expire_time": "2024-12-31"}`

客户端错误

代码	说明	处理建议
400	参数缺失	检查请求体中是否包含 `code` 和 `device_id` 参数
401	卡密无效或已过期	提示用户检查卡密是否正确，或引导用户续费
403	设备不匹配	该卡密已绑定其他设备，请联系管理员解绑或购买新卡密
404	卡密不存在	检查卡密格式是否正确，可能输入有误
423	卡密已被冻结	该卡密已被管理员冻结，请联系客服处理
429	请求过于频繁	触发速率限制，请稍后再试（建议等待 1 分钟）

服务器错误

代码	说明	处理建议
500	服务器内部错误	服务器发生意外错误，请稍后重试或联系技术支持
503	服务暂时不可用	服务器正在维护，请稍后再试

最佳实践： 建议在客户端实现重试机制，对于 5xx 错误可尝试延迟重试（指数退避），对于 4xx 错误应直接提示用户。

接入指南

其他

快速开始

下载完整 SDK 包

接入步骤

Web SDK 接入

1. 引入 SDK

2. 初始化并验证

3. 完整示例

Web API 接入

应用鉴权说明

1. 初始化/验证卡密

请求参数

响应示例

2. 检查设备状态

响应示例

3. 错误码对照表

iOS SDK 接入

1. 导入 SDK

2. 初始化与调用

1. 源码配置

2. 编译与注入

Android SDK 接入

1. 添加依赖

2. 调用验证

功能集成指南

冻结与解冻

客户端处理：

设备换绑

客户端处理：

过期处理

客户端处理：

版本更新

数据获取：

错误码说明

成功状态

客户端错误

服务器错误