快速开始

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

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

接入步骤

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

Web SDK 接入

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

1. 引入 SDK

<script src="http://127.0.0.1:443/sdk/jiuban_auth.js"></script>

2. 初始化并验证

JavaScript

// 初始化
JiubanAuth.init({
    serverUrl: 'http://127.0.0.1:443/api',
    appKey: 'YOUR_APP_KEY',
    appSecret: 'YOUR_APP_SECRET' // 必须，用于签名验证
});

// 验证卡密
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="http://127.0.0.1:443/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>
        JiubanAuth.init({ 
            serverUrl: 'http://127.0.0.1:443/api',
            appKey: 'YOUR_APP_KEY',
            appSecret: 'YOUR_APP_SECRET' // 必填，用于签名
        });
        
        // 页面加载时检查设备
        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、timestamp 和 sign 参数以进行安全验证。

签名算法： sign = SHA256(app_key + app_secret + timestamp)
注：timestamp 为当前时间戳（精确到秒）。请务必保证客户端时间准确，与服务器误差不得超过 10 分钟。

时间同步机制：

若客户端时间偏差过大，接口会返回 HTTP 403 并在响应包含 server_time 字段。客户端应捕获此错误并提示用户校准时间，或使用服务器时间进行修正。

Python 签名示例

import hashlib
import time

app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
timestamp = str(int(time.time()))

# 生成签名
raw_str = app_key + app_secret + timestamp
sign = hashlib.sha256(raw_str.encode('utf-8')).hexdigest()

print(f"Sign: {sign}, Timestamp: {timestamp}")

1. 应用初始化 & 状态检查

App 启动时由于一次性获取版本信息、公告和当前授权状态。支持传入卡密进行“自动激活”。

POST /api/init

curl -X POST http://127.0.0.1:443/api/init \
-H "Content-Type: application/json" \
-d '{
    "app_key": "YOUR_APP_KEY",
    "timestamp": "1701234567",
    "sign": "SIGNATURE",
    "device_id": "unique-device-id",
    "card_code": "OPTIONAL_CARD_CODE" 
}'

请求参数

参数名	类型	说明
app_key	string	应用识别码
device_id	string	设备唯一标识
card_code	string	(可选) 传入卡密可尝试自动激活
sign	string	签名

响应示例

{
    "code": 0,
    "msg": "Success",
    "data": {
        "status": "active", // active=已激活, expired=已过期, none=未激活
        "expire_time": "2025-12-31 23:59:59",
        "version": "1.0.0",
        "download_url": "https://example.com/app.exe",
        "notice": "应用公告...",
        "popup_announcement": "弹窗内容..."
    }
}

2. 用户手动激活

当初始化返回状态不仅用时，用户输入卡密调用此接口。

POST /api/activate

curl -X POST http://127.0.0.1:443/api/activate \
-H "Content-Type: application/json" \
-d '{
    "app_key": "YOUR_APP_KEY",
    "timestamp": "...",
    "sign": "...",
    "device_id": "unique-device-id",
    "code": "CARD-CODE-XXXX"
}'

响应示例

{
    "code": 0,
    "msg": "激活成功",
    "data": {
        "expires_at": "2025-12-31 23:59:59"
    }
}

3. 心跳保活与状态监测

建议每 3-5 分钟调用一次。此接口会实时检查卡密状态（是否过期/冻结/解绑）。

POST /api/heartbeat

curl -X POST http://127.0.0.1:443/api/heartbeat \
-H "Content-Type: application/json" \
-d '{
    "app_key": "YOUR_APP_KEY",
    "timestamp": "...",
    "sign": "...",
    "device_id": "unique-device-id",
    "code": "CARD-CODE-OPTIONAL" 
}'

响应示例 (正常)

{ 
    "code": 0, 
    "msg": "success",
    "data": {
        "expires_at": "2025-12-31 23:59:59"
    }
}

响应示例 (异常 - 需立即下线)

{ 
    "code": 1, 
    "msg": "卡密已被冻结，请联系管理员" 
}

安全提示： 客户端在收到心跳返回 code: 1 时，应立即停止服务并强制用户退出。这是服务器端强制即时封禁/踢人的关键机制。

4. 设备解绑

调用此接口可解绑指定卡密。注意：只能解绑属于当前 AppKey 的卡密。

POST /api/unbind

curl -X POST http://127.0.0.1:443/api/unbind \
-H "Content-Type: application/json" \
-d '{
    "app_key": "YOUR_APP_KEY",
    "timestamp": "...",
    "sign": "...",
    "card_code": "CARD-CODE-TO-UNBIND"
}'

响应示例

{
    "code": 0, 
    "msg": "解绑成功，扣除0小时", 
    "success": true,
    "expires_at": "..."
}

iOS SDK 接入

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

1. 导入 SDK

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

2. 初始化与调用

Objective-C

#import <JiubanAuth/JiubanAuth.h>

// 1. 初始化 (通常在 AppDelegate didFinishLaunchingWithOptions)
[[JiubanAuth shared] initWithServerUrl:@"http://127.0.0.1:443/api" 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 @"http://127.0.0.1:443/api"
#define kAppKey @"YOUR_APP_KEY"      // 填入您的 AppKey
#define kAppSecret @"YOUR_APP_SECRET" // 填入您的 AppSecret

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 中
// 参数: Context, ServerURL, AppKey, AppSecret
JiubanAuth.getInstance().init(context, "http://127.0.0.1:443/api", "YOUR_APP_KEY", "YOUR_APP_SECRET");

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。
建议动作： 比较本地版本号，如低于服务器版本，弹出更新提示框。

Webhook 通知

当发生特定事件（如设备激活）时，系统会向您配置的 URL 发送 POST 请求。

1. Payload 结构

{
    "event": "activation",
    "timestamp": "2023-10-27T10:00:00Z",
    "data": {
        "key_code": "XXXX....XXXX",
        "device_id": "dev...",
        "expires_at": "2024-01-01 00:00:00"
    }
}

2. 签名验证 (Headers)

如果配置了 Webhook Secret，请求头包含 X-Webhook-Signature。

算法：HMAC-SHA256(secret, body_json_string)

错误码说明

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

业务逻辑错误码 (API: /api/init)

code	说明	解释
0	成功	请求成功，返回 `data` 数据。
1	业务失败	验证失败、设备未激活、卡密过期等。具体查看 `msg` 字段。
401	AppKey 无效	`app_key` 不正确，请检查配置。
403	签名错误	`sign` 校验失败，请检查签名算法。

HTTP 状态码

代码	说明	建议
200	OK	请求成功，请解析 JSON Body 判断业务结果。
429	Too Many Requests	请求频率过高，触发限流。请降低请求频率。
500	Internal Server Error	服务器内部错误，请稍后重试。

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

接入指南

其他

快速开始

下载完整 SDK 包

接入步骤

Web SDK 接入

1. 引入 SDK

2. 初始化并验证

3. 完整示例

Web API 接入

应用鉴权说明

1. 应用初始化 & 状态检查

请求参数

响应示例

2. 用户手动激活

响应示例

3. 心跳保活与状态监测

响应示例 (正常)

响应示例 (异常 - 需立即下线)

4. 设备解绑

响应示例

iOS SDK 接入

1. 导入 SDK

2. 初始化与调用

1. 源码配置

2. 编译与注入

Android SDK 接入

1. 添加依赖

2. 调用验证

功能集成指南

冻结与解冻

客户端处理：

设备换绑

客户端处理：

过期处理

客户端处理：

版本更新

数据获取：

Webhook 通知

1. Payload 结构

2. 签名验证 (Headers)

错误码说明

业务逻辑错误码 (API: /api/init)

HTTP 状态码